JWT

## Quick Reference | Topic | File | |-------|------| | Algorithm selection | `algorithms.md` | | Token lifecycle | `lifecycle.md` | | Validation checklist | `validation.md` | | Common attacks | `attacks.md` | ## Security Fundamentals - JWTs are signed, not encrypted—anyone can decode and read the payload; never store secrets in it - Always verify signature before trusting claims—decode without verify is useless for auth - The `alg: none` attack: reject tokens with algorithm "none"—some libraries accepted unsigned tokens - Use strong secrets: HS256 needs 256+ bit key; short secrets are brute-forceable ## Algorithm Choice - HS256 (HMAC): symmetric, same key signs and verifies—good for single service - RS256 (RSA): asymmetric, private key signs, public verifies—good for distributed systems - ES256 (ECDSA): smaller signatures than RSA, same security—preferred for size-sensitive cases - Never let the token dictate algorithm—verify against expected algorithm server-side ## Required Claims - `exp` (expiration): always set and verify—tokens without expiry live forever - `iat` (issued at): when token was created—useful for invalidation policies - `nbf` (not before): token not valid until this time—for scheduled access - Clock skew: allow 30-60 seconds leeway when verifying time claims ## Audience & Issuer - `iss` (issuer): who created the token—verify to prevent cross-service token theft - `aud` (audience): intended recipient—API should reject tokens for other audiences - `sub` (subject): who the token represents—typically user ID - Token confusion attack: without aud/iss validation, token for Service A works on Service B ## Token Lifecycle - Access tokens: short-lived (5-15 min)—limits damage if stolen - Refresh tokens: longer-lived, stored securely—used only to get new access tokens - Refresh token rotation: issue new refresh token on each use, invalidate old one - Revocation is hard—JWTs are stateless; use short expiry + refresh, or maintain blacklist ## Storage - httpOnly cookie: immune to XSS, but needs CSRF protection - localStorage: vulnerable to XSS, but simpler for SPAs - Memory only: most secure, but lost on page refresh - Never store in URL parameters—visible in logs, history, referrer headers ## Validation Checklist - Verify signature with correct algorithm (don't trust header's alg) - Check `exp` is in future (with clock skew tolerance) - Check `iat` is not unreasonably old (optional policy) - Verify `iss` matches expected issuer - Verify `aud` includes your service - Check `nbf` if present ## Common Mistakes - Storing sensitive data in payload—it's just base64, not encrypted - Huge payloads—JWTs go in headers; many servers limit header size to 8KB - No expiration—indefinite tokens are security nightmares - Same secret across environments—dev tokens work in production - Logging tokens—they're credentials; treat as passwords ## Key Rotation - Use `kid` (key ID) claim to identify which key signed the token - JWKS (JSON Web Key Set) endpoint for public key distribution - Overlap period: accept old key while transitioning to new - After rotation, old tokens still valid until they expire—plan accordingly ## Implementation - Use established libraries—don't implement JWT parsing yourself - Libraries: `jsonwebtoken` (Node), `PyJWT` (Python), `java-jwt` (Java), `golang-jwt` (Go) - Middleware should reject invalid tokens early—before any business logic