Stackvora.tech

OAuth 2.1 and PKCE: The Modern Auth Flow Every Dev Should Know

OAuth 2.0 has been the de-facto standard for delegated authorization since its inception, but its flexibility led to several implementation pitfalls,…

OAuth 2.0 has been the de-facto standard for delegated authorization since its inception, but its flexibility led to several implementation pitfalls, particularly concerning client security. OAuth 2.1 emerges as a refined standard, consolidating the best practices and security enhancements learned over a decade. A cornerstone of this evolution is the mandated use of Proof Key for Code Exchange (PKCE) for all client types, along with the deprecation of less secure flows like the Implicit Grant and Resource Owner Password Credentials Grant.

This article details the OAuth 2.1 Authorization Code Flow with PKCE, demonstrating its mechanics and benefits. We will cover the key components, the request/response sequence, and provide practical examples for implementation in a modern web application context, focusing on client-side and backend interactions.

Understanding OAuth 2.1's Core Changes

OAuth 2.1 is not a new protocol but rather a consolidation of existing RFCs and BCPs (Best Current Practices) under a single, streamlined specification. Its primary goal is to enhance security and simplify implementation by removing ambiguity and discouraging insecure patterns. Key changes include:

  • PKCE for all Authorization Code Flows: Previously optional, PKCE is now mandatory for all clients using the Authorization Code Grant, including confidential clients (server-side applications). This eliminates the threat of authorization code interception attacks.
  • Deprecation of Implicit Grant: The Implicit Grant, which returned access tokens directly in the URL fragment, is removed due to its susceptibility to token leakage and injection attacks. Its use is now strongly discouraged, even for single-page applications (SPAs).
  • Deprecation of Resource Owner Password Credentials Grant: This flow, which involves clients collecting user credentials, is removed. It bypasses the authorization server's robust authentication mechanisms and introduces significant security risks. Clients should redirect users to the authorization server for authentication.
  • Redirect URI Validation: Stricter validation of redirect URIs is enforced to prevent open redirector vulnerabilities. Exact matching or more rigorous partial matching is recommended.
  • Refresh Token Rotation: When refresh tokens are used, the authorization server should issue a new refresh token with each new access token. The old refresh token should be invalidated after use, ideally with a short grace period for race conditions. This enhances security by limiting the lifespan of a compromised refresh token.

The Authorization Code Flow with PKCE: A Deep Dive

The Authorization Code Flow with PKCE is the recommended and most secure OAuth 2.1 grant type. It involves a secure exchange of an authorization code for an access token, protected by cryptographic proof.

Sequence of Operations

  1. Client Generates PKCE Parameters: The client (e.g., a SPA or mobile app) generates a high-entropy cryptographically random string called a code_verifier. It then hashes this code_verifier using SHA256 and Base64Url-encodes the result to create a code_challenge.
  2. Client Redirects to Authorization Server: The client redirects the user's browser to the authorization server's authorization endpoint, including the code_challenge, code_challenge_method (S256), client_id, redirect_uri, scope, and state parameters.
  3. User Authenticates and Authorizes: The authorization server authenticates the user and prompts them to grant (or deny) the requested permissions (scopes) to the client.
  4. Authorization Server Redirects Back with Code: If authorized, the authorization server redirects the user's browser back to the client's pre-registered redirect_uri, including an authorization code and the state parameter.
  5. Client Exchanges Code for Tokens: The client makes a direct, backend HTTP POST request to the authorization server's token endpoint. This request includes the authorization code, redirect_uri, client_id, and crucially, the original code_verifier.
  6. Authorization Server Verifies PKCE and Issues Tokens: The authorization server receives the request, re-computes the code_challenge from the provided code_verifier, and compares it to the code_challenge received in the initial authorization request. If they match, and all other parameters are valid, the authorization server issues an access_token (and optionally a refresh_token and id_token for OIDC) to the client.
  7. Client Accesses Protected Resources: The client uses the access_token to make authenticated requests to protected resource servers.

Why PKCE?

PKCE (RFC 7636) was originally designed for mobile and single-page applications (public clients) that cannot securely store a client_secret. Without PKCE, if an attacker intercepts the authorization code (e.g., through a malicious app or DNS cache poisoning on a redirect URI), they could exchange it for an access token. PKCE mitigates this by requiring the client to prove ownership of the authorization request by providing the code_verifier in the token exchange step. Since only the legitimate client knows the code_verifier, the intercepted code becomes useless to an attacker.

Mandating PKCE for confidential clients as well (those that can securely store a client_secret) provides an additional layer of defense, even if the client_secret is compromised or if the code is intercepted before the confidential client can validate it. It’s a defense-in-depth strategy.

Practical Implementation Example (SPA and Backend)

Let's consider a Single Page Application (SPA) using React/Vue/Angular and a simple backend API. The SPA is a public client, and our authorization server is an Identity Provider like Auth0, Okta, or Keycloak.

Client-Side (SPA) Steps

First, the SPA initiates the flow. This often involves a JavaScript library (e.g., oidc-client-js or a vendor-specific SDK) that handles PKCE generation and redirects.


// Example using a hypothetical JS client library
// (pseudo-code for clarity, actual implementation varies by library/framework)

import { generateCodeVerifier, generateCodeChallenge } from './pkce-utils'; // Custom utility

