JWT — Deep Dive

Level: Intermediate
Pre-reading: 08 · Security Summary · 08.01 · OAuth2 & OIDC

Anatomy of a JWT

A JWT is three Base64URL-encoded parts separated by dots:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9   ← Header
.eyJzdWIiOiJ1c2VyMTIzIiwiZXhwIjoxNzE...  ← Payload
.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV...   ← Signature

Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-2024"
}

Payload (Claims)

{
  "sub": "user-123",
  "iss": "https://auth.example.com",
  "aud": "https://api.example.com",
  "exp": 1713000000,
  "iat": 1712996400,
  "jti": "unique-token-id",
  "roles": ["admin", "user"],
  "email": "user@example.com"
}

Signature

• RS256 (asymmetric): Auth Server signs with private key; anyone can verify with the public key from JWKS endpoint. Preferred for distributed systems.
• HS256 (symmetric): Shared secret signs and verifies. Requires every service to know the secret — secret sprawl risk. Only acceptable for internal monolithic systems.

RS256 vs HS256 — Which to Use?

JWKS — Key Discovery and Rotation

Every standards-compliant Auth Server publishes its public keys at:

GET https://auth.example.com/.well-known/jwks.json

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "key-id-2024",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

Your service uses the kid in the JWT header to look up the correct key. This enables zero-downtime key rotation — publish a new key, old tokens still validate with old kid, new tokens use new kid.

Complete Validation Checklist

graph TD
    A[Receive JWT] --> B[Decode header - no verification yet]
    B --> C[Look up kid in JWKS cache]
    C --> D{Key found?}
    D -->|No| E[Refresh JWKS from endpoint]
    E --> F{Key found?}
    F -->|No| G[Reject 401]
    F -->|Yes| H[Verify signature]
    D -->|Yes| H
    H --> I{Signature valid?}
    I -->|No| G
    I -->|Yes| J[Check exp - not expired]
    J --> K{Expired?}
    K -->|Yes| G
    K -->|No| L[Check iss matches config]
    L --> M{iss valid?}
    M -->|No| G
    M -->|Yes| N[Check aud matches this service]
    N --> O{aud valid?}
    O -->|No| G
    O -->|Yes| P[Check alg is in allowlist]
    P --> Q{alg allowed?}
    Q -->|No| G
    Q -->|Yes| R[Token Valid - extract claims]

Security Vulnerabilities — Know These Cold

1. Algorithm Confusion (alg: none)

An attacker modifies the header to "alg": "none" and removes the signature. A naive library might accept this.

Fix: Explicitly configure your library with the expected algorithm — never derive it from the token itself.

// WRONG — trusts whatever algorithm the token claims
JWTVerifier verifier = JWT.require(Algorithm.none()).build();

// CORRECT — explicitly specify RS256
JWTVerifier verifier = JWT.require(Algorithm.RSA256(publicKey)).build();

2. RS256 → HS256 Downgrade

If a server accepts both RS256 and HS256, an attacker can take the public key (which is public!) and sign a forged token with HS256 using the public key as the HMAC secret.

Fix: Never accept both RS256 and HS256 for the same endpoint. Pin the algorithm.

3. Missing aud Validation

A token issued for Service A is replayed against Service B.

Fix: Always validate aud matches this specific service's identifier.

4. Sensitive Data in Payload

JWT payload is only Base64 encoded — it is not encrypted. Any party with the token can decode and read the payload.

Fix: Never store passwords, PII, credit card numbers, or secrets in JWT claims. Use JWE (JSON Web Encryption) if you need encrypted tokens.

5. JWT Replay Attacks

A stolen valid JWT can be replayed until it expires.

Fix options:

• Keep expiry short (exp ≤ 15 minutes for access tokens)
• Use jti claim + maintain a denylist for sensitive operations
• Bind token to client fingerprint (IP, device) — advanced

Token Storage — Browser Clients

JWE — When You Need Encryption

JWE (JSON Web Encryption) encrypts the payload — not just signs it.