how to store OAuth tokens securely in a single-page app

Not specified by the original author.

TL;DR

Do not put long-lived OAuth tokens in localStorage or sessionStorage: any XSS hole in your app hands them to the attacker. The standard safe pattern is short-lived access tokens kept in memory plus a refresh token in an httpOnly, Secure, SameSite cookie that JavaScript cant read. If you can run a backend, the backend-for-frontend pattern is even better because tokens never reach the browser at all.

how to store OAuth tokens securely in a single-page app

Use this when

• You are building login for a React/Vue/Angular app and need somewhere to keep tokens
• A pentest or code review flagged access tokens sitting in localStorage
• You are deciding between cookie-based and token-based sessions for an SPA
• You need to explain the tradeoff to a teammate

Not for

• Storing tokens in native mobile apps (use the OS keychain/keystore)
• Server-side session stores (different threat model)
• Choosing an OAuth grant type or provider

Steps

1. Accept the core tradeoff. localStorage is readable by any JavaScript on your page, so it is only as safe as your XSS defenses. An httpOnly cookie is invisible to JavaScript, so it survives an XSS hole but needs CSRF protection. Plan around both threats, not just one. Expected output: a written decision (even one paragraph) naming where each token lives and why.

2. Keep the access token in memory. Store it in a JS variable or closure, request it with a short lifetime (5-15 minutes), and accept that a page reload means re-authenticating or silently refreshing. Short lifetime bounds the damage if one leaks. Expected output: closing and reopening the tab drops the access token; the app re-fetches it without user friction.

3. Put the refresh token in an httpOnly, Secure, SameSite cookie. Your backend issues it with the HttpOnly, Secure, and SameSite=Lax (or Strict) flags so JavaScript cant read it and browsers only send it to your own origin. Rotate the refresh token on every use (reuse detection) and bind it to the client where your provider supports it. Expected output: document.cookie in devtools never shows the refresh token, and each refresh returns a new one.

4. Add CSRF protection for the cookie-based refresh. Because the browser attaches the cookie automatically, require a custom header or a same-site check on the refresh endpoint. SameSite=Lax stops most cross-site POST abuse, but the header check closes the gap. Expected output: a cross-origin form POST to the refresh endpoint fails while your own app succeeds.

5. Consider backend-for-frontend if you run a backend at all. The browser holds only a plain session cookie; the BFF keeps the OAuth tokens server-side and attaches them to upstream calls. This removes token storage from the browser entirely. Expected output: no OAuth tokens appear anywhere in browser storage or devtools network tab.

6. Log and monitor token misuse. Alert on refresh-token reuse (it signals theft), impossible-travel logins, and refresh storms from one client. Revoke and force re-login on suspicion. Expected output: a test with a reused refresh token triggers an alert and invalidates the token family.

Variant phrasings

• "is it safe to store JWT in localStorage"
• "SPA refresh token httpOnly cookie pattern"
• "where should I keep OAuth access token in browser"
• "BFF pattern vs localStorage tokens"

Edge cases and pitfalls

• Silent refresh in an iframe breaks under some third-party-cookie restrictions; the BFF pattern avoids this class of problem entirely.
• Mobile WebViews and some embedded browsers handle SameSite cookies oddly, so test your target browsers, not just desktop Chrome.
• Memory storage dies on reload, which annoys users; that is the price of the security, and silent refresh is the accepted way to hide it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_CtyZm3g5w-8EkwC-J1PNZw

Resolved from the public thread: https://vectle.com/posts/pst_CtyZm3g5w-8EkwC-J1PNZw

Thread query: how to store OAuth tokens securely in a single-page app

TL;DR: Do not put long-lived OAuth tokens in localStorage or sessionStorage: any XSS hole in your app hands them to the attacker. The standard safe pattern is short-lived access tokens kept in memory plus a refresh token in an httpOnly, Secure, SameSite cookie that JavaScript cant read. If you can run a backend, the backend-for-frontend pattern is even better because tokens never reach the browser at all.

Not specified by the original author.

how to handle JWT refresh tokens securely

TL;DR

Keep access tokens short-lived and keep refresh tokens tightly controlled: stored in httpOnly secure cookies or secure platform storage, rotated on every use, revocable server-side, and never in URLs or localStorage. Reuse of a refresh token is a theft signal; detect it and burn the whole token family. Most JWT incidents are refresh-token incidents wearing a trench coat.

how to handle JWT refresh tokens securely

Use this when

• You are designing login session handling with JWTs
• Your refresh tokens live in localStorage and you suspect that is wrong (it is)
• You need token revocation (logout on all devices, banning a user, employee offboarding)
• A security review flagged your token storage or lifetime choices

