System Design Cases
OAuth 2.0 + OpenID Connect
OAuth 2.0 + OpenID Connect: Authorization Code + PKCE flow, M2M Client Credentials, refresh token rotation with theft detection, ADR comparing OAuth/OIDC vs SAML vs custom session-based auth.
OAuth 2.0 and OpenID Connect: protocol boundaries and secure flows
OAuth delegates access to protected resources; OpenID Connect adds an authentication assertion for the client. The client, authorization server, resource server, browser, and their tokens remain distinct security principals.
Security invariants
- OAUTH-C1: OAuth is an authorization framework; OpenID Connect adds an ID Token containing claims about an authentication event.
- OAUTH-C2: Redirect-based clients use authorization code flow with transaction-specific PKCE; S256 is the method that does not expose the verifier.
- OAUTH-C3: Redirect URIs are exact-matched and clients bind the response to state or nonce and the expected issuer to resist CSRF and mix-up.
- OAUTH-C4: ID Token validation includes exact issuer, client audience, expiry, signature and nonce when a nonce was sent.
- OAUTH-C5: Resource servers reject access tokens not audience-restricted and authorized for that resource and action.
- OAUTH-C6: Refresh tokens for public clients are sender-constrained or rotated, and reuse is handled as a compromise signal.
Trust-boundary map
| Component | Responsibility |
|---|---|
browser | User Agent |
client | OAuth/OIDC Client |
authorization-endpoint | Authorization Endpoint |
token-endpoint | Token Endpoint |
resource-server | Resource Server |
issuer-keys | Pinned Issuer Metadata and JWKS |
session-store | Client Session and Transaction Store |
attacker | Malicious Site or Token Thief |
Topology edges represent authenticated or otherwise explicit communication paths. Responses reuse those physical paths in reverse; no response-only or bypass edges are added.
Executable scenarios
authorization-code-pkce — Authorization code with PKCE
A transaction-bound S256 challenge protects the code; the confidential exchange happens at the token endpoint.
oidc-id-token-validation — Validate the ID Token at the client
Signature, pinned issuer, client audience, expiry, and transaction nonce are all required; one successful check cannot replace the others.
access-token-boundary — Access token stays at the resource server
An access token authorizes a resource request; an ID Token is an authentication assertion for the client and is not an API bearer token.
redirect-and-mixup-rejection — Reject redirect and issuer mix-up
Exact redirect matching and issuer binding prevent an attacker from substituting an endpoint or exfiltrating the code.
code-interception-rejection — Intercepted code cannot be redeemed
PKCE binds the authorization code to a verifier that never travels in the front-channel authorization request.
refresh-token-reuse — Detect refresh token reuse
Public clients use rotation or sender-constraining; reuse of an invalidated family member is an incident signal, not another successful refresh.
wrong-audience-token — Reject a token for another API
A valid signature does not make a token valid for every resource; the resource server enforces its own audience and authority.
Operational and failure rules
- Every rejection path fails closed at the component that owns the decision; infrastructure failure is never converted into authentication, authorization, or integrity success.
- Retries preserve stable transaction identity, replay detection, bounded freshness, and audit context. A retry does not erase a prior success or compromise signal.
- Concurrent validation branches are independent checks. Completion requires every mandatory branch, and no check substitutes for another.
- Logs contain decision metadata and stable identifiers, not credentials, bearer tokens, cryptographic keys, or sensitive payloads.