JWT Authentication Explained: Structure, Claims, Algorithms, and Security Pitfalls

JWT Structure: Three Parts

A JWT is a string of three Base64url-encoded sections separated by dots:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsaWNlIiwiaWF0IjoxNzQzMDAwMDAwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Part 1 — Header: Describes the token itself. Typically:

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

alg identifies the signing algorithm. typ is always "JWT". Some tokens add kid (Key ID) to indicate which key was used — needed when rotating signing keys.

Part 2 — Payload: Contains the claims — assertions about the authenticated entity. Typically:

{
  "sub": "1234567890",
  "name": "Alice",
  "email": "alice@example.com",
  "role": "admin",
  "iat": 1743000000,
  "exp": 1743003600
}

The payload is Base64url-encoded, not encrypted. Anyone with the token can decode and read it. Never put passwords, secret keys, credit card numbers, or other sensitive data in a JWT payload.

Part 3 — Signature: Created by the server using the algorithm specified in the header:

• HMAC algorithms (HS256, HS384, HS512): HMAC-SHA256(base64url(header) + "." + base64url(payload), secret_key)
• RSA/ECDSA algorithms: RSA-SHA256(base64url(header) + "." + base64url(payload), private_key)

The signature proves that the header and payload have not been tampered with since the server signed the token. If any byte in the header or payload changes, signature verification fails.

Standard Claims

Claims are the key-value pairs in the JWT payload. Some are standardised by RFC 7519; the rest are application-specific.

Standard (registered) claims:

Critical validation rules:

1. Always validate `exp`. A token whose exp is in the past is expired and must be rejected regardless of valid signature. Accepting expired tokens is one of the most common JWT security mistakes.

2. Validate `iss`. Confirm the token was issued by your authentication server, not some other service.

3. Validate `aud`. If your token includes an audience claim, verify it matches your service. This prevents tokens issued for one service from being used on another.

4. Validate `nbf` if present. A token presented before its nbf time should be rejected.

Custom claims: Any key not in the registered list is an application-specific claim. Prefix custom claims with a namespace to avoid collisions: "https://api.yourapp.com/roles": ["admin"]. Short undocumented keys like "role" or "isAdmin" are fine for internal use; namespaced claims are recommended when tokens cross service boundaries.

Claim size: The JWT payload is included in every request as a header or cookie. Keep it small. Store only what the server needs for authorization decisions — typically user ID, roles, and expiration. User preferences, profile data, and large permission lists belong in the database, not the token.

Signing Algorithms: HS256 vs RS256 vs ES256

The alg header field determines how the signature is created and verified. Choosing the right algorithm for your architecture is critical.

**HS256, HS384, HS512 (HMAC-SHA-*):** Symmetric algorithms. The same secret key is used to sign and verify. All parties (the signer and all verifiers) must share the secret.

• Appropriate when: You control all services that verify tokens. A monolith, or a small set of services where the secret can be securely distributed.
• Avoid when: Third-party services need to verify your tokens, or tokens cross trust boundaries. You cannot distribute your signing secret to external services.

**RS256, RS384, RS512 (RSA-SHA-*):** Asymmetric algorithms. The private key signs; the public key verifies. The public key can be distributed freely — it cannot forge signatures.

• Appropriate when: Multiple services verify tokens, third parties need to verify your tokens, or you publish a JWKS (JSON Web Key Set) endpoint for automatic key discovery.
• Drawback: Larger signature size (256 bytes vs 32 bytes for HS256). RSA key generation and verification are slower than HMAC (though negligible for most web apps).

**ES256, ES384, ES512 (ECDSA-SHA-*):** Asymmetric like RSA, but using elliptic curve cryptography. Smaller keys and signatures than RSA at equivalent security levels.

• Appropriate when: You want asymmetric signing with smaller payload overhead than RSA.
• ECDSA implementation caution: ECDSA requires a secure random number for each signature. A flawed RNG can leak the private key. Use a well-reviewed library, never implement ECDSA manually.

PS256 (RSASSA-PSS): RSA with probabilistic signing. More secure than RS256 (deterministic RSA is vulnerable to certain side-channel attacks). Required by some regulatory standards. Supported by most modern JWT libraries.

Recommendation for new projects: RS256 for services that need to distribute verification capability; HS256 for purely internal auth servers where you control all verifiers.

The Security Vulnerabilities You Must Know

JWTs have a documented history of critical vulnerabilities in implementations. Every developer working with JWTs should know these attacks.

1. The "alg: none" attack. The JWT specification allows "alg": "none", meaning an unsigned token that any parser should accept without verification. Early JWT libraries that respected this field would accept a token with "alg": "none" and no signature as valid — allowing an attacker to forge any token. Fix: explicitly reject tokens with alg: none. Always specify the allowed algorithms when validating; never use the algorithm from the token header to choose the verification algorithm.

2. RS256 to HS256 confusion attack. When a server accepts both RS256 and HS256, an attacker can take the server's public RSA key (which is public!), craft a token signed with HS256 using that public key as the HMAC secret, and the server verifies it with the public key — which is the same value used as the HMAC secret. Fix: never accept both algorithm families on the same verification path. Specify the expected algorithm and reject anything else.

3. Missing expiration validation. A valid signature does not mean a valid session. Tokens remain cryptographically valid after exp. Servers that verify the signature but not the expiration accept tokens from logged-out or disabled users indefinitely. Fix: always check exp before accepting a token.

4. Insecure storage (XSS via localStorage). Tokens stored in localStorage are accessible to any JavaScript running on the page. An XSS vulnerability can exfiltrate the token, giving an attacker a persistent authenticated session. Fix: use HttpOnly cookies for token storage — JavaScript cannot read HttpOnly cookies. This shifts the attack surface from XSS token theft to CSRF, which is more controllable.

5. No revocation. JWTs are stateless — the server does not track issued tokens. Logging out, banning a user, or changing a password does not invalidate existing tokens until they expire. Fix: use short expiration (15 minutes for access tokens). Implement a revocation list (a database of jti values) for security-critical operations like password changes. Use refresh tokens with longer expiration for persistent sessions.

Access Tokens and Refresh Tokens

The standard pattern for JWT-based authentication uses two types of tokens with different lifetimes and storage.

Access token: A short-lived JWT (typically 15 minutes to 1 hour) included in every API request in the Authorization: Bearer <token> header. Short expiration limits the damage if a token is compromised — it becomes worthless after 15 minutes without server-side revocation. The server validates the token on every request but does not store it — the authentication is stateless.

Refresh token: A long-lived token (1 day to 90 days depending on security requirements) stored securely (HttpOnly cookie or secure device storage). Used only to obtain a new access token when the current one expires. The refresh token is validated by the auth server and stored in a database for revocation capability. On compromise, revoke the refresh token — the attacker cannot obtain new access tokens.

The token refresh flow:

1. Client sends request with access token → server validates, returns response

2. Access token expires → next request returns 401

3. Client sends refresh token to /auth/refresh endpoint

4. Auth server validates refresh token, issues new access token (and optionally rotates the refresh token)

5. Client retries original request with new access token

Refresh token rotation: On each refresh, issue a new refresh token and invalidate the old one. If an attacker has stolen the refresh token and uses it, the legitimate client's next refresh attempt fails (old token is invalid), alerting you to a compromise. Implement refresh token families — if a refresh token from a rotated-out family is used, invalidate the entire family.

Silent refresh: Implement a timer in the frontend that triggers a refresh request shortly before the access token expires (e.g., 1 minute before expiration). The user never sees the expiration — their session renews transparently.