1 JWT Fundamentals — Anatomy & Threat Model

A JSON Web Token (JWT) is a compact, URL-safe way to represent claims between two parties. Every JWT has three dot-separated Base64url-encoded parts:

JWS vs JWE — Signed vs Encrypted

The standard distinguishes two token types that are often confused:

The Real Threat Model

Before choosing any security mechanism, be precise about what you're protecting against:

2 Authorization Code + PKCE Flow

PKCE (Proof Key for Code Exchange, RFC 7636) is the mandatory security extension for public clients (SPAs, mobile apps) that cannot safely store a client secret. It prevents authorization code interception attacks by binding the code to a cryptographic challenge that only the legitimate client can answer.

The 8-Step PKCE Dance

Key Points for Architects

• The auth server never sees the code_verifier until the token exchange — it only stores the hash.
• The state parameter is a CSRF nonce — verify it matches exactly before proceeding.
• The authorization code is single-use and short-lived (typically 60 seconds).
• PKCE makes the client_secret unnecessary for public clients — do not include it in SPA code.
• The JWT returned contains all claims needed by the API — no separate user info call required.

3 Client Credentials Flow

The Client Credentials grant is for machine-to-machine communication — when a backend service needs to call another service, with no user involved. Think: auth server calling the resource API to sync a user profile, or a scheduled job calling the mail service.

4 Token Revocation: JWE vs Opaque vs Token Versioning

JWTs are stateless by design. Once issued, a JWT is valid until it expires — the API verifies it cryptographically without contacting the auth server. This is efficient but creates a problem: how do you revoke a token before it expires?

Token Versioning: How It Works in Detail

5 Token Storage: localStorage vs sessionStorage vs httpOnly Cookies

Where you store the access token is one of the most consequential frontend security decisions. Each option has a genuinely different threat profile — there is no universally correct answer.

6 Cross-Origin Token Hand-Off & Hash Security

When multiple frontend apps run on different origins (different ports in dev, same domain in prod), passing a token between them requires careful design. The naive approach — putting the token in a URL query parameter — is a serious vulnerability because query parameters appear in server logs, browser history, and Referer headers.

https://editor.app/callback
  ?access_token=eyJhbGc...
  &state=abc

https://editor.app/callback
  #token=eyJhbGc...

The Anti-Replay Guard (iat check)

The iat (issued-at) claim is the timestamp when the auth server signed the token. A legitimate PKCE hand-off happens within milliseconds. If you check that now - iat < 60 seconds, any token replayed from browser history, a server log, or a cached page is rejected — even if it hasn't expired yet.

// auth.service.ts — absorbHashToken() security guards
const payload = JSON.parse(atob(token.split('.')[1]));
const nowSec  = Date.now() / 1000;

// Guard 1: Token must not be expired
if (payload.exp && nowSec > payload.exp) { return; }

// Guard 2: Token must have a subject
if (!payload.sub) { return; }

// Guard 3: Anti-replay — reject if issued more than 60s ago
// Legitimate hand-offs happen in milliseconds. Replays fail.
if (payload.iat && nowSec - payload.iat > 60) { return; }

// Guard 4: Skip if valid token already exists (same-origin prod)
const existing = sessionStorage.getItem('app_token');
if (existing && decodeToken(existing) !== null) { return; }

sessionStorage.setItem('app_token', token);
window.history.replaceState({}, document.title, window.location.pathname);

7 Security Recommendations Checklist

Auth Server

• ✅
  Use RSA-256 or EC P-256 for JWT signing
  Persist the key pair to disk so it survives restarts. A new key on every restart invalidates all existing tokens. Plan a key rotation policy — rotate annually or immediately after a suspected compromise.
  Recommended
• ✅
  Hash passwords with bcrypt, scrypt, or Argon2
  Never store plaintext, MD5, or SHA-1 passwords. bcrypt cost factor ≥10 is the current baseline; Argon2id is the OWASP recommended choice for new systems.
  Recommended
• ✅
  Verify email addresses before activating accounts
  Issue a cryptographically random token (at least 128 bits), set a short expiry (24h), and keep the account in PENDING status until verified. Prevents account enumeration via registration.
  Recommended
• ✅
  Rate-limit authentication endpoints per IP
  Block IPs after repeated failures using a sliding window. A common policy: 5 failures → 5-min block, 10 failures → 60-min block. Apply to login, registration, password reset, and token endpoints.
  Recommended
• ✅
  Use PKCE for all browser and mobile OAuth2 flows
  RFC 7636 is mandatory for public clients. Never embed a client_secret in a SPA or mobile app. For social login (Google, GitHub), add prompt=select_account to force the account picker and prevent silent session reuse from a previous user's login.
  Recommended