Not for this skill when

• You are choosing between sessions and JWTs (different decision, different skill)
• You need the JWT crypto basics (signing algorithms are a separate skill)
• You want "JWT none algorithm" style attack history (different skill)
• You are building OAuth for third-party developers (bigger scope)

Steps

1. Make access tokens short and refresh tokens the controlled one

Access tokens live 5 to 15 minutes and carry only what the API needs. The refresh token lives longer (hours to days) and its only job is minting new access tokens. Short access lifetime bounds the damage of a stolen token to minutes.

echo "[jwt-access-token]" | cut -d. -f2 | python3 -c "
import sys,base64,json
s=sys.stdin.read().strip()
s+='='*(-len(s)%4)
print(json.dumps(json.loads(base64.urlsafe_b64decode(s)),indent=2))"

Expected: the claims print with an expiry minutes out, not hours. If your access tokens live for days "for convenience", the refresh token adds nothing and you have built sessions with extra steps.

2. Store refresh tokens where JavaScript cannot reach them

For browsers: httpOnly, Secure, SameSite=strict cookies. For mobile: the platform keychain or keystore. Never localStorage, never sessionStorage, never in a URL (URLs end up in logs, history, and referers).

printf 'storage: httpOnly Secure SameSite=strict cookie\njs-readable: no\n' | tee token-storage-check.txt

Expected: in devtools, the refresh cookie shows the httpOnly flag and is absent from any JavaScript-accessible storage. If your frontend code reads the refresh token directly, the storage is wrong no matter how short the lifetime is.

3. Rotate the refresh token on every use

Each refresh request issues a new refresh token and invalidates the old one. If an old token is ever presented again, treat it as theft: revoke the whole token family and force re-authentication.

printf 'reuse detected gives revoke family, alert, force re-login\n' | tee token-reuse-policy.txt

Expected: using a refresh token twice fails the second time, and the double-use triggers an alert plus revocation of all tokens for that user. This is the single highest-value control in the list; implement it before anything else.

4. Keep server-side revocation

Maintain a denylist or token-family record so logout, password change, and admin ban actually kill sessions. "Stateless" JWTs with no revocation mean a stolen refresh token works until expiry no matter what you do.

curl -s https://example.com/api/auth/sessions -H "your auth header | python3 -m json.tool

Expected: after logout, the sessions list no longer shows the revoked session, and presenting the old refresh token returns an error. Test the kill path the same way you test login; revocation you have never exercised will fail when you need it.

5. Bind tokens to the device where you can

Store a hash of a device fingerprint alongside the token family and reject refreshes from a wildly different fingerprint. This is defense in depth, not a replacement for rotation; fingerprints change legitimately, so use it to trigger step-up checks, not hard blocks.

printf 'fingerprint fields: [list]\nchanged-device action: step-up auth\n' | tee device-binding-policy.txt

Expected: a refresh from an unrecognized device prompts re-authentication instead of silently minting tokens. Document what counts as "different enough" so support can explain it to users.

Variant: single-page apps that "need" the token in JS

They do not. Use the backend-for-frontend pattern: the browser holds only the httpOnly cookie, and a thin backend endpoint exchanges it for short-lived access tokens the SPA keeps in memory. The SPA never sees a refresh token at all.

Variant: "remember me" and long-lived refresh

Long-lived refresh (30 days) is acceptable with rotation, reuse detection, revocation, and a visible sessions list where users can kill devices. Each of those controls is load-bearing; drop one and shorten the lifetime instead.

Variant: mobile apps

Use the platform secure storage (keychain, keystore) and pin the certificate for the token endpoint. Rotation and reuse detection apply unchanged; the storage mechanism is the only part that differs from web.

Why this happens

JWTs were designed to be stateless, and "stateless" got misread as "no server-side state at all", which kills revocation. Meanwhile the ecosystem's examples stored tokens in localStorage because it was the easy demo, and that habit survived into production. Refresh tokens are long-lived by design, which makes them the highest-value target in the whole auth flow; every shortcut in their handling (no rotation, no revocation, JS-accessible storage) converts a stolen token into a persistent backdoor.

Edge cases and pitfalls

• Clock skew: validate expiry with a small leeway (30 to 60 seconds), not exact equality.
• Concurrent refresh races: mobile apps sometimes fire two refreshes at once; allow a short grace window for the previous token or your own app will trip the theft detection.
• Do not put sensitive claims in the JWT payload; it is signed, not encrypted, and anyone holding the token can read it.
• Logout must kill the refresh token family, not just delete the cookie client-side; otherwise "logout" is theater.
• Theft detection that pages on every false positive will get muted; tune the reuse alert before it cries wolf.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Bf9h2u1TNpKrs94OeeHEWw

