oauth-pkce-sessionstorage-lost-on-redirect

OAuth PKCE sessionStorage Lost on Redirect

Problem

OAuth PKCE flow fails at the code exchange step because the PKCE code verifier stored in sessionStorage is missing after the redirect from the external authorization server. The error message typically says "Session not found" or "No code verifier found" with no indication that the storage backend is the issue.

Context / Trigger Conditions

• SPA initiates OAuth PKCE flow, storing code_verifier in sessionStorage
• User is redirected to external auth server (e.g., login.example.com)
• Auth server redirects back to SPA callback URL with ?code=...&state=...
• SPA tries to exchange code but can't find the PKCE verifier
• Error message is about "session not found" or "missing verifier", NOT about storage
• Works fine in local development (same-origin), fails in production (cross-origin)

Root Cause

sessionStorage is scoped per-tab AND per-origin, and has additional fragility:

1. If the auth server opens a new tab or popup, the new tab has empty sessionStorage
2. Some browsers (especially Safari with ITP) may clear sessionStorage during cross-origin navigation chains
3. If the auth server does multiple redirects (302 chains), some browsers treat the return as a new browsing context
4. Mobile browsers are particularly aggressive about clearing sessionStorage

Solution

Switch from sessionStorage to localStorage for the PKCE code verifier storage:

// BEFORE (fragile)
const client = createOAuthClient({
  storage: sessionStorage,
});

// AFTER (reliable)
const client = createOAuthClient({
  storage: localStorage,
});

The security concern with localStorage (verifier persists longer) is mitigated because:

• The PKCE verifier is single-use; the auth server rejects it after first exchange
• Most OAuth SDKs clean up the verifier after successful exchangeCode()
• getAuthorizationUrl() overwrites any stale verifier on new flow start

Verification

1. Start OAuth flow on the SPA
2. Complete auth on the external server
3. Callback should successfully exchange the code without "session not found" errors
4. Check localStorage — the divine_pkce (or equivalent) key should be cleaned up after successful exchange