Can this system reliably distinguish legitimate claimants from attackers under real production conditions?

Who is the claimant?
What evidence is presented?
Where is the evidence verified?
What makes the evidence valid?
What subject is produced?
How long does the subject remain authenticated?
How can authentication be revoked?
How is authentication observed?
How is the system recovered after compromise?

Authentication Architecture =
  Evidence Model
+ Verification Boundary
+ Continuity Mechanism
+ Revocation Model
+ Tenant/Context Binding
+ Observability
+ Operational Recovery

"We use JWT."
"We use Spring Security."
"We use Keycloak."
"We use MFA."

[ ] Credentials are never accepted from untrusted locations accidentally.
[ ] Passwords, OTPs, API keys, refresh tokens, and session ids are never logged.
[ ] Token validation does not depend on unsigned claims.
[ ] HMAC verification binds method, path, query, headers, timestamp, nonce, and body hash.
[ ] Client certificate identity is taken from verified TLS state, not a raw external header.

[ ] Password verification uses adaptive hashing.
[ ] Unknown account and bad credential paths are externally indistinguishable.
[ ] Rate limiting happens before expensive verification.
[ ] JWT validation checks signature, algorithm, issuer, audience, expiry, not-before, and tenant context.
[ ] OIDC login validates state and nonce.
[ ] SAML assertion validation checks signature, issuer, audience, destination, time window, and replay.

[ ] Session id rotates after login.
[ ] Session id rotates after step-up.
[ ] Session has idle and absolute expiry.
[ ] Access token TTL is short enough for risk model.
[ ] Refresh token rotation is atomic.
[ ] Refresh token reuse compromises the token family.

[ ] Tenant is explicitly resolved.
[ ] Tenant hint is cross-checked against authentication evidence.
[ ] User identity and service identity are not collapsed.
[ ] Delegation and impersonation are explicitly represented.
[ ] Authentication strength/auth level is available to sensitive workflows.

[ ] Signing keys can be rotated.
[ ] Sessions can be revoked by account, tenant, client, and incident scope.
[ ] API keys can be revoked without deploy.
[ ] Audit events are durable and queryable.
[ ] Incident runbooks exist for key leak, token leak, session compromise, IdP outage, and account takeover.

Key rotation
Audience validation
Issuer validation
Revocation strategy
Token leak response
Claim lifecycle
Tenant binding
Clock skew
JWKS cache behavior

Multiple login identifiers
External IdP subjects
Credential versions
Multiple authenticators
Sessions
Recovery methods
Tenant memberships
Service accounts
API clients
Audit evidence

Email can change.
Email can be reassigned.
Email can be unverified.
Email can collide across IdPs.
Email normalization is provider-specific.

issuer + subject

They are stripped at the edge.
They are injected only by trusted proxy.
Internal network prevents bypass.
Services enforce trust boundary.

Recovery flow
Session theft
MFA fatigue
SIM swap
OAuth consent abuse
Helpdesk reset
Device enrollment
Remembered devices

They lack correlation id.
They lack reason code.
They contain secrets.
They are sampled.
They are overwritten quickly.
They cannot answer incident questions.

Cookie attributes
Session timeout
Password hash cost
JWT audience
Allowed algorithms
JWKS cache
Error semantics
Rate limit thresholds
Audit events

How are identifiers normalized?
How is account enumeration prevented?
What hash algorithm and parameters are used?
How are parameters upgraded?
How is credential stuffing detected?
How is rate limiting dimensioned?
How is password reset protected?
What invalidates existing sessions after password change?
What is the support recovery path?

Where is session state stored?
Is session id rotated after login/step-up?
Are cookies Secure, HttpOnly, SameSite, Path-scoped?
Is CSRF protection enabled for unsafe browser requests?
What are idle and absolute timeouts?
How are sessions revoked?
How are concurrent sessions handled?
How is privilege drift prevented?

Who issues the token?
Who is the intended audience?
Which algorithms are accepted?
How are keys rotated?
What happens when JWKS endpoint is down?
How short is access token TTL?
Which claims are trusted?
How is tenant binding enforced?
What is the revocation story?

