OAuth 2.0 and OIDC Flows: Authorization Code to PKCE

OAuth 2.0 is an authorization-delegation framework; OpenID Connect (OIDC) layers identity on top. This article walks the canonical OAuth 2.1 flow set — Authorization Code + PKCE, Device Authorization Grant, Client Credentials — explains how OIDC ID tokens, refresh-token rotation, DPoP, and the BFF pattern fit on top, and pins each design choice to the specific RFC or attack it answers, so a senior engineer can pick a flow, validate a token, and harden a deployment without re-deriving the threat model.

Abstract

OAuth 2.0 is an authorization delegation framework—it lets users grant applications limited access to their resources without sharing credentials. OIDC (OpenID Connect) is an identity layer on top of OAuth—it proves who the user is via ID tokens. The core security model relies on:

Key Design Principles

• PKCE is mandatory for all clients (OAuth 2.1)—prevents authorization code interception
• Tokens are bearer credentials—possession equals authorization; protect accordingly
• State prevents CSRF; nonce prevents replay; PKCE prevents interception—all three are required
• Implicit flow is deprecated—tokens in URLs leak via history, referrer, logs
• Access tokens are for APIs; ID tokens are for clients—never use ID tokens to call APIs

OAuth 2.0 Core Architecture

Four Defined Roles

OAuth 2.0 (RFC 6749) defines four roles that interact during authorization:

Design rationale: OAuth separates the client from the resource owner. Instead of the client storing user credentials (the pre-OAuth antipattern), the client obtains tokens with specific scope and lifetime. This enables revocable, scoped access without credential exposure.

Client Types

Clients are classified by their ability to maintain credential confidentiality:

OAuth 2.1 (draft-15): The distinction matters less now — PKCE is mandatory for all clients (§7.5). Confidential clients still use secrets (or, preferably, private_key_jwt / mTLS) for client authentication, but secrets alone are insufficient as a defence against authorization-code interception.

Protocol Endpoints

Picking a flow

OAuth 2.1 narrows the canonical flow set to three, plus refresh tokens for session continuity. Everything else (Implicit, Resource Owner Password Credentials) is removed.¹

Authorization Code Flow with PKCE

The Authorization Code flow with PKCE (Proof Key for Code Exchange) is the only recommended flow for all client types as of OAuth 2.1.

Step 1: Generate Security Parameters

Before initiating the flow, the client generates three security parameters:

1import crypto from "crypto"23// PKCE: code_verifier (43-128 chars, cryptographically random)4const codeVerifier = crypto.randomBytes(32).toString("base64url")5// e.g., "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"67// PKCE: code_challenge (SHA256 hash of verifier)8const codeChallenge = crypto.createHash("sha256").update(codeVerifier).digest("base64url")9// e.g., "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"1011// CSRF protection12const state = crypto.randomBytes(16).toString("hex")1314// OIDC replay protection15const nonce = crypto.randomBytes(16).toString("hex")1617// Store in session for validation18session.oauthParams = { codeVerifier, state, nonce }

Why three parameters?

Step 2: Authorization Request

The client redirects the user to the authorization server:

1GET /authorize?2  response_type=code3  &client_id=CLIENT_ID4  &redirect_uri=https://client.example/callback5  &scope=openid profile email6  &state=abc123xyz7  &nonce=def456uvw8  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM9  &code_challenge_method=S25610HTTP/1.111Host: auth.example.com

Required parameters:

Step 3: User Authentication and Consent

The authorization server:

1. Authenticates the user (login if no session)
2. Displays consent screen with requested scopes
3. Records user’s decision

Step 4: Authorization Response

On approval, the authorization server redirects back with the authorization code:

1HTTP/1.1 302 Found2Location: https://client.example/callback?3  code=SplxlOBeZQQYbYS6WxSbIA4  &state=abc123xyz5  &iss=https://auth.example.com

Security validation (client-side):

