OAuth 2.0 and OIDC Flows: Authorization Code to PKCE

A comprehensive technical analysis of OAuth 2.0 authorization flows, OpenID Connect (OIDC) identity layer, PKCE security mechanism, and token lifecycle management for secure authentication and authorization implementations.

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-14): The distinction matters less now—PKCE is mandatory for all clients. Confidential clients still use secrets for additional security, but secrets alone are insufficient.

Protocol Endpoints

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:

1
import crypto from "crypto"
2

3
// PKCE: code_verifier (43-128 chars, cryptographically random)
4
const codeVerifier = crypto.randomBytes(32).toString("base64url")
5
// e.g., "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
6

7
// PKCE: code_challenge (SHA256 hash of verifier)
8
const codeChallenge = crypto.createHash("sha256").update(codeVerifier).digest("base64url")
9
// e.g., "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
10

11
// CSRF protection
12
const state = crypto.randomBytes(16).toString("hex")
13

14
// OIDC replay protection
15
const nonce = crypto.randomBytes(16).toString("hex")
16

17
// Store in session for validation
18
session.oauthParams = { codeVerifier, state, nonce }

Why three parameters?

Step 2: Authorization Request

The client redirects the user to the authorization server:

1
GET /authorize?
2
  response_type=code
3
  &client_id=CLIENT_ID
4
  &redirect_uri=https://client.example/callback
5
  &scope=openid profile email
6
  &state=abc123xyz
7
  &nonce=def456uvw
8
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
9
  &code_challenge_method=S256
10
HTTP/1.1
11
Host: 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:

1
HTTP/1.1 302 Found
2
Location: https://client.example/callback?
3
  code=SplxlOBeZQQYbYS6WxSbIA
4
  &state=abc123xyz
5
  &iss=https://auth.example.com

Security validation (client-side):

3 collapsed lines
1
// Express callback handler
2
app.get("/callback", async (req, res) => {
3
  const { code, state, iss, error } = req.query
4

5
  // Check for error response
6
  if (error) {
7
    return res.status(400).json({ error: req.query.error_description })
8
  }
9

10
  // Validate state (CSRF protection)
11
  if (state !== req.session.oauthParams.state) {
12
    return res.status(400).json({ error: "State mismatch - CSRF detected" })
13
  }
14

15
  // Validate issuer (mix-up attack protection, RFC 9207)
16
  if (iss !== EXPECTED_ISSUER) {
17
    return res.status(400).json({ error: "Issuer mismatch" })
18
  }
19

4 collapsed lines
20
  // Proceed to token exchange...
21
  const tokens = await exchangeCodeForTokens(code)
22
  res.json(tokens)
23
})

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:

1
POST /token HTTP/1.1
2
Host: auth.example.com
3
Content-Type: application/x-www-form-urlencoded
4

5
grant_type=authorization_code
6
&code=SplxlOBeZQQYbYS6WxSbIA
7
&redirect_uri=https://client.example/callback
8
&client_id=CLIENT_ID
9
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

For confidential clients, add client authentication:

1
POST /token HTTP/1.1
2
Host: auth.example.com
3
Content-Type: application/x-www-form-urlencoded
4
Authorization: Basic base64(client_id:client_secret)
5

6
grant_type=authorization_code
7
&code=SplxlOBeZQQYbYS6WxSbIA
8
&redirect_uri=https://client.example/callback
9
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

PKCE server validation:

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

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-14, Section 7.6: “Clients MUST use code_challenge and code_verifier and authorization servers MUST enforce their use.”

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

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": true
15
}

ID Token Claims

Required claims (per OIDC Core 1.0):

Contextually required claims:

ID Token Validation (Mandatory Steps)

5 collapsed lines
1
import jwt from "jsonwebtoken"
2
import jwksClient from "jwks-rsa"
3

4
async function validateIdToken(idToken, expectedIssuer, clientId, nonce) {
5
  // 1. Decode header to get key ID
6
  const decoded = jwt.decode(idToken, { complete: true })
7
  const { kid, alg } = decoded.header
8

9
  // 2. Fetch signing key from JWKS endpoint
10
  const client = jwksClient({ jwksUri: `${expectedIssuer}/.well-known/jwks.json` })
11
  const key = await client.getSigningKey(kid)
12

13
  // 3. Verify signature and decode claims
14
  const claims = jwt.verify(idToken, key.getPublicKey(), {
15
    algorithms: [alg], // Explicitly allowlist algorithm
16
    issuer: expectedIssuer,
17
    audience: clientId,
18
  })
19

20
  // 4. Validate nonce (replay protection)
21
  if (claims.nonce !== nonce) {
22
    throw new Error("Nonce mismatch - potential replay attack")
23
  }
24

25
  // 5. Validate auth_time if max_age was used
26
  if (claims.auth_time && maxAgeUsed) {
27
    const authAge = Math.floor(Date.now() / 1000) - claims.auth_time
28
    if (authAge > maxAge) {
29
      throw new Error("Authentication too old - re-authentication required")
30
    }
31
  }
32

33
  // 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
  }
