JWT Explained

What is a JWT?

A JWT (JSON Web Token) is a compact, URL-safe token format for securely transmitting claims between two parties. JWTs are the most popular method for API authentication — when you log into a web application, you likely receive a JWT that proves your identity on subsequent requests.

JWTs are defined in RFC 7519. They're self-contained: the token itself carries the user's identity, roles, and permissions. The server doesn't need to look up a session in a database — it just verifies the token's signature.

JWT Structure

A JWT consists of three parts separated by dots:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

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

{
  "sub": "1234567890",
  "name": "John Doe",
  "role": "admin",
  "iat": 1516239022,
  "exp": 1516242622
}

HMACSHA256(base64url(header) + "." + base64url(payload), secret)

Standard Claims

How JWT Authentication Works

1. User sends username + password to POST /login
2. Server verifies credentials, creates a JWT with user claims, signs it with a secret key
3. Server returns the JWT to the client
4. Client stores the JWT (usually in memory or httpOnly cookie)
5. Client sends JWT in Authorization: Bearer <token> header on every request
6. Server verifies the signature and reads claims from the payload — no database lookup needed

Signing Algorithms

• HS256 (HMAC-SHA256) — Symmetric. Same secret key signs and verifies. Simple, fast. Good for single-server setups.
• RS256 (RSA-SHA256) — Asymmetric. Private key signs, public key verifies. Best for microservices where multiple services verify tokens.
• ES256 (ECDSA-SHA256) — Asymmetric. Smaller keys and signatures than RSA. Recommended for new projects.

Security Best Practices

• Always validate the signature — never trust an unverified JWT.
• Check expiration (exp) — reject expired tokens. Use short lifetimes (15 min for access tokens).
• Validate issuer (iss) and audience (aud) — prevent token confusion attacks.
• Never accept "alg": "none" — this disables signature verification entirely.
• Store in httpOnly cookies — not localStorage, which is vulnerable to XSS.
• Use refresh tokens — short-lived access tokens (15 min) + long-lived refresh tokens (7 days).
• Use strong secrets — HS256 keys should be at least 256 bits of random data.

JWT vs Session Cookies