Show 3 hidden lines45  // Check for error response6  if (error) {7    return res.status(400).json({ error: req.query.error_description })8  }910  // Validate state (CSRF protection)11  if (state !== req.session.oauthParams.state) {12    return res.status(400).json({ error: "State mismatch - CSRF detected" })13  }1415  // Validate issuer (mix-up attack protection, RFC 9207)16  if (iss !== EXPECTED_ISSUER) {17    return res.status(400).json({ error: "Issuer mismatch" })18  }19Show 4 hidden lines

RFC 9207: The iss parameter in the authorization response prevents mix-up attacks when clients use multiple authorization servers. Always validate it matches the expected issuer.

Step 5: Token Exchange

The client exchanges the authorization code for tokens at the token endpoint:

1POST /token HTTP/1.12Host: auth.example.com3Content-Type: application/x-www-form-urlencoded45grant_type=authorization_code6&code=SplxlOBeZQQYbYS6WxSbIA7&redirect_uri=https://client.example/callback8&client_id=CLIENT_ID9&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

For confidential clients, add client authentication:

1POST /token HTTP/1.12Host: auth.example.com3Content-Type: application/x-www-form-urlencoded4Authorization: Basic base64(client_id:client_secret)56grant_type=authorization_code7&code=SplxlOBeZQQYbYS6WxSbIA8&redirect_uri=https://client.example/callback9&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

PKCE server validation:

1// Authorization server validates PKCE2function validatePKCE(codeChallenge, codeVerifier, method) {3  if (method === "S256") {4    const computedChallenge = crypto.createHash("sha256").update(codeVerifier).digest("base64url")5    return computedChallenge === codeChallenge6  }7  // 'plain' method (SHOULD NOT be used)8  return codeVerifier === codeChallenge9}

Step 6: Token Response

1{2  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",3  "token_type": "Bearer",4  "expires_in": 900,5  "refresh_token": "8xLOxBtZp8",6  "scope": "openid profile email",7  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."8}

PKCE Deep Dive

PKCE (Proof Key for Code Exchange, RFC 7636) prevents authorization code interception attacks.

The Attack PKCE Prevents

