JWT Tokens Decoded: What's Actually Inside That eyJ… String

) to match traditional session security postures.

• Proper claim validation (exp, iss, aud, nbf) reduces replay and misrouting attacks by >90% in distributed microservice architectures.

Core Solution

A JWT is a compact, URL-safe string composed of three Base64URL-encoded segments separated by dots: header.payload.signature. Understanding the cryptographic boundaries and claim semantics is essential for secure implementation.

1. JWT Anatomy

• Header: Declares the signing algorithm (alg) and token type (typ). Example: {"alg": "HS256", "typ": "JWT"}
• Payload: Contains registered and custom claims. Example: {"sub": "user_123", "role": "admin", "iat": 1704067200, "exp": 1704070800}
• Signature: Cryptographically binds the header and payload to a secret/key. Computed as:

  HMAC-SHA256(base64url(header) + "." + base64url(payload), secret_key)
  

2. Decoding vs. Verifying

• Decoding: Reads the Base64URL payload. Requires no keys. Useful for debugging and claim inspection.
• Verifying: Validates the cryptographic signature against a trusted key. Mandatory for authorization decisions. Never trust decoded claims without server-side verification.

3. Manual Decoding Implementation

function decodeJWT(token) {
  const [headerB64, payloadB64] = token.split('.');

  function b64urlDecode(str) {
    // Base64URL → Base64
    let s = str.replace(/-/g, '+').replace(/_/g, '/');
    // Add padding
    while (s.length % 4) s += '=';
    // Decode UTF-8 bytes
    const bytes = Uint8Array.from(atob(s), c => c.charCodeAt(0));
    return JSON.parse(new TextDecoder().decode(bytes));
  }

  return {
    header: b64urlDecode(headerB64),
    payload: b64urlDecode(payloadB64),
  };
}

4. Standard Claims (RFC 7519)

Claim	Full Name	Meaning
iss	Issuer	Who issued the token
sub	Subject	Token subject (typically user ID)
aud	Audience	Intended recipient service
exp	Expiration Time	Unix timestamp (seconds) — reject after this time
nbf	Not Before	Unix timestamp (seconds) — reject before this time
iat	Issued At	Token creation timestamp
jti	JWT ID	Unique identifier for replay attack prevention

5. Signing Algorithms

• Symmetric: HS256, HS384, HS512 — HMAC with SHA. Single shared secret. Suitable for monolithic or single-service environments.
• Asymmetric: RS256, RS384, RS512 (RSA) and ES256, ES384, ES512 (ECDSA). Private key signs, public key verifies. Ideal for distributed systems and third-party integrations.
• Critical Rule: Never accept alg: none. Always enforce an explicit algorithm whitelist during verification.

Pitfall Guide

1. Trusting Decoded Payload Without Verification: Decoding reveals claims but proves nothing about authenticity. Attackers can forge payloads with elevated privileges (e.g., role: admin). Always verify the cryptographic signature server-side before authorizing requests.
2. Stateless Session Revocation Failure: JWTs lack built-in invalidation mechanisms. When users log out or credentials rotate, existing tokens remain valid until exp. Mitigate with short access token TTLs (5-15 mins), refresh token rotation, or a server-side denylist/redis blacklist.
3. Embedding Sensitive Data in Payload: Base64URL is reversible encoding, not encryption. Storing passwords, PII, or internal secrets in claims exposes them to any client or network interceptor. Use opaque session tokens or encrypt sensitive payloads separately.
4. Missing or Misconfigured Expiry (exp): Tokens without exp claims are valid indefinitely, increasing blast radius on compromise. Always set exp using Unix seconds (Math.floor(Date.now() / 1000)), and validate exp < currentTime server-side.
5. Accepting alg: none or Unrestricted Algorithms: Vulnerable libraries may process tokens with "alg": "none" and empty signatures, enabling complete forgery. Explicitly configure your JWT library to accept only expected algorithms (e.g., algorithms: ['HS256']).
6. Storing Tokens in localStorage: localStorage is accessible to all JavaScript execution contexts, making tokens vulnerable to XSS extraction. Prefer HttpOnly, Secure, SameSite=Strict cookies for web applications, or secure OS keychains for mobile/desktop clients.
7. Timestamp Unit Mismatch: JWT claims use Unix timestamps in seconds, while JavaScript Date.now() returns milliseconds. Comparing exp < Date.now() causes immediate validation failure. Always normalize: exp < Math.floor(Date.now() / 1000).

Deliverables

• 📘 JWT Architecture & Security Blueprint: Comprehensive reference covering token lifecycle, cryptographic boundary definitions, claim validation matrices, and distributed verification patterns for microservices.
• ✅ JWT Implementation & Validation Checklist: Step-by-step verification protocol including algorithm whitelisting, signature validation, claim integrity checks (iss, aud, exp, nbf), revocation strategy selection, and storage hardening guidelines.
• ⚙️ Configuration Templates: Production-ready server-side verification configs for Node.js (jsonwebtoken), Python (PyJWT/FastAPI), and Go (golang-jwt), including denylist schema definitions, cookie security headers, and refresh token rotation flows.