Understanding JWT: JSON Web Tokens for Authentication

Introduction

JWT (JSON Web Token) has become the standard for modern web authentication. It's a compact, URL-safe way to transmit information between parties as a JSON object. Used for single sign-on, API authentication, and information exchange, understanding JWT is essential for building secure modern applications.

A JWT is a string consisting of three parts separated by dots:

xxxxx.yyyyy.zzzzz
│     │     │
│     │     └── Signature
│     └──────── Payload
└────────────── Header

JWT Structure

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

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

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

Standard Claims

• JWT payload is NOT encrypted: Anyone can decode and read it. Never put sensitive data (passwords, secrets) in the payload.
• Signature prevents tampering: Without the secret, attackers cannot modify the token without detection.
• Always set expiration: Tokens without expiration never expire - stolen tokens remain valid forever.
• Use HTTPS: JWTs sent over HTTP can be intercepted. Always use TLS for transmission.

JWT implementations are frequently the target of attacks. Understanding these vulnerabilities is essential for building secure authentication systems.

// Attacker modifies the header:
{
  "alg": "none",
  "typ": "JWT"
}

// And changes the payload to escalate privileges:
{
  "sub": "admin",
  "role": "superuser",
  "exp": 9999999999
}

// The resulting token has an empty signature:
eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJzdWIiOiJhZG1pbiIsInJvbGUiOiJzdXBlcnVzZXIiLCJleHAiOjk5OTk5OTk5OTl9.

// Node.js (jsonwebtoken)
jwt.verify(token, secret, { algorithms: ['HS256'] });

// Never accept "none" algorithm
// Never let the token header decide the algorithm

// Always specify the algorithm explicitly
jwt.verify(token, publicKey, { algorithms: ['RS256'] });

// Never use the algorithm from the token header
// Never use the same verification function for different algorithms

// Generate a strong secret (Node.js)
const crypto = require('crypto');
const secret = crypto.randomBytes(64).toString('hex');
// Result: 128 hex characters = 512 bits of entropy

// NEVER use:
// - "secret", "password", "my-secret-key"
// - Keys shorter than 256 bits (32 bytes)
// - Keys committed to public repositories

// Never trust keys from the token header
// Only use keys from your own trusted key store
// Disable jwk and jku header processing in your JWT library

JWT Best Practices Checklist

• Always whitelist algorithms - Never accept alg: "none". Specify expected algorithms explicitly in verification.
• Use strong secrets - Minimum 256-bit random keys for HS256. Use RS256/ES256 for distributed systems.
• Set short expiration - Access tokens: 15 minutes. Refresh tokens: 7 days with rotation.
• Store tokens securely - Use HttpOnly, Secure, SameSite cookies. Avoid localStorage for access tokens.
• Validate all claims - Check iss, aud, exp, and nbf on every request.
• Never put secrets in payload - JWT payload is Base64-encoded, not encrypted. Anyone can read it.
• Use JWE for sensitive data - If you need encrypted content, use JSON Web Encryption (JWE) instead of JWS.
• Implement refresh token rotation - Issue a new refresh token on each use and invalidate the old one.

Choosing the Right Algorithm

For most applications, RS256 is the best choice. It allows you to share the public key for verification while keeping the private key secure on the auth server. ES256 produces shorter signatures but requires more complex key management.

Implementation Example (Node.js)

import jwt from "jsonwebtoken";

const ACCESS_TOKEN_SECRET = process.env.ACCESS_TOKEN_SECRET!;
const REFRESH_TOKEN_SECRET = process.env.REFRESH_TOKEN_SECRET!;

// Generate tokens
function generateTokens(userId: string) {
  const accessToken = jwt.sign(
    { sub: userId, type: "access" },
    ACCESS_TOKEN_SECRET,
    { algorithm: "HS256", expiresIn: "15m" }
  );

  const refreshToken = jwt.sign(
    { sub: userId, type: "refresh" },
    REFRESH_TOKEN_SECRET,
    { algorithm: "HS256", expiresIn: "7d" }
  );

  return { accessToken, refreshToken };
}

// Verify access token
function verifyAccessToken(token: string) {
  try {
    const payload = jwt.verify(token, ACCESS_TOKEN_SECRET, {
      algorithms: ["HS256"],  // Always whitelist!
    });
    return { valid: true, payload };
  } catch (error) {
    return { valid: false, error };
  }
}

Related Tools