Implementing OAuth 2.0 Authorization Code Flow with PKCE for SPA and Mobile Apps

Desired outcome

Successfully obtain an access token using the OAuth 2.0 Authorization Code Flow with PKCE, without storing a client secret.

Prerequisites

• OAuth 2.0 Authorization Server that supports PKCE (S256 method).
• Registered client ID with at least one redirect URI.
• Ability to generate cryptographically random strings and compute SHA-256 (available in modern browsers via Web Crypto API).

Procedure

1. Generate code_verifier and code_challenge. Create a random string 43‑128 characters (alphanumeric plus -._~). Compute SHA‑256, then Base64URL‑encode to get the challenge. Store the verifier temporarily (e.g., sessionStorage).
2. Start the authorization request. Redirect the user to the AS /authorize endpoint with parameters: response_type=code, client_id=YOUR_CLIENT_ID, redirect_uri=YOUR_REDIRECT_URI, scope=openid%20profile, state=RANDOM_STATE, code_challenge=GENERATED_CHALLENGE, code_challenge_method=S256.
3. Handle the redirect. After user authentication, the AS returns to redirect_uri with code and the original state. Verify the state matches the one you sent to mitigate CSRF.
4. Exchange the authorization code for tokens. POST to the AS /token endpoint with Content-Type: application/x-www-form-urlencoded and body:

   grant_type=authorization_code
   code=AUTHORIZATION_CODE_RECEIVED
   client_id=YOUR_CLIENT_ID
   redirect_uri=YOUR_REDIRECT_URI
   code_verifier=ORIGINAL_CODE_VERIFIER
   

5. Process the response. On success, the AS returns JSON containing access_token, optional refresh_token, and token_type. Store the token securely (e.g., in-memory) and use it for API calls.

Expected checks

• Network tab shows the initial GET to /authorize includes code_challenge and code_challenge_method=S256.
• The POST to /token includes the exact code_verifier generated earlier.
• Providing an incorrect verifier results in a 400 error from the token endpoint.
• A valid verifier yields a JSON response with an access_token field.

Recovery options

• If the state mismatch occurs, abort the flow and restart from step 1 with a new verifier/challenge.
• If the token endpoint returns 400 due to verifier failure, clear the stored verifier and repeat the flow.
• Network errors: retry the POST after a short back‑off, ensuring the verifier is still available.