Chapter 3 — JWT Deep Dive

The why

JWT (JSON Web Token) is the most widely used authentication token format — and the most widely misused. Most online tutorials teach JWT wrong: no refresh tokens, no revocation, secrets in code, alg: none vulnerabilities. This chapter teaches JWT the way production systems actually use it.

Core concepts

JWT anatomy

A JWT is three base64url-encoded strings separated by dots:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIsInJvbGUiOiJ1c2VyIiwiZXhwIjoxNzE1NjAwMDAwfQ.abc123def456
|___________HEADER_____________|___________________PAYLOAD______________________|_____SIGNATURE_____|

Header: Algorithm + token type.

{ "alg": "HS256", "typ": "JWT" }

Payload (claims):

{
  "sub": "42",           // subject (user ID)
  "role": "user",        // custom claim
  "iat": 1715596400,     // issued at
  "exp": 1715600000      // expiration (1 hour)

Signature: HMACSHA256(base64(header) + "." + base64(payload), secret)

Signing and verifying JWTs

const jwt = require('jsonwebtoken');
const SECRET = process.env.JWT_SECRET; // at least 32 random bytes, base64 encoded
 
// Sign (create)
function createToken(userId, role) {
  return jwt

HMAC (HS256) vs RSA (RS256)

// RS256 — auth service signs, API services verify with public key
const privateKey = fs.readFileSync('private.pem');
const publicKey = fs.readFileSync('public.pem');
 
// Auth service: sign with private key
const token = jwt.

The refresh token flow (how JWTs are actually used)

JWTs should be short-lived (15 minutes to 1 hour). If a JWT is stolen, the attacker has a limited window. But forcing users to log in every 15 minutes is terrible UX. Enter refresh tokens.

1. User logs in → server returns:
   - Access token (JWT, 15 min expiry)
   - Refresh token (opaque random string, 7 day expiry, stored in DB)
 
2. User makes API request → sends access token in Authorization header
   - Server verifies JWT signature + expiry (no DB query needed!)
 
3. Access token expires → client sends refresh token to /auth/refresh
   - Server looks up refresh token in DB
   - If valid + not revoked → issues new access token + new refresh token
   - If revoked/expired → 401, user must log in again
 
4. Refresh token rotation: every /auth/refresh issues a NEW refresh token
   - Old refresh token is invalidated
   - If a stolen refresh token is used, the legitimate user's next refresh attempt
     fails → server detects token reuse → revokes ALL tokens for that user

// Simplified refresh token implementation
const crypto = require('crypto');
 
async function login(req, res) {
  const user = await authenticateUser(req.body.email, req.

JWT revocation (yes, it's possible)

"JWTs can't be revoked" is the most repeated myth. Here's how:

// Blocklist approach (Redis)
async function revokeToken(jti, expiresAt) {
  const ttl = Math.ceil((expiresAt * 1000 - Date.now()) / 1000);
  await redis.set(`blocklist:

When NOT to use JWT

JWT is not always the answer:

Real-world example: How Auth0 uses JWTs

Auth0 (now part of Okta) is the most popular JWT-based identity platform. Their design:

1. RS256 by default. Auth0 signs tokens with a private key. Your API verifies with Auth0's public JWKS endpoint (/.well-known/jwks.json). Your API never sees the private key.
2. Short-lived access tokens (default: 24 hours, configurable down to minutes). Refresh tokens for long-lived sessions.
3. JWKS endpoint for key rotation. Auth0 publishes public keys at a well-known URL. Your API fetches them, caches them, and automatically handles key rotation without configuration changes.
4. Custom claims via Rules/Actions. Add app_metadata, permissions, roles to the JWT payload. Your API reads claims directly — no DB lookup needed.

Common mistakes

Production notes

• Use RS256 or ES256 for microservice architectures. HMAC (HS256) requires sharing the secret with every service that needs to verify tokens. RSA/ECDSA lets you share only the public key.
• JWKS endpoint for key rotation. Publish public keys at /.well-known/jwks.json. Rotate keys every 90 days. Old keys stay published until all tokens signed with them have expired.
• Validate EVERY claim. iss (issuer), aud (audience), exp, nbf, iat. A token from a different issuer or for a different audience should be rejected.

Performance notes

• JWT verification is fast (~0.1ms) because it's a cryptographic operation, not a database query. This is JWT's primary advantage over sessions.
• Token size matters. A JWT with many claims can exceed 4 KB. This adds 4 KB to every HTTP request. Keep claims minimal — user ID, role, and timestamps only.
• Redis blocklist adds ~0.5ms per request. Use it only for tokens that need immediate revocation (admin tokens, sensitive operations).

Security notes

• Never use alg: none. Always specify accepted algorithms: algorithms: ['HS256'].
• Validate iss and aud claims. Prevents token reuse across different applications.
• Use HTTPS everywhere. JWTs in HTTP headers are visible to anyone on the network without TLS.

Exercises

Beginner

1. Write a script that creates a JWT with user ID and role claims, then verifies it. Test with: correct secret, wrong secret, expired token.
2. Create an Express route protected by JWT middleware. Return 401 if no token, 401 if invalid, and the protected resource if valid.

Intermediate

1. Implement the full refresh token flow: login returns access + refresh tokens. A /refresh endpoint accepts a refresh token and returns new tokens. Implement refresh token rotation.
2. Set up RS256: generate a key pair with openssl. Sign JWTs with the private key. Verify with the public key. Test that a token signed with the wrong key is rejected.

Advanced

1. Implement token reuse detection: when a refresh token is used, invalidate the old one. If an already-invalidated token is presented, revoke ALL refresh tokens for that user (assume token theft).
2. Implement a JWKS endpoint that publishes your public keys. Write a client that fetches the JWKS, caches it, and automatically handles key rotation.

Interview questions

Beginner

1. What are the three parts of a JWT? Header (algorithm + type), Payload (claims — user ID, role, expiry), Signature (cryptographic proof the token hasn't been tampered with).

2. Why shouldn't you store a JWT in localStorage? Any JavaScript on the page can read localStorage — including malicious code from XSS attacks, third-party scripts, or browser extensions. Use HttpOnly cookies instead.

3. What is the benefit of short-lived access tokens? If a token is stolen, the attacker has a limited window (15 minutes) to use it. With refresh tokens, the legitimate user gets new access tokens seamlessly.

Senior

4. Explain the refresh token rotation pattern and why it's important. Every time a refresh token is used, the server issues a NEW refresh token and invalidates the old one. If an attacker steals a refresh token and uses it, the legitimate user's next refresh attempt fails (their token was invalidated). The server detects this reuse and revokes all tokens for that user. Without rotation, a stolen refresh token gives permanent access until it expires.

5. When would you use RS256 over HS256? In microservice architectures where an auth service signs tokens and multiple API services verify them. RS256 lets API services verify tokens with only a public key — they can't create new tokens. HS256 requires sharing the secret with every service, which means compromising any service compromises the entire auth system.

6. How do you revoke a JWT? Short-lived access tokens (15 min) + revocable refresh tokens is the primary strategy. For immediate revocation: maintain a blocklist (Redis) of revoked JWT IDs (jti) with TTL matching the token's remaining life. Check the blocklist on every request. Alternatively, include a token_version claim in the JWT and increment the user's version on logout — the JWT becomes invalid because the version doesn't match.

Summary

JWT is a stateless token format — the server can verify it without a database query. Use short-lived access tokens (15 min) + refresh tokens (7 days) with rotation. Sign with RS256 for microservices, HS256 for monoliths. Never store JWTs in localStorage. Never accept alg: none. Always validate iss, aud, and exp claims. Revocation is possible via short expiry + blocklist or token versioning. JWTs are not encrypted — the payload is readable by anyone with the token.

Quick recall

• JWT = Header.Payload.Signature. Base64-encoded, NOT encrypted.
• HS256 (shared secret) for monoliths. RS256 (public/private key) for microservices.
• Access token: 15 min. Refresh token: 7 days, rotated on every use.
• Never store JWT in localStorage. Use HttpOnly cookies or BFF pattern.
• Validate iss, aud, exp, nbf. Never accept alg: none.
• Revoke via short expiry + blocklist (Redis) or token versioning.

Quiz

1. Are JWTs encrypted? No — they're base64-encoded. Anyone can decode the payload. Never put secrets in JWT claims.
2. What does alg: none do and why is it dangerous? It tells the library to skip signature verification entirely. An attacker can create a valid-looking token with any payload. Always whitelist specific algorithms.
3. What's the difference between an access token and a refresh token? Access token: short-lived (15 min), sent with every API request, stateless (verified without DB). Refresh token: long-lived (7 days), used only once per 15 min to get new access tokens, stored in DB and revocable.
4. Why rotate refresh tokens? To detect theft — if a stolen refresh token is used, the legitimate user's next attempt fails, and the server can revoke all tokens for that user.
5. Why use RS256 in microservices? API services verify with public key only. They can't create tokens. Compromising an API service doesn't compromise the auth system.
6. How do you store JWTs securely in a browser? HttpOnly, Secure, SameSite=Strict cookie. Not accessible to JavaScript, automatically sent with requests, protected against XSS.
7. What's the advantage of JWTs over session tokens? Stateless verification — no database/Redis lookup needed per request. The token itself contains the user identity and claims that the server can trust after signature verification.