Lorixen.
EN

Validating JWTs: the checks your API must not skip

Short answer: A JWT is only trustworthy after your API has checked it properly, and decoding it is not checking it. Verify the signature with a key you expect, accept only the algorithm you chose (never none, never whatever the token's header asks for), and check the issuer, audience, expiry and not-before time, with a small allowance for clock differences. Use a maintained library with these options switched on, and treat every claim inside the token as untrusted until validation passes.

Decoding isn't validating

A JSON Web Token has three parts: a header, a payload of claims and a signature. The header and payload are just base64url-encoded JSON, which anyone can read and anyone can create. Plenty of tutorials show decoding a token to read the user ID, and some production code stops there.

If your API reads "role": "admin" from a token without checking the signature, anyone can write a token saying the same thing. The signature, checked with the right key and algorithm, is what makes the claims meaningful.

The IETF's JWT Best Current Practices document, RFC 8725, sets out the common mistakes and how to avoid them. Most come down to libraries being too willing to trust the token's own description of itself.

Check 1: pin the algorithm

RFC 8725 describes a classic attack: an attacker changes the header's algorithm to none, and some libraries trust that value and "validate" the token without checking any signature. Another variant swaps an asymmetric algorithm, such as RS256, for a symmetric one, such as HS256, so the library uses the public key as an HMAC secret, which the attacker also knows.

The document's first recommendation is to perform algorithm verification: your code should decide which algorithm is acceptable for each key, and reject tokens using anything else. In practice:

  • Configure your library with an explicit allowed algorithm list, such as only RS256 or only ES256.
  • Never allow none for tokens that arrive from clients.
  • Don't use the token's header to choose a key type or algorithm.

Check 2: verify the signature with the right key

For tokens from an identity provider, you'll usually fetch its public keys from a published key set and pick the key by its key ID. Make sure:

  • Keys come only from the issuer's configured URL, not from a URL inside the token.
  • Unknown key IDs are rejected, after at most a refresh of the cached key set.
  • Your own signing secrets, if you use symmetric algorithms, are long and random, kept out of code, and rotated when staff with access leave.

Check 3: issuer and audience

A valid signature only proves who issued the token. RFC 8725 recommends validating the issuer and the audience. The issuer (iss) should be exactly the provider you expect. The audience (aud) should include your API's identifier.

Audience checks matter more than they look. If your company has several apps using the same identity provider, a token issued for the marketing dashboard shouldn't be accepted by the payments API. Without an audience check, it might be.

Check 4: time claims

The JWT specification, RFC 7519, defines exp, the expiration time after which the token must not be accepted, and nbf, the time before which it must not be accepted. It notes that implementers may allow a small leeway, usually no more than a few minutes, to account for clock skew between servers.

So:

  • Require exp and reject expired tokens.
  • Honour nbf if present.
  • Allow a small, fixed leeway, such as a minute or two, not hours.
  • Keep server clocks synchronised.

Check 5: the right kind of token

Apps often handle several kinds of JWT: access tokens, ID tokens, email-verification tokens, password-reset links. RFC 8725 recommends explicit typing and mutually exclusive validation rules, so a token meant for one purpose can't be replayed for another. For example, an ID token describing the user shouldn't be accepted as an API access token, and a password-reset token shouldn't work as a login.

Use a typ header, different audiences or different signing keys for different token kinds, and check them.

After validation: authorise

A valid token tells you who the caller is and what the issuer granted. Your API still has to decide what they can do:

  • Check scopes or roles against the specific action.
  • Check ownership: user A's valid token mustn't fetch user B's invoice.
  • Don't trust claims such as email or tenant ID for security decisions unless the issuer guarantees them.

RFC 8725 puts it plainly as a principle: don't trust received claims without validation.

Use a library, configured strictly

Hand-written JWT verification is a common source of bugs. Use a well-maintained library for your language and configure:

  • Allowed algorithms.
  • Expected issuer and audience.
  • Required claims, including exp.
  • Clock leeway.

Then write tests with deliberately bad tokens: alg: none, wrong audience, expired, wrong issuer, tampered payload, unknown key ID. Each should be rejected.

A worked example

Picture a hypothetical London events-ticketing API that decoded JWTs to read the user ID and verified signatures with a library set to accept "any supported algorithm". A security review showed it would accept a token issued for the company's separate staff rota app, because nobody checked the audience. The team pinned the algorithm to RS256, set the expected issuer and audience, required exp with a 60-second leeway, added ownership checks on ticket endpoints and added a test suite of bad tokens. The rota app's tokens are now rejected.

FAQ

Should I put sensitive data in a JWT?

No. Signed JWTs are readable by anyone who has them. Put only what the API needs.

How do I log someone out if JWTs are stateless?

Short expiry times plus revocable refresh tokens are the usual answer. A deny-list is possible for urgent cases.

Is HS256 unsafe?

Not inherently. It's fine when only your own servers sign and verify with a strong secret. The danger is mixing it up with asymmetric keys.

If you'd like your API's token checks reviewed, tell us which identity provider and library you use.

Sources

WhatsAppBook a call