OAuth 2.0 / OIDC (Deep Workflow)

OAuth solves delegated authorization; OIDC adds identity on top. Most production bugs are wrong flow for client, token validation gaps, and confused redirect URIs.

When to Offer This Workflow

Trigger conditions:

• Web, mobile, or SPA login; machine-to-machine clients
• Debugging invalid_grant, redirect_uri mismatches, token replay
• Hardening scopes, refresh rotation, logout

Initial offer:

Use six stages: (1) actors & client type, (2) select flow & PKCE, (3) tokens & validation, (4) scopes & consent UX, (5) session & logout, (6) operational hardening). Confirm IdP (Auth0, Cognito, Keycloak, Google, etc.).

Stage 1: Actors & Client Type

Goal: Classify confidential vs public clients and who holds secrets.

Rules

• Server-side web app with secret: confidential; SPA and native: public → PKCE mandatory
• M2M: client credentials or JWT assertion—no user in loop

Exit condition: Architecture diagram: browser, backend, IdP, resource server.

Stage 2: Select Flow & PKCE

Goal: Authorization Code (+ PKCE for public clients); avoid Implicit and ROPC for new apps.

Practices

• Exact redirect URI allowlist—no wildcards that enable open redirects
• State and nonce for CSRF and token binding (OIDC)
• Mobile: custom URL schemes vs universal links—document trade-offs

Exit condition: Sequence diagram for login happy path and error paths.

Stage 3: Tokens & Validation

Goal: Access token for APIs; ID token for identity claims—validate issuer, audience, exp, signature (JWKS rotation).

Practices

• Never use ID token as API bearer unless your architecture explicitly defines that (usually wrong)
• Refresh token: rotation, reuse detection, secure storage (httpOnly cookie or secure OS storage on mobile)
• Clock skew tolerance when validating exp

Exit condition: Documented validation steps in code or API gateway config.

Stage 4: Scopes & Consent

Goal: Least privilege scopes; incremental auth when possible.

UX

• Clear consent copy; minimize scope creep at first login

Stage 5: Session & Logout

Goal: RP-initiated logout vs local session clearing—know what breaks SSO across apps.

Practices

• Front-channel / back-channel logout when enterprise IdP requires

Stage 6: Operational Hardening

Goal: Rotate client secrets safely; monitor failed auth rates; alert on abnormal token issuance.

Pitfalls

• Mixing dev and prod clients; leaking JWKS or introspection endpoints in client bundles

Final Review Checklist

• Correct flow and PKCE for client class
• Redirect URIs strict; state/nonce used appropriately
• Token validation complete (sig, iss, aud, exp)
• Refresh handling and rotation policy
• Scopes minimal; logout behavior understood

Tips for Effective Guidance

• Draw Authorization Code + PKCE as default for SPAs.
• Call out BFF pattern when SPA cannot hold secrets and APIs need cookies.
• Enterprise SAML bridge to OIDC adds quirks—defer to IdP docs when needed.

Handling Deviations

• First-party only same-site: consider session cookie auth instead of full OAuth complexity if appropriate.
• Legacy Implicit: migration plan to Code+PKCE with downtime window.