• ⚠️
  Use constant-time comparison for all secret validation
  String equality in most languages short-circuits on the first byte mismatch, leaking information via timing. Use a constant-time function (e.g. MessageDigest.isEqual() in Java, hmac.compare_digest() in Python, crypto.timingSafeEqual() in Node.js) for any comparison involving API keys, HMAC signatures, or internal service tokens.
  Important
• ⚠️
  Plan a key rotation strategy
  RSA-2048 is still secure today but EC P-256 provides equivalent strength with significantly faster signing. Include key IDs (kid) in your JWKS from day one — this lets you publish multiple keys simultaneously and rotate without invalidating all existing tokens at once.
  Consider

Resource Server

• ✅
  Verify JWTs cryptographically using the JWKS endpoint
  Fetch the auth server's public key from its JWKS URI on startup. Verify the RSA or EC signature locally on every request — no per-request call to the auth server. Cache keys in memory; re-fetch when you encounter an unknown key ID (kid).
  Recommended
• ✅
  Implement token versioning for near-instant revocation
  Embed a version counter in the JWT at issuance. Increment it in the auth server's database whenever roles change or accounts are suspended. The resource server fetches the current version periodically (e.g. 5-minute cache) and rejects tokens whose embedded version is stale. This gives revocation within minutes at near-zero performance cost.
  Recommended
• ✅
  Apply token version checks consistently across all protected endpoints
  It is a common mistake to check revocation only on high-privilege (admin) endpoints. Apply the same check to all authenticated write operations — create, update, delete, publish — so a suspended account cannot continue writing even on lower-risk paths.
  Recommended
• ✅
  Rate-limit write endpoints per authenticated identity
  Apply limits per IP for unauthenticated paths and per user ID for authenticated ones. Reasonable defaults: 10–30 POST/PUT/DELETE requests per minute per user. Return 429 with a Retry-After header. Log repeated violations.
  Recommended
• ⚠️
  Fail safely when the auth server is unreachable
  If your token version check calls the auth server and the call fails, decide explicitly: fail-open (allow the request using a cached value) or fail-closed (deny). Fail-open is the common default for availability, but it means a revoked token remains valid during an auth server outage. Use the most recent cached version as a fallback, not a hard-coded permissive default.
  Important
• ⚠️
  Protect internal service-to-service endpoints
  Internal APIs called between your own services should require a pre-shared secret sent in a request header (e.g. X-Internal-Key). Validate it with constant-time comparison. These endpoints should never be reachable from the public internet — enforce this at the network/firewall level in addition to application-level auth.
  Recommended

Browser Client (SPA)

• ✅
  Store tokens in sessionStorage, not localStorage
  sessionStorage is tab-scoped and cleared when the tab closes, reducing the XSS attack window from "until the JWT expires" to "while the tab is open". An attacker who steals a token via XSS cannot persist it across browser sessions or access it from a different tab.
  Recommended
• 🎯
  Target: store tokens in httpOnly SameSite=Strict cookies
  This is the gold standard. The auth server sets the cookie after the PKCE callback; JavaScript never sees the token at all, eliminating the XSS token-theft surface. Requires CSRF protection — use the Double Submit Cookie pattern or the Synchronizer Token pattern.
  Best practice
• ✅
  Keep PKCE state in localStorage, token in sessionStorage
  The PKCE code_verifier, state nonce, and redirect target must survive the full-page redirect to the auth server and back — sessionStorage is wiped by cross-origin navigation. The access token itself does not need to survive cross-origin navigation, so sessionStorage is safe.
  Recommended
• ✅
  Validate PKCE state nonce before exchanging the code
  Compare the returned state parameter exactly against the stored value before calling the token endpoint. A mismatch indicates a CSRF attack or a replayed callback — abort the flow immediately.
  Recommended
• ✅
  Validate all claims when absorbing a URL hash token
  If you pass tokens via URL fragment between apps, validate: (1) 3-part JWT structure, (2) token is not expired, (3) sub claim is present, (4) issued-at (iat) gap is <60 seconds. The iat check prevents replay from browser history. Clear the hash with replaceState immediately after.
  Recommended
• ✅
  Deploy a strict Content Security Policy
  A CSP with script-src, connect-src, and style-src limits the blast radius of XSS. An XSS that cannot exfiltrate data is far less dangerous than one with open network access. Apply CSP at the HTTP header level (not only via meta tags) so it applies to all responses.
  Recommended

8 Decision Guide: Which Strategy for Which Scenario