how to handle JWT refresh tokens securely

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.