JWT Security Best Practices: Architecture, Claims & Vulnerability Defense

JSON Web Token (JWT) is an open industry standard (RFC 7519) specifying a compact, URL-safe container format for securely transmitting claims between parties. A JWT comprises three distinct segments separated by periods (.):

1. Header: Declares the token type ("typ": "JWT") and the cryptographic signing algorithm ("alg": "HS256" or "RS256").
2. Payload: Encapsulates the claims—statements regarding an entity (typically the authenticated subject) and contextual metadata like expiration and authorization roles.
3. Signature: Generated by concatenating the Base64URL-encoded header and payload with a period, then signing that string using a secret key or private key. The signature guarantees data integrity and tamper-evidence.

// Valid JWT Token Example (Inspectable via DevUtils JWT Decoder):
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

// 1. Decoded Header:
// {"alg": "HS256", "typ": "JWT"}

// 2. Decoded Payload:
// {"sub": "1234567890", "name": "John Doe", "iat": 1516239022}

// 3. Cryptographic Signature:
// SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

To prevent authentication bypasses, replay attacks, and token reuse across environments, backend services must rigorously evaluate standard registered claims:

• exp (Expiration Time): Unix timestamp indicating when the token ceases to be valid. Expired tokens must be immediately rejected with an HTTP 401 response. Access tokens should carry short lifespans (5–15 minutes).
• nbf (Not Before): Designates the timestamp prior to which the token must not be accepted.
• iat (Issued At): The creation timestamp, useful for rejecting tokens minted before a user changed their password or revoked active sessions.
• iss (Issuer): Identifies the principal that issued the token, validating that the token originated from your trusted authentication server.
• aud (Audience): Specifies the recipients for which the JWT is intended. If an API receives a token minted for a different service, it must reject the request.
• sub (Subject): The unique identifier (e.g., UUID or account ID) representing the authenticated principal.

• HMAC with SHA-256 (HS256): Employs a single shared symmetric key for both minting signatures and verifying them. While computationally fast, HS256 introduces severe operational risk in distributed microservice architectures. Because every verification node requires the secret key, a breach of any single service allows an attacker to forge arbitrary valid tokens across the entire fleet.
• RSA or ECDSA (RS256 / ES256): Utilizes asymmetric public/private key pairs. The centralized authentication server guards the private signing key, while independent resource servers and API gateways verify signatures using the publicly published JWKS (JSON Web Key Set). This guarantees complete cryptographic isolation.

1. The alg: "none" Exploit: Historic JWT libraries permitted attackers to set "alg": "none" in the header, omit the signature, and have the server accept the token as valid. Modern verification routines must explicitly whitelist accepted algorithms and reject unsigned tokens.
2. Key Confusion Attacks: When an API expects an asymmetric algorithm (RS256) but accepts HS256, an attacker can sign a forged token using the server's publicly available RSA public key as the HMAC shared secret. Ensure your verification library enforces an explicit algorithm whitelist that cannot be overridden by token headers.
3. Weak HMAC Secrets: HS256 secrets that lack sufficient cryptographic entropy can be cracked offline using GPU-accelerated dictionary attacks. Always generate secrets with at least 256 bits of cryptographically secure random entropy.

• LocalStorage Storage: While trivial to implement with JavaScript, tokens stored in localStorage or sessionStorage are fully accessible to any script executing on the origin. A single Cross-Site Scripting (XSS) vulnerability permits an adversary to exfiltrate active session tokens immediately.
• HttpOnly, Secure, SameSite Cookies: Setting the HttpOnly flag prevents JavaScript from accessing the cookie, effectively neutralizing XSS exfiltration vectors. Setting Secure enforces HTTPS transmission, and configuring SameSite=Lax or SameSite=Strict mitigates Cross-Site Request Forgery (CSRF).
• Production Recommended Pattern: Retain short-lived access tokens solely in JavaScript memory (React/Vue application state), while persisting long-lived refresh tokens in an HttpOnly cookie with automatic token rotation.