async function initiateLogin() {
    const code_verifier = generateCodeVerifier(); // e.g., "dBjftJeZ4CVP-mB92K_7oESZ_rY_GMBrWzO-o4vM_V-dpUFqd_Y3f"
    sessionStorage.setItem('code_verifier', code_verifier); // Store for later token exchange

    const code_challenge = generateCodeChallenge(code_verifier); // e.g., "E9MelSacrTqRz-fQJcChVsd4N_EmjrsoJzP0X-zM_Bs"
    const code_challenge_method = 'S256';

    const authUrl = new URL('https://your-auth-server.com/oauth2/authorize');
    authUrl.searchParams.append('response_type', 'code');
    authUrl.searchParams.append('client_id', 'YOUR_SPA_CLIENT_ID'); // e.g., "my-spa-app-123"
    authUrl.searchParams.append('redirect_uri', 'http://localhost:3000/callback');
    authUrl.searchParams.append('scope', 'openid profile email');
    authUrl.searchParams.append('state', 'a_random_csrf_state'); // Crucial for CSRF protection
    authUrl.searchParams.append('code_challenge', code_challenge);
    authUrl.searchParams.append('code_challenge_method', code_challenge_method);

    window.location.href = authUrl.toString();
}

// In the callback handler (e.g., on /callback route)
async function handleCallback() {
    const urlParams = new URLSearchParams(window.location.search);
    const code = urlParams.get('code');
    const state = urlParams.get('state');

    // TODO: Verify 'state' against stored value to prevent CSRF attacks.

    if (code) {
        const code_verifier = sessionStorage.getItem('code_verifier');
        if (!code_verifier) {
            console.error('Code verifier not found in session storage.');
            return;
        }

        const tokenUrl = 'https://your-auth-server.com/oauth2/token';
        const response = await fetch(tokenUrl, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded',
            },
            body: new URLSearchParams({
                grant_type: 'authorization_code',
                client_id: 'YOUR_SPA_CLIENT_ID',
                redirect_uri: 'http://localhost:3000/callback',
                code: code,
                code_verifier: code_verifier,
            }),
        });

        const data = await response.json();
        if (response.ok) {
            console.log('Access Token:', data.access_token);
            console.log('Refresh Token:', data.refresh_token); // If refresh tokens are issued
            // Store tokens securely (e.g., in memory, HTTP-only cookies for refresh tokens if applicable)
            sessionStorage.removeItem('code_verifier'); // Clean up
        } else {
            console.error('Token exchange failed:', data);
        }
    }
}

Note: Storing code_verifier in sessionStorage is common for SPAs. For refresh tokens, consider security implications. Many SPAs opt for short-lived access tokens and token rotation, avoiding long-lived refresh tokens in browser storage.

Authorization Server Configuration

On the authorization server (e.g., Keycloak 23.0.x), when registering a client:

  • Set "Access Type" to "public" (for SPAs) or "confidential" (for server-side apps).
  • Ensure PKCE support is enabled (it's often on by default or configurable).
  • Register exact redirect_uris.

Resource Server (Backend API) Interaction

Once the SPA obtains an access_token, it uses this token to call backend APIs (resource servers). The backend API needs to validate the token.


// Example: Node.js Express middleware for token validation
// This typically involves an OAuth 2.0 validation library like 'jsonwebtoken' or 'express-oauth2-jwt-bearer'

const express = require('express');
const { auth } = require('express-oauth2-jwt-bearer'); // Example for JWT validation

const app = express();

// Middleware to protect routes
const checkJwt = auth({
  audience: 'https://your-api.com', // Audience of your API (Resource Server)
  issuerBaseURL: `https://your-auth-server.com/`, // Your Authorization Server's issuer
  tokenSigningAlg: 'RS256' // Algorithm used by your Auth Server
});

app.get('/api/protected-data', checkJwt, (req, res) => {
  // If we reach here, the access token is valid
  res.json({
    message: 'This is protected data!',
    user: req.auth.payload.sub // User ID from the token
  });
});

app.listen(3001, () => {
  console.log('Resource Server listening on port 3001');
});

The resource server does not participate in the PKCE flow directly. Its role is solely to validate the access token presented by the client. This validation typically involves:

  • Verifying the token's signature using the authorization server's public key (retrieved from the /.well-known/openid-configuration endpoint).
  • Checking the expiry time (exp claim).
  • Validating the issuer (iss claim).
  • Validating the audience (aud claim) to ensure the token is intended for this resource server.
  • Checking for necessary scopes (scope claim) or permissions.

Common Pitfalls and Troubleshooting

  • Mismatched redirect_uri: One of the most common errors. The redirect_uri sent in the authorization request MUST exactly match one of the pre-registered URIs on the authorization server. Any deviation, even a trailing slash, can cause errors (e.g., invalid_redirect_uri).
  • code_verifier/code_challenge Mismatch: The code_verifier sent in the token exchange must exactly match the original code_challenge (after transformation) that the authorization server received. Errors here typically manifest as invalid_grant or specific PKCE errors from the authorization server. Double-check your Base64Url encoding and SHA256 hashing. Many libraries handle this, but manual implementations are prone to errors.
  • State Parameter Missing/Invalidated: The state parameter is crucial for CSRF protection. Always generate a unique, unguessable state for each request, store it securely (e.g., HTTP-only cookie or session storage), and validate it upon callback. Failing to do so can leave your application vulnerable.
  • Client ID Issues: Ensure the client_id sent in the request matches a registered client on the authorization server. Public clients typically do not have a client_secret, but confidential clients do.
  • CORS Issues: Token exchange typically happens server-to-server or from the client directly to the authorization server's token endpoint. If a SPA makes this request, ensure the authorization server has appropriate CORS headers configured to allow requests from your SPA's origin.
  • Scope Mismatch: Requesting scopes that are not configured for your client or not understood by the authorization server can lead to errors or reduced permissions.
  • Clock Skew: For JWT validation on the resource server, significant clock skew between the resource server and the authorization server can cause valid tokens to be rejected due to premature expiry or "not before" checks. Ensure server clocks are synchronized (e.g., using NTP).

Back to the knowledge base · Ask the AI assistant