Attack scenario: On mobile platforms, multiple apps can register the same custom URI scheme (com.example.app://). A malicious app intercepts the redirect containing the authorization code and exchanges it for tokens.

With PKCE: The authorization server binds the code to the code_challenge. Without the code_verifier (which only the legitimate app possesses), the malicious app cannot complete the exchange.

Code Verifier Requirements (RFC 7636)

Challenge Methods

Design rationale: S256 is preferred because even if the code_challenge is leaked (e.g., in browser history), the original code_verifier cannot be derived. With plain, leaking the challenge equals leaking the verifier.

PKCE in OAuth 2.1

OAuth 2.1 draft-15, Section 7.5 (March 2026): “Clients MUST use code_challenge and code_verifier and authorization servers MUST enforce their use except under the conditions described in Section 7.5.1. Even in this case, using and enforcing code_challenge and code_verifier as described above is still RECOMMENDED.”

OAuth 2.1 makes PKCE mandatory for all clients—public and confidential. This acknowledges that:

1. Client secrets can leak (supply chain attacks, compromised dependencies)
2. PKCE provides defense-in-depth even when secrets are used
3. A single secure pattern simplifies implementation

Client Credentials Flow (Machine-to-Machine)

The Client Credentials grant (RFC 6749 §4.4) is the only flow with no end user: the client is acting on its own behalf, typically a backend service calling another backend service. There is no authorization code, no redirect, no refresh token, and no ID token — there is no user to identify.

1POST /token HTTP/1.12Host: auth.example.com3Content-Type: application/x-www-form-urlencoded4Authorization: Basic base64(client_id:client_secret)56grant_type=client_credentials7&scope=invoices:read invoices:write

When to use it

What to avoid

• Refresh tokens MUST NOT be issued for the Client Credentials grant (RFC 6749 §4.4.3). When the access token expires, the client just re-authenticates.
• Prefer private_key_jwt or mTLS client authentication (RFC 8705) over client_secret_basic/client_secret_post. Shared secrets sit in env vars and leak through logs, configs, and container images.
• Combine with DPoP (RFC 9449) or mTLS sender-constraint so a stolen token cannot be replayed by a different caller.

Device Authorization Grant

The Device Authorization Grant (RFC 8628) covers input-constrained devices — smart TVs, set-top boxes, CLIs, IoT devices, kiosks — where typing a password or rendering a full login UI is impractical. The user authenticates on a secondary device (phone or laptop) while the device polls for the result.

Step 1: Device authorization request

1POST /device_authorization HTTP/1.12Host: auth.example.com3Content-Type: application/x-www-form-urlencoded45client_id=CLIENT_ID&scope=openid profile offline_access

Step 2: Authorization server response

1{2  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",3  "user_code": "WDJB-MJHT",4  "verification_uri": "https://auth.example.com/device",5  "verification_uri_complete": "https://auth.example.com/device?user_code=WDJB-MJHT",6  "expires_in": 1800,7  "interval": 58}

The device displays user_code and verification_uri (or a QR code for verification_uri_complete) and starts polling.

Step 3: Polling the token endpoint

1POST /token HTTP/1.12Host: auth.example.com3Content-Type: application/x-www-form-urlencoded45grant_type=urn:ietf:params:oauth:grant-type:device_code6&device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS7&client_id=CLIENT_ID

The client MUST respect the interval and MUST back off when it receives slow_down (RFC 8628 §3.5):

OpenID Connect (OIDC) Identity Layer

OIDC extends OAuth 2.0 to provide authentication (proving who the user is) in addition to OAuth’s authorization (proving what the user can access).

ID Token Structure

The ID token is a JWT containing identity claims about the authenticated user:

1{2  "iss": "https://auth.example.com",3  "sub": "user_12345",4  "aud": "CLIENT_ID",5  "exp": 1704153600,6  "iat": 1704150000,7  "auth_time": 1704149900,8  "nonce": "def456uvw",9  "acr": "urn:mace:incommon:iap:silver",10  "amr": ["pwd", "mfa"],11  "at_hash": "x4Q8HQ2_VFbP...",12  "name": "Jane Doe",13  "email": "jane@example.com",14  "email_verified": true15}

ID Token Claims

Required claims (per OIDC Core 1.0):

Contextually required claims:

ID Token Validation (Mandatory Steps)

Show 5 hidden lines6  const decoded = jwt.decode(idToken, { complete: true })7  const { kid, alg } = decoded.header89  // 2. Fetch signing key from JWKS endpoint10  const client = jwksClient({ jwksUri: `${expectedIssuer}/.well-known/jwks.json` })11  const key = await client.getSigningKey(kid)1213  // 3. Verify signature and decode claims14  const claims = jwt.verify(idToken, key.getPublicKey(), {15    algorithms: [alg], // Explicitly allowlist algorithm16    issuer: expectedIssuer,17    audience: clientId,18  })1920  // 4. Validate nonce (replay protection)21  if (claims.nonce !== nonce) {22    throw new Error("Nonce mismatch - potential replay attack")23  }2425  // 5. Validate auth_time if max_age was used26  if (claims.auth_time && maxAgeUsed) {27    const authAge = Math.floor(Date.now() / 1000) - claims.auth_time28    if (authAge > maxAge) {29      throw new Error("Authentication too old - re-authentication required")30    }31  }3233  // 6. Validate at_hash if present (binds ID token to access token)34  if (claims.at_hash) {35    const expectedHash = computeAtHash(accessToken, alg)36    if (claims.at_hash !== expectedHash) {37      throw new Error("Access token hash mismatch")38    }39  }Show 15 hidden lines

ID Token vs Access Token vs Refresh Token

Critical distinction: ID tokens prove who the user is (for the client). Access tokens prove what the user can do (for the API). Never use an ID token to call APIs—it’s semantically wrong and often insecure (audience mismatch).

UserInfo Endpoint

The UserInfo endpoint returns claims about the authenticated user:

1GET /userinfo HTTP/1.12Host: auth.example.com3Authorization: Bearer <access_token>

1{2  "sub": "user_12345",3  "name": "Jane Doe",4  "given_name": "Jane",5  "family_name": "Doe",6  "email": "jane@example.com",7  "email_verified": true,8  "picture": "https://example.com/jane.jpg"9}

When to use UserInfo vs ID Token:

• ID Token: Get claims at authentication time (single request)
• UserInfo: Fetch additional claims later, refresh claims without re-authentication

Refresh Tokens and Rotation

Refresh tokens enable long-lived sessions without long-lived access tokens.

Refresh Token Grant

1POST /token HTTP/1.12Host: auth.example.com3Content-Type: application/x-www-form-urlencoded45grant_type=refresh_token6&refresh_token=8xLOxBtZp87&client_id=CLIENT_ID8&scope=openid profile

Response (with rotation):

1{2  "access_token": "new_access_token...",3  "token_type": "Bearer",4  "expires_in": 900,5  "refresh_token": "new_refresh_token",6  "scope": "openid profile"7}

Refresh Token Rotation

Rotation issues a new refresh token with each use, invalidating the previous one:

Reuse Detection

If a previously-used refresh token is presented, it indicates token theft:

Implementation considerations:

Show 8 hidden lines910  // Check if token was already used11  if (tokenRecord.usedAt) {12    const timeSinceUse = Date.now() - tokenRecord.usedAt1314    // Grace period for legitimate retries (network failures)15    if (timeSinceUse < GRACE_PERIOD_MS) {16      // Return same tokens issued during grace period17      return tokenRecord.issuedTokens18    }1920    // Outside grace period - potential theft!21    await db.revokeTokenFamily(tokenRecord.familyId)22    throw new OAuthError("invalid_grant", "Token reuse detected")23  }2425  // Mark as used and issue new tokens26  await db.markTokenUsed(refreshToken, Date.now())2728  const newTokens = await issueTokens(tokenRecord.userId, tokenRecord.scopes)29  await db.storeIssuedTokens(refreshToken, newTokens)Show 3 hidden lines

Trade-offs of rotation:

Alternative: Sender-constrained tokens (DPoP/mTLS) avoid rotation overhead by binding tokens to cryptographic keys.

Token Storage by Platform

Web Applications (Browser-Based)

Backend-for-Frontend (BFF) Pattern (most secure for SPAs):

• Browser never sees OAuth tokens
• BFF maintains server-side session
• Session ID in HttpOnly, Secure, SameSite=Strict cookie
• BFF proxies API requests with access token

Mobile Applications

Show 4 hidden lines5    let query: [String: Any] = [6        kSecClass as String: kSecClassGenericPassword,7        kSecAttrAccount as String: userId,8        kSecAttrService as String: "oauth-refresh-token",9        kSecValueData as String: token.data(using: .utf8)!,10        kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly11    ]1213    // Delete existing item first14    SecItemDelete(query as CFDictionary)1516    // Add new item17    let status = SecItemAdd(query as CFDictionary, nil)18    return status == errSecSuccess19}

Native Apps (RFC 8252)

RFC 8252 defines OAuth for native applications:

Redirect URI options:

DPoP: Demonstrating Proof of Possession

DPoP (RFC 9449) sender-constrains tokens to prevent stolen tokens from being usable by attackers.

How DPoP Works

DPoP Proof JWT Structure

Header:

1{2  "typ": "dpop+jwt",3  "alg": "ES256",4  "jwk": {5    "kty": "EC",6    "crv": "P-256",7    "x": "l8tFrhx-34tV3hRICRDY9zCkDlpBhF42UQUfWVAWBFs",8    "y": "9VE4jf_Ok_o64tbkMYAPVS-9hQp9A7v9oy_A9C1_2RY"9  }10}

Payload (for token request):

1{2  "jti": "e7d7c7a9-1234-5678-abcd-ef0123456789",3  "htm": "POST",4  "htu": "https://auth.example.com/token",5  "iat": 17041500006}

Payload (for resource request):

1{2  "jti": "f8e8d8b9-2345-6789-bcde-f01234567890",3  "htm": "GET",4  "htu": "https://api.example.com/resource",5  "iat": 1704150100,6  "ath": "fUHyO2r2Z3DZ53EsNrWBb0xWXoaNy59IiKCAqksmQEo"7}

DPoP Claims

Security benefit: Even if an attacker steals the access token, they cannot use it without the private key that signed the DPoP proofs.

Security Pitfalls and Mitigations

Authorization Code Interception

Attack: Malicious app intercepts authorization code via shared redirect URI.

Mitigation: PKCE (mandatory in OAuth 2.1).

CSRF via Forged Authorization Response

Attack: Attacker tricks user into completing OAuth flow with attacker’s account.

Mitigation: state parameter—validate it matches the value sent in the request.

ID Token Replay

Attack: Attacker replays captured ID token to authenticate as victim.

Mitigation: nonce parameter—include in request, validate in ID token.

Mix-Up Attack

Attack: When client supports multiple authorization servers, attacker tricks client into sending tokens to wrong server.

Mitigation:

• Validate iss parameter in authorization response (RFC 9207)
• Validate iss claim in ID token matches expected issuer
• Use distinct redirect_uri per authorization server

Open Redirect via redirect_uri

Attack: Attacker crafts authorization request with malicious redirect_uri to steal authorization code.

Mitigation: Exact string matching for redirect_uri validation (no wildcards, no patterns).

1// Registration: Store exact URIs only2const registeredRedirectUris = ["https://client.example.com/callback", "https://client.example.com/oauth/callback"]34// Validation: Exact string match5function validateRedirectUri(requestedUri) {6  // MUST be exact match - no wildcards, patterns, or normalization7  return registeredRedirectUris.includes(requestedUri)8}910// MUST NOT allow:11// - https://client.example.com/* (wildcard)12// - https://*.example.com/callback (subdomain wildcard)13// - Pattern matching or regex

Token Leakage via Referrer

Attack: Access tokens in URL fragments leak via Referer header.

Mitigation:

• Use Authorization Code flow (not Implicit)
• Set Referrer-Policy: no-referrer header
• Use response_mode=form_post (OIDC)

Insufficient Redirect URI Validation

Attack: Authorization server accepts partial URI matches, enabling redirect to attacker-controlled subdomain.

Mitigation: Per RFC 9700 (OAuth Security BCP): “Authorization servers MUST utilize exact string matching” for redirect URI validation.

OAuth 2.1 Key Changes

OAuth 2.1 (currently draft-15, published 2 March 2026 and still on the standards track) consolidates OAuth 2.0 with security best practices from RFC 9700 (January 2025).

Removed Flows

Mandatory Requirements

Migration Checklist

1. Implement PKCE for all clients, including confidential
2. Remove Implicit flow support; migrate to Authorization Code + PKCE
3. Remove ROPC if implemented; migrate to proper redirect flow
4. Enforce exact redirect URI matching—no wildcards
5. Implement refresh token rotation or DPoP for public clients
6. Never send tokens in query strings—use headers or POST body

Beyond OAuth 2.1: Hardening Profiles and Extensions

OAuth 2.1 is the floor; high-assurance deployments — banking, healthcare, government, regulated APIs — layer additional specs on top. The pieces worth knowing:

Conclusion

OAuth 2.0 and OIDC provide a robust framework for authorization and authentication, but secure implementation requires understanding the threat model and applying defense-in-depth:

1. Pick the right flow first. Authorization Code + PKCE for any user-facing client; Device Authorization Grant for input-constrained devices; Client Credentials for service-to-service. Implicit and ROPC are gone.
2. ID tokens prove identity (for clients); access tokens prove authorization (for APIs)—never confuse them.
3. State, nonce, and PKCE work together—all three are required for user-facing flows.
4. Token storage must match platform capabilities—HttpOnly cookies (or BFF) for web, Keychain/Keystore for mobile, never localStorage.
5. Refresh token rotation or sender-constraining (DPoP / mTLS) is mandatory for public clients in OAuth 2.1; both is better.
6. OAuth 2.1 is the floor, not the ceiling. For high-assurance APIs, adopt FAPI 2.0 (PAR + PKCE + sender-constrained tokens + asymmetric client auth) as a single bundle.

The complexity exists because the threat model is real. Authorization code interception, CSRF, replay attacks, and token theft are documented, exploited vulnerabilities. Every security parameter exists because of a specific attack it prevents.

Appendix

Prerequisites

• HTTP fundamentals (cookies, headers, redirects, CORS)
• Cryptographic basics (symmetric vs asymmetric, hashing, JWTs)
• Session management patterns

Terminology

Summary

• OAuth 2.0 is authorization (what you can access); OIDC is authentication (who you are).
• Three canonical flows in OAuth 2.1: Authorization Code + PKCE (anything with a browser), Device Authorization Grant (input-constrained devices), Client Credentials (service-to-service). Implicit and ROPC are removed.
• state prevents CSRF; nonce prevents replay; PKCE prevents code interception — use all three on user-facing flows.
• ID tokens are for clients; access tokens are for APIs — never interchange them.
• Refresh token rotation detects theft; DPoP / mTLS prevents stolen token use; one of the two is mandatory for public clients.
• Store tokens appropriately: memory or HttpOnly cookies (BFF) for web; Keychain / Keystore for mobile.
• For high-assurance APIs, jump straight to FAPI 2.0 rather than re-deriving the hardening from RFCs.

References

Core specifications:

• RFC 6749: OAuth 2.0 Authorization Framework — core grants and roles.
• RFC 6750: Bearer Token Usage — Authorization: Bearer semantics.
• RFC 7636: PKCE — Proof Key for Code Exchange.
• RFC 8628: OAuth 2.0 Device Authorization Grant — input-constrained devices.
• RFC 9068: JWT Profile for OAuth 2.0 Access Tokens — at+jwt shape.
• OpenID Connect Core 1.0 — identity layer (also ISO/IEC 26131:2024).
• OpenID Connect Discovery 1.0 — /.well-known/openid-configuration.
• OAuth 2.1 Draft 15 — IETF Internet-Draft, 2026-03-02.

Security and hardening:

• RFC 6819: OAuth 2.0 Threat Model — original threat model.
• RFC 9700: OAuth 2.0 Security Best Current Practice — January 2025; updates 6749 / 6750 / 6819.
• RFC 9207: Authorization Server Issuer Identification — iss in authorization response (mix-up defence).
• RFC 9449: DPoP — sender-constrained tokens via proof-of-possession JWTs.
• RFC 8705: Mutual-TLS Client Authentication and Certificate-Bound Tokens — mTLS sender-constraint.
• RFC 9126: Pushed Authorization Requests (PAR) — push request parameters via back channel.
• RFC 9101: JWT-Secured Authorization Request (JAR) — sign authorization requests.
• JARM Final — JWT Secured Authorization Response Mode.
• RFC 9396: Rich Authorization Requests (RAR) — structured authorization_details.
• FAPI 2.0 Security Profile (OIDF, Final, Feb 2025) — high-assurance bundle.

Implementation guidance:

• RFC 8252: OAuth for Native Apps (BCP 212) — system browsers, claimed HTTPS, loopback, private URI schemes.
• RFC 7523: JWT Profile for Client Authentication — private_key_jwt.
• RFC 8693: OAuth 2.0 Token Exchange — delegation and impersonation patterns.
• OWASP OAuth2 Cheat Sheet — implementation security guidance.