Oauth Oidc

---

name: oauth-oidc description: Deep OAuth 2.0 / OpenID Connect workflow—choosing flows for client type, PKCE, tokens and validation, scopes and consent, rotation, and common misconfigurations. Use when implementing SSO, social login, or API access on behalf of users.

---

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.

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.

---