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.