Is Authorization Code + PKCE used?
Is state validated?
Is nonce validated?
How is external identity linked?
Is email auto-linking forbidden or tightly controlled?
How is JIT provisioning governed?
How does logout work?
How are disabled/deprovisioned users handled?
What is the break-glass path during IdP outage?

Is the key shown only once?
Is the key stored hashed?
Is there a lookup prefix?
Are scopes and tenant stored server-side?
Does the key expire?
Can it be rotated without downtime?
Is last-used metadata recorded?
Can leaked keys be detected?

Is canonicalization precisely specified?
Are method/path/query/header/body bound?
Is timestamp checked?
Is nonce uniqueness enforced?
Is comparison constant-time?
Are proxy header mutations accounted for?
Are there golden test vectors?
How are secrets rotated?

Where does TLS terminate?
Which CA is trusted?
Which certificate fields map to service identity?
Is SAN validation explicit?
How are certs issued and rotated?
What happens when cert expires?
Can a service bypass the gateway?
How is client cert identity propagated safely?

Never migrate authentication without shadow telemetry.

Admin backdoor
Batch endpoint
Old mobile API
Support impersonation
Webhook shared secret
Basic Auth endpoint
Database direct access
Internal header trust

0 = absent or ad hoc
1 = implemented but inconsistent
2 = implemented consistently with tests
3 = implemented, tested, observed, and operated with runbook

0-10   = prototype risk
11-20  = fragile production
21-25  = acceptable with remediation plan
26-30  = strong production posture

Low-risk public account:
  Password + session + rate limit may be acceptable.

Internal business workflow:
  SSO/OIDC + session + CSRF + audit + step-up for sensitive operations.

Regulatory enforcement case management:
  Enterprise SSO + strong MFA/passkey + tenant binding + audit + step-up + break-glass runbook.

Machine-to-machine API:
  OAuth client credentials or mTLS + audience-scoped token.

High-risk webhook:
  HMAC request signing + nonce + timestamp + body hash.

Administrative operation:
  Recent authentication + step-up + reason capture + audit + dual control where needed.

subject_id
subject_type
tenant_id
auth_time
auth_level
factors
client_id
scopes / coarse grants
issuer
session_id / token_id

action
resource
ownership
case status
tenant policy
delegation
separation of duties
risk state
regulatory constraints

Putting business authorization into token claims permanently.

{
  "sub": "user-123",
  "can_approve_case_987": true
}

Token says who authenticated and at what assurance.
Authorization service decides whether current case state allows approval.

# Authentication Architecture Review

## 1. System Scope
- Applications:
- APIs:
- User types:
- Client types:
- Tenants:
- Environments:

## 2. Authentication Entry Points
| Entry Point | Client | Mechanism | Credential Transport | Trust Boundary |
|---|---|---|---|---|

## 3. Evidence Verification
| Mechanism | Verifier | Checks | Failure Response | Audit Event |
|---|---|---|---|---|

## 4. Subject Model
- Subject id:
- Account mapping:
- Tenant binding:
- Service identity:
- Delegation/impersonation:

## 5. Continuity
- Session/token type:
- TTL:
- Revocation:
- Rotation:
- Logout semantics:

## 6. Threat Model
| Threat | Control | Test | Owner |
|---|---|---|---|

## 7. Observability
- Audit events:
- Metrics:
- Alerts:
- Dashboards:
- Retention:

## 8. Operational Readiness
- Key rotation:
- Session purge:
- Token revocation:
- IdP outage:
- Break-glass:
- Incident runbook:

## 9. Open Risks
| Risk | Severity | Decision | Owner | Due Date |
|---|---|---|---|---|

## 10. Decision
- Approved:
- Approved with conditions:
- Rejected:

B2B SaaS app.
Browser users login via enterprise SSO.
Public API supports machine clients.
Admin portal performs high-risk tenant operations.
System is multi-tenant.

Browser login: OIDC Authorization Code + PKCE
Browser continuity: BFF session cookie, HttpOnly/Secure/SameSite
API access: audience-scoped JWT or opaque token
Machine clients: OAuth client credentials preferred; API key only for simpler integrations
High-risk webhooks: HMAC signing
Tenant model: issuer/client/claim/session binding
Admin step-up: WebAuthn/passkey or IdP MFA claim + recent auth check
Audit: durable auth event outbox