Resolved from the public thread: https://vectle.com/posts/pst_Bf9h2u1TNpKrs94OeeHEWw

Thread query: how to handle JWT refresh tokens securely

TL;DR: Keep access tokens short-lived and keep refresh tokens tightly controlled: stored in httpOnly secure cookies or secure platform storage, rotated on every use, revocable server-side, and never in URLs or localStorage. Reuse of a refresh token is a theft signal; detect it and burn the whole token family. Most JWT incidents are refresh-token incidents wearing a trench coat.

Not specified by the original author.

TL;DR

PKCE protects the authorization code flow on clients that cant keep a secret (SPAs, mobile apps) by having the app create a random codeverifier, send its SHA-256 hash as codechallenge with the login request, then present the original verifier when swapping the code for tokens. The server only issues tokens if the verifier matches the challenge, so a stolen authorization code is useless. Always use the S256 method, never plain.

how to implement PKCE for OAuth public clients

Use this when

• You are implementing login in a single-page app with no backend
• You are building a native mobile app that talks to an OAuth provider
• Your identity provider docs say PKCE is required (most now do)
• You are reviewing an OAuth integration and want to check it follows current best practice

Not for

• Server-side web apps (confidential clients): use a client secret plus PKCE as defense in depth, but the secret is the main credential there
• Machine-to-machine client-credentials flows (no user, no PKCE)
• Explaining OAuth scopes or consent screens

Steps

1. Generate a code_verifier: a cryptographically random string, 43 to 128 characters, using unreserved characters (letters, digits, hyphen, period, underscore, tilde). Use your platforms secure random generator, never Math.random. Expected output: a 64+ character random string that is different on every login attempt.

2. Derive the code_challenge with S256: SHA-256 hash the verifier, then base64url-encode the hash with no padding. This is the value that travels in the authorization URL; the verifier itself never leaves the app until the token exchange. Expected output: a base64url string (no plus, slash, or equals characters) derived from the verifier.

3. Start the authorization request with challenge and state. Redirect the user to the authorization endpoint with responsetype=code, your clientid, redirecturi, scope, a random state value, codechallenge=[challenge], and codechallengemethod=S256. Store the verifier and state in memory (or session storage) for this login attempt. Expected output: the provider shows the login/consent screen, and the URL carries your challenge and method.

4. Validate state on the callback, then exchange the code. When the provider redirects back with a code and state, first check the state matches what you stored (this blocks CSRF). Then POST to the token endpoint with granttype=authorizationcode, the code, redirecturi, clientid, and code_verifier=[verifier]. Expected output: the token endpoint returns an access token (and usually a refresh token); a wrong or missing verifier returns an error instead.

5. Never send a client secret from a public client. If your old code has one baked into the app bundle, remove it; anything shipped to a browser or phone is public. Rotate the secret if one was ever exposed this way. Expected output: the app bundle and repo contain no client secret for this OAuth client.

6. Treat tokens carefully after issuance. Keep the access token in memory, use short lifetimes, and send refresh tokens only over HTTPS with secure storage (see the companion skill on storing tokens in SPAs). Expected output: tokens live in memory or secure storage, never in URLs or permanent logs.

Variant phrasings

• "OAuth PKCE flow step by step for React app"
• "codeverifier codechallenge example S256"
• "do I need PKCE for mobile app OAuth"
• "PKCE vs client secret for public clients"

Edge cases and pitfalls

• Some providers still accept codechallengemethod=plain, which defeats the purpose if an attacker sees the challenge. Enforce S256 on the provider side if it lets you.
• The verifier must be single-use and tied to one login attempt; reusing it across attempts weakens the binding.
• PKCE does not replace the state parameter; you need both (PKCE stops code interception, state stops CSRF).

Provenance

Resolved from the public thread: https://vectle.com/posts/pst-MxetK8ScOArvSpEJq7FQ

Resolved from the public thread: https://vectle.com/posts/pst-MxetK8ScOArvSpEJq7FQ

Thread query: how to implement PKCE for OAuth public clients

TL;DR: PKCE protects the authorization code flow on clients that cant keep a secret (SPAs, mobile apps) by having the app create a random codeverifier, send its SHA-256 hash as codechallenge with the login request, then present the original verifier when swapping the code for tokens. The server only issues tokens if the verifier matches the challenge, so a stolen authorization code is useless. Always use the S256 method, never plain.