11 collapsed lines
40

41
  return claims
42
}
43

44
// Compute at_hash per OIDC Core 3.1.3.6
45
function computeAtHash(accessToken, alg) {
46
  const hashAlg = alg === "RS256" ? "sha256" : "sha512"
47
  const hash = crypto.createHash(hashAlg).update(accessToken).digest()
48
  const halfHash = hash.slice(0, hash.length / 2)
49
  return halfHash.toString("base64url")
50
}

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:

1
GET /userinfo HTTP/1.1
2
Host: auth.example.com
3
Authorization: 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

1
POST /token HTTP/1.1
2
Host: auth.example.com
3
Content-Type: application/x-www-form-urlencoded
4

5
grant_type=refresh_token
6
&refresh_token=8xLOxBtZp8
7
&client_id=CLIENT_ID
8
&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:

8 collapsed lines
1
const GRACE_PERIOD_MS = 5000 // 5 seconds for network retries
2

3
async function handleRefreshToken(refreshToken) {
4
  const tokenRecord = await db.findRefreshToken(refreshToken)
5

6
  if (!tokenRecord) {
7
    throw new OAuthError("invalid_grant", "Unknown refresh token")
8
  }
9

10
  // Check if token was already used
11
  if (tokenRecord.usedAt) {
12
    const timeSinceUse = Date.now() - tokenRecord.usedAt
13

14
    // Grace period for legitimate retries (network failures)
15
    if (timeSinceUse < GRACE_PERIOD_MS) {
16
      // Return same tokens issued during grace period
17
      return tokenRecord.issuedTokens
18
    }
19

20
    // Outside grace period - potential theft!
21
    await db.revokeTokenFamily(tokenRecord.familyId)
22
    throw new OAuthError("invalid_grant", "Token reuse detected")
23
  }
24

25
  // Mark as used and issue new tokens
26
  await db.markTokenUsed(refreshToken, Date.now())
27

28
  const newTokens = await issueTokens(tokenRecord.userId, tokenRecord.scopes)
29
  await db.storeIssuedTokens(refreshToken, newTokens)
3 collapsed lines
30

31
  return newTokens
32
}

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

4 collapsed lines
1
// iOS: Store refresh token in Keychain
2
import Security
3

4
func storeRefreshToken(_ token: String, for userId: String) -> Bool {
5
    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: kSecAttrAccessibleWhenUnlockedThisDeviceOnly
11
    ]
12

13
    // Delete existing item first
14
    SecItemDelete(query as CFDictionary)
15

16
    // Add new item
17
    let status = SecItemAdd(query as CFDictionary, nil)
18
    return status == errSecSuccess
19
}

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": 1704150000
6
}

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 only
2
const registeredRedirectUris = ["https://client.example.com/callback", "https://client.example.com/oauth/callback"]
3

4
// Validation: Exact string match
5
function validateRedirectUri(requestedUri) {
6
  // MUST be exact match - no wildcards, patterns, or normalization
7
  return registeredRedirectUris.includes(requestedUri)
8
}
9

10
// 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-14, expected RFC in 2026) consolidates OAuth 2.0 with security best practices from RFC 9700.

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

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. Authorization Code + PKCE is the only recommended flow—use it for all clients
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
4. Token storage must match platform capabilities—HttpOnly cookies for web, Keychain/Keystore for mobile
5. Refresh token rotation or sender-constraining (DPoP) limits the blast radius of token theft
6. OAuth 2.1 codifies best practices—adopt its requirements now

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)
• Authorization Code + PKCE is mandatory for all clients in OAuth 2.1
• state prevents CSRF; nonce prevents replay; PKCE prevents code interception—use all three
• ID tokens are for clients; access tokens are for APIs—never interchange them
• Refresh token rotation detects theft; DPoP prevents stolen token use
• Store tokens appropriately: memory/HttpOnly cookies for web; Keychain/Keystore for mobile
• OAuth 2.1 removes Implicit and ROPC flows; mandates PKCE and exact redirect URI matching

References

Core Specifications:

• RFC 6749: OAuth 2.0 Authorization Framework - Core OAuth 2.0 specification
• RFC 7636: PKCE - Proof Key for Code Exchange
• OpenID Connect Core 1.0 - OIDC specification (also ISO/IEC 26131:2024)
• OAuth 2.1 Draft - IETF Draft 14 (October 2025)

Security Specifications:

• RFC 6819: OAuth 2.0 Threat Model - Security considerations
• RFC 9700: OAuth Security BCP - Best Current Practice (January 2025)
• RFC 9449: DPoP - Demonstrating Proof of Possession
• RFC 9207: Authorization Server Issuer Identification - Mix-up attack prevention

Implementation Guidance:

• RFC 8252: OAuth for Native Apps - BCP 212 for mobile/desktop apps
• OWASP OAuth2 Cheat Sheet - Implementation security guidance
• Auth0 Token Best Practices - Practical implementation advice