Implement OAuth 2.0 Authorization Code Flow with PKCE in a Single‑Page App

Desired Outcome

The goal is to obtain a short‑lived access token and a rotating refresh token for a single‑page application (SPA) while keeping the user’s credentials out of the browser and protecting against CSRF, XSS, and code interception.

Prerequisites

• A registered OAuth 2.0 client with a client_id and a pre‑registered redirect_uri that uses https://.
• HTTPS enabled for all endpoints (auth, token, JWKS).
• Ability to generate cryptographically random strings (e.g., crypto.getRandomValues).
• Access to the provider’s JWKS endpoint for ID token verification.
• Optional: a backend proxy to rotate refresh tokens if the provider does not support it.

Focused Procedure

1. Generate PKCE Parameters

   In the SPA, create a code_verifier and derive a code_challenge using SHA‑256 and Base64URL encoding. Store the code_verifier in a secure, in‑memory variable until the token request.

   // Generate a 128‑byte verifier
   const verifier = base64urlEncode(crypto.getRandomValues(new Uint8Array(128)));
   // Create the challenge
   const challenge = base64urlEncode(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier)));
   

2. Build the Authorization Request

   Include response_type=code, client_id, redirect_uri, scope (e.g., openid profile email offline_access), state (cryptographically random, tied to the user session), nonce (for ID token validation), code_challenge, and code_challenge_method=S256.

   GET https://auth.example.com/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=openid%20profile%20email%20offline_access&state=RANDOM_STATE&nonce=RANDOM_NONCE&code_challenge=CHALLENGE&code_challenge_method=S256 HTTP/1.1
   Host: auth.example.com
   

3. Handle the Redirect

   When the provider redirects back to redirect_uri, the URL will contain code and state as query parameters. Verify that the returned state matches the one stored in the session. If it does not, reject the response.

4. Exchange Code for Tokens

   Send a POST request to the token endpoint with grant_type=authorization_code, the code, redirect_uri, client_id, and the original code_verifier. Do not send client_secret from the SPA.

   POST https://auth.example.com/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code&code=AUTH_CODE&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&client_id=YOUR_CLIENT_ID&code_verifier=VERIFIER
   

   Expect a JSON response containing access_token, refresh_token, id_token, and expires_in.

5. Validate the ID Token

   Decode the JWT, fetch the provider’s JSON Web Key Set (JWKS) from https://auth.example.com/.well‑known/jwks.json, and verify the signature. Then check the standard claims: iss matches the provider, aud includes your client_id, exp is in the future, and nonce matches the one sent earlier.

   const {payload, header} = jwtDecode(idToken, {complete: true});
   const jwk = await fetchJWKS(header.kid);
   const isValid = await verifySignature(idToken, jwk);
   

6. Secure Token Storage

   • Never write tokens to localStorage or sessionStorage because they are accessible to any script on the page.
   • Use an in‑memory store (e.g., a JavaScript variable) for the access token during the session.
   • Store the refresh token in an HttpOnly, Secure cookie with SameSite=Lax if the SPA shares a domain with a backend that can rotate the token.
   • If no backend is available, keep the refresh token in memory and clear it on page unload; the user will have to re‑authenticate after a short period.

7. Refresh Token Rotation

   When the access token expires, call the token endpoint again with grant_type=refresh_token and the current refresh_token. The provider should return a new refresh token. Replace the old one immediately in the secure cookie or memory. This reduces the risk of a stolen refresh token being used for a long time.

   POST https://auth.example.com/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=refresh_token&refresh_token=CURRENT_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID
   

8. Error Handling

   If the token endpoint returns an error (e.g., invalid_grant), clear all stored tokens, invalidate the session, and redirect the user to the login page. Log the error for audit purposes but avoid exposing sensitive details to the UI.

Expected Checks

• Network inspector: confirm that the authorization request contains state, code_challenge, and code_challenge_method=S256.
• Token request: ensure the code_verifier matches the earlier challenge.
• ID token: verify signature, iss, aud, exp, and nonce.
• Refresh token rotation: after each refresh, the new token should be different from the previous one.
• CSRF test: simulate a tampered state value; the app should reject the response and not store any token.

Recovery Options

• If a token is missing or invalid, prompt the user to re‑authenticate.
• In case of a lost refresh token, the user must log in again; the SPA should clear any stale tokens and show a clear message.
• For XSS‑related token theft, ensure that the refresh token is never exposed to client‑side scripts. If a breach is detected, rotate the refresh token server‑side and force a re‑login.

Limitations & Practical Checklist

• This guide assumes the provider supports PKCE and refresh token rotation; check the provider’s documentation.
• If the SPA cannot set HttpOnly cookies (e.g., due to CORS restrictions), consider moving token handling to a backend proxy.
• Remember that SPA cookies are still vulnerable to CSRF unless SameSite is set; always pair with a state parameter.
• Validate that the redirect_uri exactly matches the registered one, including trailing slashes.
• Use a tool like curl or Postman to manually test the token exchange before integrating into the SPA.

Concrete Example – Configuring Auth0 for an SPA

Below is a minimal auth_config.json you might store on the client (never include secrets):

{
  "domain": "dev-xyz.us.auth0.com",
  "clientId": "abc123DEF456",
  "redirectUri": "https://app.example.com/callback",
  "audience": "https://api.example.com",
  "scope": "openid profile email offline_access"
}

Auth0’s token endpoint automatically validates PKCE and returns a rotating refresh token when offline_access is requested.

Conclusion

By following this structured flow—PKCE, state, nonce, secure storage, and refresh token rotation—you protect your SPA from the most common OAuth 2.0 attack vectors while maintaining a smooth user experience.