SPA storing long-lived access and refresh tokens in localStorage.
Email-only account linking across IdPs.
JWT accepted by all APIs without audience separation.
One shared API key per tenant.
Tenant selected only by dropdown after login.

Internal enforcement lifecycle/case management platform.
Sensitive workflows.
Audit defensibility required.
Human users mostly internal and partner agencies.
Case transitions have legal consequence.

Primary auth: Enterprise IdP / OIDC / SAML federation
Session: Server-side session via BFF/admin app
Step-up: Required for enforcement finalization, bulk export, permission elevation
Auth level: Stored in session and checked before sensitive workflows
Audit: Append-only structured auth events correlated with case events
Break-glass: Dual-controlled, alerting, time-bound
Service identity: mTLS or OAuth client credentials
Tenant/agency boundary: Explicit, not inferred from email domain only

A user authenticated to the platform is not automatically authorized to act on every case.

request.getHeader("X-User")
request.getHeader("X-Tenant")
JWT.decode(token)
claims.get("email") as account key
csrf.disable()
SessionCreationPolicy.STATELESS everywhere
localStorage.setItem("token")
logger.info("Authorization: {}", header)
new BCryptPasswordEncoder(4)
password.equals(storedHash)
Random instead of SecureRandom
@Async method reading SecurityContext implicitly
permitAll() on /auth/** without endpoint-specific review
catch Exception -> allow request

Password hash p95/p99 latency
Hash executor queue depth
Login rate limiter deny rate
Redis latency for session/token store
JWKS cache hit ratio
Token introspection latency
Audit outbox lag
IdP callback latency
Session store memory growth
Refresh rotation lock contention
API key lookup hot keys
HMAC body hashing cost for large payloads

Can we revoke all sessions for one account?
Can we revoke all sessions for one tenant?
Can we revoke all tokens for one client?
Can we rotate signing keys without downtime?
Can we detect refresh-token reuse?
Can we identify which API keys are unused?
Can we disable one IdP provider?
Can we operate during IdP outage?
Can we prove who authenticated before a sensitive action?
Can we find all auth events for a case/user/tenant/correlation id?
Can we purge leaked tokens from logs?
Can we notify affected users without revealing sensitive details?

Who authenticated
When they authenticated
Which method/factor they used
Which tenant/context they entered
Which session/token/client was used
Whether step-up occurred
Which policy was applied
What failed and why
Who changed credential or authenticator state
How incident response was executed

Completeness
Integrity
Correlation
Retention
Access control
Redaction
Reviewability

One users table.
Plain login endpoint.
No rate limit.
No audit.
No revocation.

Password hashing.
Session/JWT validation.
Some logging.
Basic logout.
Framework defaults.

Rate limiting.
Generic failures.
Session rotation.
JWT issuer/audience validation.
Refresh token rotation.
Audit events.
Security tests.

SSO/federation.
Multi-tenant binding.
MFA/step-up.
API client lifecycle.
Runbooks.
Dashboards.
Key rotation.
Incident drills.

Phishing-resistant auth.
Strong recovery controls.
Formal threat-control traceability.
Immutable audit pipeline.
Operational evidence.
Continuous security regression testing.
Separation-of-duty integration.

Local login vs external IdP
Session vs token
BFF vs SPA token storage
JWT vs opaque token
API key vs OAuth client credentials
HMAC vs mTLS
Gateway validation vs service validation
Tenant per realm vs tenant claim vs tenant table
Custom IdP vs Keycloak/managed IdP
Audit log vs audit event stream

If JWT is validated only at gateway,
then internal services trust propagated identity.
That requires strong network boundary and header stripping.
If those are weak,
services must validate tokens themselves or use signed internal identity assertions.

001-004: Understand identity, trust boundary, threat model, and Java landscape.
005-008: Understand request pipeline, Spring/Jakarta architecture, and identity domain model.
009-012: Build password authentication safely with state machine, hashing, enumeration defense, and rate limiting.
013-016: Model session and token authentication with browser/security boundary awareness.
017-018: Treat JWT and refresh tokens as lifecycle systems, not string formats.
019-021: Handle machine authentication with API keys, HMAC signing, and mTLS.
022-028: Understand OAuth/OIDC/federation/Keycloak/custom IdP trade-offs.
029-031: Add assurance with MFA, WebAuthn/passkeys, and risk-based authentication.
032-034: Carry authentication safely through microservices, events, and tenants.
035-038: Make authentication observable, testable, performant, and operable.
039-040: Assemble and review the production architecture.

Given a real system, choose and implement the right authentication architecture,
explain the trade-offs,
prove the invariants,
and operate it under failure.

Identity model
[ ] Account, identifier, credential, authenticator, session, token, API client, tenant are distinct concepts.
[ ] External identities are linked by issuer + subject.
[ ] Email is not the only account key.

Password auth
[ ] Adaptive hash.
[ ] Hash cost tuned.
[ ] Rate limit before hash.
[ ] Generic failure response.
[ ] Recovery flow hardened.

Session auth
[ ] Session id rotates after login and step-up.
[ ] Secure cookie attributes.
[ ] CSRF for browser writes.
[ ] Idle and absolute timeout.
[ ] Revocation by account/tenant/session.

Token auth
[ ] Issuer validated.
[ ] Audience validated.
[ ] Algorithm allowlisted.
[ ] Expiry and not-before checked.
[ ] Tenant binding checked.
[ ] JWKS cache behavior defined.

Refresh lifecycle
[ ] Opaque token.
[ ] Stored hashed.
[ ] Rotated atomically.
[ ] Reuse detected.
[ ] Family compromised on replay.

Federation
[ ] Authorization Code + PKCE.
[ ] State checked.
[ ] Nonce checked.
[ ] Account linking safe.
[ ] Deprovisioning handled.

Machine auth
[ ] API key lifecycle implemented.
[ ] HMAC canonicalization specified if used.
[ ] mTLS trust boundary documented if used.
[ ] Service identity separate from user identity.

Multi-tenancy
[ ] Tenant resolved explicitly.
[ ] Tenant hint checked against evidence.
[ ] Cross-tenant negative tests exist.

Observability
[ ] Structured audit events.
[ ] No secrets in logs.
[ ] Metrics for failures, latency, revocation, outbox.
[ ] Detection rules for abuse.

Operations
[ ] Key rotation runbook.
[ ] Token/session revocation runbook.
[ ] IdP outage runbook.
[ ] Break-glass account control.
[ ] Incident drills.

Testing
[ ] Negative tests.
[ ] Timing/enumeration regression.
[ ] Token confusion tests.
[ ] Session fixation tests.
[ ] Refresh replay tests.
[ ] Tenant isolation tests.

1. Authentication entrypoint inventory
2. Credential inventory
3. Session/token lifecycle diagram
4. Trust boundary diagram
5. Threat-to-control table
6. Top 10 authentication risks
7. 30-day remediation plan

Wrong issuer
Wrong audience
Expired token
Future nbf
Missing tenant
Wrong tenant
Unexpected algorithm
Unknown kid
ID token used as access token
Access token for another API

One succeeds.
One fails.
Family is marked compromised if reuse is detected after rotation.
Audit event is emitted.

Tenant A token on Tenant B URL
Tenant A session with Tenant B header
Tenant A API key on Tenant B endpoint
Tenant A OIDC issuer on Tenant B client config

JWT signing key suspected leaked.

Containment actions
Key rotation steps
Token revocation/expiry plan
Affected user/client scope
Communication plan
Audit queries
Post-incident hardening

1. Java Authorization Pattern
2. Policy-as-Code and ABAC/ReBAC
3. Secure Workflow Authorization for Case Management
4. Audit-Defensible State Machines
5. Identity Governance and Access Review
6. Cryptographic Key Management in Java Systems
7. Secure Multi-Tenant Architecture
8. Zero Trust Service-to-Service Architecture

Series: Learn Java Authentication Pattern
Parts: 001-040
Status: Complete
Final Part: 040 — Authentication Architecture Review

Mental model
Threat model
Java framework model
Domain model
Password/session/token/API-key/HMAC/mTLS/OIDC/MFA/passkey patterns
Microservice/event/multi-tenant propagation
Observability/testing/performance/operations
Reference implementation
Architecture review

Authentication is not proven by a successful login.
Authentication is proven by the system's behavior under invalid, hostile, ambiguous, expired, replayed, cross-tenant, compromised, and operationally degraded conditions.