JWT and token validation

A JSON Web Token (JWT) is a compact way to represent claims. It is used for ID tokens, many access tokens, client authentication assertions, and security events. The format is simple; validating it correctly is where most problems occur.

Structure

A signed JWT has three base64url-encoded parts separated by dots: header.payload.signature.

// Header
{ "alg": "ES256", "kid": "2026-10-key-1", "typ": "at+jwt" }

// Payload
{
  "iss": "https://login.example.test",
  "sub": "p-1042",
  "aud": "https://api.example.test",
  "exp": 1792000000,
  "iat": 1791999700,
  "scope": "documents.read",
  "client_id": "print-app"
}

The payload is encoded, not encrypted. Anyone holding the token can read it. Do not put secrets or unnecessary personal data in a signed JWT. Encrypted JWTs (JWE) exist but add complexity.

The related specifications

A validation checklist

A recipient should, at minimum:

1. Restrict algorithms. Accept only the algorithms you expect for this issuer. Reject none. Do not let the token’s header choose between symmetric and asymmetric verification.
2. Find the key from trusted configuration. Use the issuer’s published key set, fetched from a configured location over HTTPS, and select the key by kid. Never use a key embedded in the token itself unless a specification explicitly requires it and you validate the chain.
3. Verify the signature before trusting any claim.
4. Check the issuer (iss) matches exactly the expected issuer.
5. Check the audience (aud) contains your identifier. A token for another API must be rejected.
6. Check time claims: exp in the future, nbf if present, with a small clock-skew allowance.
7. Check the token type. An ID token is not an access token. RFC 9068 uses typ: at+jwt for access tokens so they cannot be confused with other JWTs.
8. Apply protocol-specific checks, such as nonce for OIDC ID tokens, then your own authorization rules.

Use a maintained library and configure it for these checks; many vulnerabilities come from defaults or from skipping a step.

Common mistakes

Key rotation

Issuers rotate signing keys. Recipients should cache the key set, refresh it when they see an unknown kid (with rate limiting), and tolerate overlap between the old and new keys. Test rotation before an emergency forces it.

Opaque or structured?

An access token can be a JWT validated locally or an opaque reference checked through introspection (RFC 7662). Local validation is fast but makes revocation harder; introspection gives current state at the cost of a network call. See self-contained and opaque tokens for a full comparison and token claims for the claims you will validate.

References

• JWT, RFC 7519.
• JWT Best Current Practices, RFC 8725.
• JWT Profile for OAuth 2.0 Access Tokens, RFC 9068.
• JSON Web Key, RFC 7517.