JSON Web Token (JWT): Authentication and Security Guide

What is JWT?

JWT (JSON Web Token) is a compact, URL-safe token format defined in RFC 7519, used for secure information exchange between parties.

JWT consists of three parts: Header, Payload and Signature. These three parts are separated by dots (.): xxxxx.yyyyy.zzzzz

Provides stateless authentication. Instead of storing session data in a database, the server sends the token to the client. The client sends the token with every request.

Use cases: API authentication, SSO (Single Sign-On), authentication between microservices, mobile app authorization.

JWT Structure

Header: Contains token type (JWT) and signing algorithm (HS256, RS256, ES256). Base64URL encoded.

Payload: Contains claims. Registered claims (iss, sub, aud, exp, nbf, iat, jti), public claims and private claims. Base64URL encoded.

Signature: The Base64URL encoded header and payload are joined with a dot and signed with a secret key. HS256 uses HMAC-SHA256, RS256 uses RSA-SHA256.

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

JWT Usage Flow

1. User sends a request to the login endpoint with username and password.

2. Server verifies credentials and creates a JWT. Token is returned in response body or cookie.

3. Client stores the token in localStorage or httpOnly cookie.

4. In subsequent requests, client sends JWT as Bearer token in Authorization header: Authorization: Bearer <token>

5. Server validates the token (signature and expiry check). If valid, processes the request; if invalid, returns 401 Unauthorized.

Security Risks

Token theft: Token in localStorage can be stolen via XSS attack. Use httpOnly cookie to reduce XSS risk.

Token lifetime: Short-lived access token (15-30 min) + long-lived refresh token (7-30 days). Rotate refresh token on each use.

Algorithm confusion: 'none' algorithm or RS256→HS256 switch. Set algorithm as a constant on server side, don't take from token.

Sensitive data: JWT payload is Base64 encoded, not encrypted. Don't put sensitive data (password, credit card) in payload.

Token size: JWT is larger than session cookie. Sent with every request. Keep payload minimal.

Best Practices

Short-lived tokens: Access token 15-30 minutes, refresh token 7-30 days. Expired tokens automatically become invalid.

httpOnly + Secure + SameSite cookie: Store token in httpOnly cookie. JavaScript cannot access (XSS protection). Secure (HTTPS only). SameSite (CSRF protection).

Token rotation: Refresh token is renewed on each use. Old refresh token becomes invalid. Limits attacker access in case of token theft.

Blacklist/revocation: Use blacklist to revoke tokens. Store revoked tokens in Redis. Use for logout and security incidents.

Algorithm: RS256 (asymmetric) recommended for production. Sign with private key, verify with public key. HS256 (symmetric) only for single service.

Validation: Verify signature, issuer (iss), audience (aud), expiry (exp) on every request. Ensure all checks pass before trusting the token.

JWT vs Session-Based Authentication

JWT: Stateless, easy horizontal scaling, ideal for microservices, large token size, hard to revoke.

Session: Stateful, requires server-side storage, needs sticky session or shared store for horizontal scaling, small token size, easy to revoke.

Selection criteria: Microservice architecture → JWT. Monolithic application → Session. Mobile app → JWT. High security requirement → Session + JWT hybrid.

Hybrid approach: Short-lived JWT (access token) + session store (refresh token). Combines advantages of both.