JWT (JSON Web Tokens) - AI-Optimized Technical Reference

Overview

JWT is a token-based authentication standard (RFC 7519) that embeds user data directly in the token instead of server-side storage. Primary trade-off: horizontal scalability vs. token revocation impossibility.

Critical Failure Modes

Token Revocation Impossibility

• Problem: JWTs cannot be revoked once issued
• Impact: Compromised tokens remain valid until expiration
• Consequence: Stolen laptops/devices can maintain unauthorized access for token lifetime
• Mitigation: 15-minute maximum expiration (industry learned standard)

Algorithm Confusion Attacks

• Vulnerability: Attackers change algorithm from RS256 to HS256, using public key as HMAC secret
• Frequency: Common enough to be mentioned in every security guide
• Real incident: Startup with public key in repo - 10 minutes to forge admin tokens
• Fix: Always specify allowed algorithms in verification code

"None" Algorithm Bypass

• Attack: Setting alg: "none" makes unsigned tokens valid
• Real incident: Fintech company - intern accessed any account by removing signature
• Impact: Complete authentication bypass

Technical Specifications

Structure

header.payload.signature (three base64-encoded parts)

Performance Impact

• Size: 400-800 bytes vs 32 bytes for session IDs
• CPU overhead: 1-3ms per request vs 0.1ms for Redis session lookup
• Scale threshold: Noticeable at 1000+ requests/second

Critical Claims

• exp (Expiration): Must be ≤15 minutes (security requirement)
• sub (Subject): User ID - primary key reference
• iat (Issued At): Debug timestamps (timezone issues common)

Configuration That Works in Production

Secret Requirements

• Minimum: 32 random bytes for HS256
• Common failure: "secret", "password123", or hardcoded values
• Storage: Environment variables only, never in code

Verification Code (Node.js)

jwt.verify(token, secret, {
  algorithms: ['HS256'],        // NEVER trust header
  audience: 'api.myapp.com',    // Prevent cross-service reuse
  issuer: 'auth.myapp.com',     // Verify issuer
  maxAge: '15m'                 // Double-check expiration
});

Storage Security

• Never: localStorage (XSS vulnerability)
• Better: httpOnly cookies with secure, sameSite flags
• Best: In-memory storage with refresh token pattern

Resource Requirements

Implementation Time

• Simple setup: 1-2 days
• Production-ready with security: 1-2 weeks
• Microservices integration: 2-4 weeks (token passing complexity)

Expertise Required

• Understanding of crypto signatures
• Knowledge of web security (XSS, CSRF)
• Debugging skills for timestamp/timezone issues

Infrastructure Costs

• Stateless benefit: No session storage needed
• Reality: Redis instance for token blacklisting (defeats stateless purpose)
• Scaling: Linear CPU cost increase per request

Critical Warnings

What Documentation Doesn't Tell You

1. Logout is fake - JWT logout cannot truly revoke tokens
2. Debugging is painful - "invalid token" errors with no context
3. Timezone hell - Docker containers with different timezones break iat validation
4. Library version traps - PyJWT 2.0+ requires explicit audience validation (breaking change)

Breaking Points

• UI debugging limit: Becomes "nightmare" with complex token chains
• Token chain complexity: Service-to-service calls become "relay race"
• Memory pressure: Token caching defeats stateless benefits

Hidden Costs

• Human time: Extensive debugging sessions (3+ hours common)
• Security audit failures: Every vulnerability mentioned appears in production
• Migration pain: Moving from sessions requires complete auth rewrite

Decision Criteria

When JWT is Worth It

• Mobile APIs (cookies don't work well)
• Microservices with scaling requirements
• Third-party API integration
• Horizontal scaling requirements

When Sessions are Better

• Web applications requiring logout
• High-security applications (banking)
• Internal admin tools
• When simplicity matters more than scale

Trade-off Matrix

Factor	JWT	Sessions
Scalability	Excellent	Database-limited
Security	Complex	Simpler
Logout	Impossible	Works
Debugging	Difficult	Straightforward
Infrastructure	Eventually needs Redis	Needs session store

Library Recommendations

Production-Tested Libraries

• Node.js: jsonwebtoken (battle-tested, extensive Stack Overflow support)
• Python: PyJWT (solid, watch for version breaking changes)
• Java: Spring Security JWT (if using Spring Boot ecosystem)

Libraries to Avoid

• Custom implementations (never roll your own crypto)
• Libraries without explicit algorithm specification support
• Any library supporting "none" algorithm by default

Common Implementation Patterns

Refresh Token Pattern

• Access token: 15 minutes (in memory)
• Refresh token: 1-7 days (httpOnly cookie)
• Automatic refresh on 403 responses

Blacklist Implementation

// Redis blacklist for "stateless" tokens
const blacklisted = await redis.get(`blacklist:${tokenId}`);
if (blacklisted) return false;

Microservices Token Passing

• Include user context in service-to-service calls
• Alternative: mTLS for internal communication (often simpler)
• Key rotation requires multi-key support with kid headers

Operational Intelligence

Monitoring Requirements

• Token validation failure rates
• Blacklist hit rates (if implemented)
• Token size distribution
• Refresh token usage patterns

Incident Response

• Token compromise: Wait for expiration (15 minutes max)
• Secret compromise: Immediate rotation required, expect downtime
• Algorithm confusion detected: Emergency deployment with explicit algorithm validation

Migration Considerations

• Sessions → JWT: Complete authentication rewrite required
• JWT → Sessions: User re-authentication required
• Cross-service migration: Coordinate deployment across all services