Design an Authentication and Authorization System (OAuth 2.0/SSO)

SAML 2.0 vs OIDC: When to Use Each

Next we walk through each component on the diagram. Evaluating SAML vs OIDC is the primary architectural fork when designing modern single sign-on systems.

OIDC is the modern default for SaaS and mobile; SAML persists for enterprise IdP integrations; state which you would pick for this use case.

OIDC (OpenID Connect) (Recommended) - Modern default:
  - JSON/JWT tokens, REST-friendly, mobile-native
  - Built on OAuth 2.0 authorization code + PKCE
  - Use for: SaaS apps, mobile, SPAs, microservices
  - Flow: /authorize → code → /token → id_token + access_token

SAML 2.0 - Enterprise legacy:
  - XML assertions, browser POST binding, heavier
  - Use for: enterprise SSO (Okta/ADFS → legacy apps)
  - Flow: SP-initiated → IdP login → SAML assertion POST to /acs

Hybrid architecture:
  - OIDC for customer-facing apps and API access
  - SAML bridge for enterprise customers requiring federation
  - Same user store; map SAML NameID → internal user_id
  - Staff probe: "How do you handle SAML clock skew?" → NotBefore/NotOnOrAfter
    with 5-min tolerance; NTP sync on IdP and SP

JWKS Rotation and Key Compromise

JWKS rotation and key compromise response is a staff-level probe: explain the kid header, overlap window, and token_version bump on incident.

Signing keys (RS256):
  - Publish public keys at /.well-known/jwks.json with kid header
  - Rotate monthly: add new key, sign new tokens with new kid
  - Old keys remain in JWKS for verification-only (30-day overlap)

Gateway caches JWKS for 1 hour. On unknown kid:
  1. Force refresh JWKS (don't wait for TTL)
  2. Retry validation once
  3. If still unknown → 401 (possible key compromise or misconfig)

Key compromise incident:
  1. Revoke compromised kid immediately from JWKS
  2. Bump token_version for all users (invalidates all access tokens)
  3. Force re-login; rotate refresh tokens
  4. Audit log: which tokens signed with compromised kid

OAuth 2.0 Authorization Code Flow with PKCE

PKCE is mandatory for public clients: explain why code_verifier prevents authorization code interception before walking through the six-step flow.

1. Client generates code_verifier + code_challenge = SHA256(code_verifier)
2. Client redirects to auth server: GET /authorize?response_type=code&code_challenge=...
3. User authenticates (login + MFA if enabled)
4. Auth server redirects back with authorization code
5. Client exchanges code for tokens at POST /token
6. Auth server validates code + verifier, returns tokens

Why PKCE? Prevents authorization code interception attack.
Without PKCE: intercepted code can be exchanged for tokens.
With PKCE: code exchange requires code_verifier that only original client has.

JWT Token Structure and Validation

Access token (JWT):
  Header: { "alg": "RS256", "kid": "key-2026-03" }
  Payload: {
    "sub": "user-uuid", "iss": "https://auth.example.com",
    "aud": "api.example.com", "exp": 1710403200,
    "scope": "read write", "roles": ["admin"],
    "tenant_id": "tenant-uuid"
  }

Validation at API Gateway (stateless, < 1ms):
  1. Decode JWT -> get kid, look up public key from JWKS
  2. Verify signature, check exp, iss, aud
  3. Extract roles/permissions

Token revocation:
  a. Short expiry (15 min) + refresh tokens
  b. Token blacklist in Redis
  c. Version counter in JWT + DB

RBAC: Role-Based Access Control

Hierarchy: User -> has -> Roles -> have -> Permissions

Example:
  User "Alice" -> roles: ["editor", "viewer"]
  Role "editor" -> permissions: ["article:create", "article:edit"]
  Role "viewer" -> permissions: ["article:read"]

Permission format: resource:action
  Storage: user_roles + role_permissions in PostgreSQL
  Cache: in JWT + Redis