Skip to main content
Security guideReviewed

JWT security: the decisions your verifier must make before it trusts a token

A JSON Web Token is only as trustworthy as the code that checks it.

This guide explains in plain English what a JWT is and who can read it, the algorithm, key, claim and revocation decisions a verifier has to make, the attacks that work when one is skipped, and a verification suite you run with Node.js alone to show your own verifier makes each one.

JWT verification suite and decision table

An illustration with invented issuers and users, for learning and for testing a verifier you own. Part 1 maps eleven verifier decisions (format, header parameters, token type, issuer, algorithm, key selection, signature, required claims, validity time, audience and revocation) to the specification section or requirement behind each and the fixtures that test it.

How to use it

Parts 2 to 5 are a Node.js suite with no installs: a token minter using keys generated at run time, a flawed and a fixed verifier, sixteen fixtures printed with each verifier's decision and reason, a regression test that fails on the flawed verifier, and steps to point the fixtures at your own verifier.

jwt-security.txt

Introduction17 lines

JWT VERIFICATION SUITE AND DECISION TABLE An illustration, for learning and for testing a JWT verifier you own. Every token in it is minted by the suite with keys it generates when it starts, and checked only by the suite's own two verifiers. Nothing in it contacts another machine, and it holds no real token, key or secret. The issuers, the API and the users are invented. Written and run on: Node.js 26.0.0, the only version it was run on. It uses node:crypto, node:test and node:assert, which ship with Node.js, so there is nothing to install. Every output below was copied from that run. The keys and each jti are new on every run, so the end of each printed token differs every time; the runner shortens each token to its first 16 and last 6 characters for that reason. Test timings differ too. Source names used below: RFC 7519 RFC 7519, JSON Web Token (JWT) RFC 7515 RFC 7515, JSON Web Signature (JWS) RFC 7518 RFC 7518, JSON Web Algorithms (JWA) RFC 8725 RFC 8725, JSON Web Token Best Current Practices (BCP 225) RFC 9068 RFC 9068, JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens RFC 9700 RFC 9700, Best Current Practice for OAuth 2.0 Security ASVS OWASP Application Security Verification Standard 5.0.0, chapters V9 Self-contained Tokens and V7 Session Management. The level follows each requirement number. WSTG-SESS-10 OWASP Web Security Testing Guide, latest edition, 4.6.10 JSON Web Tokens OWASP JWT OWASP JSON Web Token Cheat Sheet CWE MITRE CWE version 5.0

What a JSON Web Token is, and who can read it

A JSON Web Token, or JWT, is a short piece of text that carries statements about someone, protected so the receiver can tell whether they were changed.

RFC 7519, the IETF standard that defines it, calls it a compact claims representation format intended for space constrained environments such as HTTP Authorization headers and URI query parameters. The statements are claims: name and value pairs in a JSON object. That object is either the payload of a JSON Web Signature (JWS), which signs it or protects it with a message authentication code (MAC), or the plaintext of a JSON Web Encryption (JWE) structure, which encrypts it. This guide is about the signed kind.

A signed JWT is three pieces of base64url text joined by full stops. RFC 7515 section 3.1 gives the compact form as the encoded protected header, then the encoded payload, then the encoded signature. The header says how the token was protected: alg names the algorithm, and RFC 7515 section 4.1.1 says it MUST be present; typ can name the kind of token; kid is, in the words of section 4.1.4, a hint indicating which key was used.

The payload holds the claims. RFC 7519 section 4.1 registers seven claim names: iss (who issued the token), sub (who it is about), aud (who it is for), exp (when it expires), nbf (when it starts to be valid), iat (when it was issued) and jti (a unique identifier for the token).

None of them is intended to be mandatory in all cases; the RFC says applications should define which claims they use and when they are required.

The signature covers the header and the payload together, and the WSTG JSON Web Tokens test puts the consequence plainly: modifying any part of the JWT should cause the signature to be invalid and the token to be rejected by the server.

Signed is not encrypted. OWASP's JSON Web Token Cheat Sheet says a signed JWT provides integrity and authenticity but not confidentiality: the payload is only base64url encoded, so anyone who obtains the token can read every claim. RFC 9068, the profile for OAuth access tokens in JWT format, says the same in its privacy considerations: because JWT access tokens carry information by value, clients and potentially even end users can look directly inside the claims of an unencrypted token.

RFC 7519 section 12 says that when a JWT contains privacy-sensitive information, measures MUST be taken to prevent its disclosure to unintended parties, and calls leaving that information out the simplest way of minimising privacy issues. Put nothing in a signed token that you would not show the person holding it.

OWASP's Application Security Verification Standard (ASVS) 5.0 files JWTs under self-contained tokens: tokens that carry the data or claims a receiving service relies on to make security decisions, as distinct from a simple token holding only an identifier the service looks up locally. It names JWTs and SAML assertions as the most common examples, and says the security of the mechanism relies on validating the token's integrity and making sure it is valid for a particular context. That validation is the verifier's job, and the subject of this guide.

Four neighbouring guides take the rest. OAuth and OIDC security covers where tokens come from when someone clicks "Sign in with", including the ID token and its nonce. Session management covers what sign-out and "sign out everywhere" have to reach. Broken access control covers what the person named in a valid token may see and change once it is accepted.

Secrets exposure covers what to do when a key or secret, such as a signing key, turns up in code, history, bundles or logs.

What a verifier must decide before it trusts a token

RFC 7519 section 11.1 sets the principle: the contents of a JWT cannot be relied upon in a trust decision unless they have been cryptographically secured and bound to the context the decision needs, and the keys used will typically need to be verifiably under the control of the party named as the issuer.

Section 7.2 lists the validation steps and says that if any of them fails, the JWT MUST be rejected. For an API that receives JWT access tokens, RFC 9068 section 4 turns this into checks the resource server MUST make: the token type, the issuer, the audience, the signature with keys the authorisation server provides, a refusal of alg none, and expiry, with some small leeway for clock skew allowed.

Combined with RFC 8725, the IETF's JSON Web Token Best Current Practices, and chapter V9 of ASVS 5.0, that comes to eleven decisions. They are numbered here in the order the suite's fixed verifier makes them. Each is answered from the verifier's own configuration; the token supplies only the values being checked.

  • D1 Format: three base64url parts, with a JSON object in the header and the claims.
  • D2 Header parameters: only the ones the verifier understands, so a key carried in the token is never used.
  • D3 Token type: typ says this is the kind of token the API accepts.
  • D4 Issuer: iss exactly matches an issuer the API is configured to trust.
  • D5 Algorithm: alg equals the algorithm set in code for that issuer.
  • D6 Key: chosen by kid from that issuer's configured keys, and from nowhere else.
  • D7 Signature: checked with that key over the header and payload.
  • D8 Required claims: every claim the API relies on is present.
  • D9 Time: not expired and not before its start, within a small, stated leeway.
  • D10 Audience: aud names this API.
  • D11 Revocation: neither the token nor every token its user held before a cut-off has been revoked.

Why a token that chooses its own algorithm or key has passed no check

Anyone can write a JWT header.

RFC 8725 section 2.1 explains that signed JWTs carry an explicit indication of the signing algorithm, the alg header parameter, to allow cryptographic agility, and that this, in conjunction with design flaws in some libraries and applications, has led to several attacks.

If the verifier takes the algorithm or the key from the header, the person who made the token chose how it would be checked, and a check whose terms the sender sets proves nothing.

The unsigned token: alg none

RFC 7519 section 6 defines an Unsecured JWT: alg set to none and an empty signature, for cases where something other than the JWT protects its content. 1 min read

Key confusion: a public key used as an HMAC secret

RFC 8725 section 2.1 describes the second attack. 2 min read

Keys the token points to

A JWS header can do more than name an algorithm. 2 min read

A key that belongs to another issuer

Trusting more than one issuer creates a quieter version of the same problem. 1 min read

A revision of RFC 8725 is in progress

RFC 8725 describes itself as a point-in-time statement and advises readers to look for updates. 1 min read

A valid signature does not mean the token is meant for you

A signature tells you who made the token, within limits: RFC 7515 section 10.5 notes that validating a MAC only shows the message came from one of the parties holding the shared key.

It says nothing about whether this API was the intended recipient, whether the token is the right kind, or whether it is still in date. RFC 8725 section 2.7 calls the result a substitution attack: a token given legitimately to one recipient is presented to another for which it was not intended, and if that is not caught, the attacker can gain access to resources it is not entitled to. Five checks deal with it.

  • Issuer. RFC 9068 section 4 says the issuer identifier MUST exactly match the iss claim, and RFC 7519 compares such values as case-sensitive strings with no transformations. The WSTG JSON Web Tokens test warns that a prefix or substring comparison in place of exact equality can let a token from a lower-trust tenant or environment through. Fixture F07, a genuine token from the staging sign-in service, tests it.
  • Audience. RFC 7519 section 4.1.3 says that when aud is present and the recipient does not identify itself with a value in it, the JWT MUST be rejected. RFC 8725 section 3.9 says that where one issuer issues JWTs for more than one relying party, the JWT MUST contain aud and the relying party MUST reject it if the audience is missing or not associated with it. ASVS 5.0 requirement 9.2.3, at Level 2, asks that the service only accepts tokens intended for use with it, and says that for JWTs this can be achieved by validating aud against an allowlist defined in the service. RFC 9700 section 2.3 says access tokens SHOULD be audience-restricted, and that a resource server MUST refuse to serve a request whose access token was not meant for it. F08, a production token issued for the billing API, tests it.
  • Token type. RFC 8725 section 2.8 calls confusion between kinds of JWT cross-JWT confusion and says that where it could occur, mitigations MUST be employed; section 3.11 recommends explicit typing through the typ header for new uses. RFC 9068 section 4 says a resource server MUST verify that typ is at+jwt or application/at+jwt and reject any other value, and its section 5 explains that this helps tell JWT access tokens from OpenID Connect ID Tokens, whose layout is very similar. ASVS 5.0 requirement 9.2.2, at Level 2, asks the receiving service to validate that a token is the correct type and meant for the intended purpose before accepting its contents, and gives as an example that only access tokens can be accepted for authorisation decisions and only ID Tokens used for proving user authentication. F09 presents an ID token to the API.
  • Time. RFC 7519 section 4.1.4 says a JWT MUST NOT be accepted for processing on or after its exp time, and section 4.1.5 says the same before its nbf time. Both let implementers provide some small leeway, usually no more than a few minutes, to account for clock skew. ASVS 5.0 requirement 9.2.1, at Level 1, asks that where a token carries a validity time span, nbf and exp are verified. The 60 seconds the suite allows is its own choice, so F11, expired 30 seconds ago, is accepted, while F10, expired ten minutes ago, and F12, not valid for another ten minutes, are refused.
  • Required claims. A check on an absent claim passes nothing. RFC 7519 leaves every registered claim optional and the choice of required ones to the application, and RFC 9068 section 2.2 requires iss, exp, aud, sub, client_id, iat and jti in every JWT access token. The fixed verifier refuses a token with no exp (F13) rather than treating it as one that never expires.

Revocation, short lifetimes and refresh tokens

A self-contained token carries its own validity, so deleting a record on the server does not end it.

ASVS 5.0 says that for self-contained tokens, additional measures are required to revoke or block them, as they may otherwise remain valid until expiration. Its requirement 7.4.1, at Level 1, asks that once termination is triggered the application disallows any further use of the session, and says applications using self-contained tokens will need a solution such as maintaining a list of terminated tokens, disallowing tokens produced before a per-user date and time, or rotating a per-user signing key.

The suite tests the first two. The revoked list uses jti, which RFC 7519 section 4.1.7 says provides a unique identifier for the JWT and can be used to prevent replay. OWASP's JWT cheat sheet suggests keying such a deny list on jti and iss together, and warns that using the raw token or a hash of it as the key is not safe, because an attacker holding a revoked token might produce another representation of it that still passes the signature check.

F14 is a token whose jti is on the list.

The per-user cut-off is what a "sign out everywhere" button sets: F15 was issued before user-2002's cut-off and is refused, while F16, issued after it, is accepted, so the cut-off ends old tokens without locking the user out.

Every revocation check is a lookup on each request, which is the state a self-contained token was meant to avoid; the OWASP cheat sheet says that with a deny list, user sessions won't be completely stateless anymore. Short lifetimes are the other half.

RFC 6750 section 5.3 says token servers SHOULD issue short-lived bearer tokens, one hour or less, particularly to clients that run within a web browser, because this can reduce the impact of a leak. RFC 9700 section 4.14 says refresh tokens add to OAuth's security because they let the authorisation server issue access tokens with a short lifetime and reduced scope, reducing the potential impact of access token leakage.

Section 2.2.2 says refresh tokens for public clients MUST be sender-constrained or use refresh token rotation, and section 4.14.2 says authorisation servers MAY revoke refresh tokens automatically after a security event such as a password change or a logout at the authorisation server.

Revoking a refresh token stops new access tokens; it does nothing to one already issued. Unless the API checks a revocation list or a cut-off, an access token stays usable until its exp, so its lifetime is the longest a revocation can take to reach the API. Choose that lifetime with this in mind, and check revocation on the API for actions where waiting it out is not acceptable.

Where a browser should keep a token

The sources set limits rather than a single answer.

RFC 6750 section 5.3 says implementations MUST NOT store bearer tokens in cookies that can be sent in the clear, that implementations which do store them in cookies MUST take precautions against cross-site request forgery, and that bearer tokens SHOULD NOT be passed in page URLs.

OWASP's HTML5 Security Cheat Sheet says not to store session identifiers in local storage, because the data is always accessible by JavaScript, and that cookies can mitigate this risk with the HttpOnly flag; it also says a single cross-site scripting flaw can be used to steal all the data in local storage.

MDN's Set-Cookie reference says HttpOnly forbids JavaScript from accessing the cookie, and that such a cookie is still sent with requests that JavaScript starts, such as fetch().

ASVS 5.0 does not rule browser storage out. Its requirement 14.3.3, at Level 2, asks that localStorage, sessionStorage, IndexedDB and cookies hold no sensitive data, with the exception of session tokens, and requirement 14.3.1, at Level 1, asks that authenticated data is cleared from client storage after the session ends.

Read together: script on the page can read a token kept in localStorage, and cannot read one kept in an HttpOnly cookie but can still make requests that carry it, and neither belongs in a URL.

Either way the token depends on the page being free of injected script. The cookie security guide covers the attributes a token cookie needs, and the XSS guide covers keeping injected script off the page.

When a plain server-side session is the simpler choice

OWASP's JWT cheat sheet opens its considerations with a question: whether JWTs are really necessary for your use case.

It says JWTs are often suggested for stateless user sessions and that this usage is frowned upon, and explains why: user sessions need a way to be invalidated, a deny list provides one, and with a deny list the sessions are no longer completely stateless, which might defeat the benefit. It suggests considering a plain session system instead.

ASVS 5.0 draws the same line from the other side. Chapter V9 separates self-contained tokens from simple tokens that contain only an identifier the service looks up locally, and requirement 7.4.1 says that for reference tokens or stateful sessions, terminating a session means invalidating the session data at the application backend. On a server-side session that is one delete, effective on the next request.

This page's view: if one web application talks to its own backend, a server-side session with an opaque identifier in a cookie gives you revocation and sign out everywhere without the algorithm, key and claim decisions above, though it has rules of its own for issuing, renewing and ending the identifier.

JWT access tokens earn their extra decisions where an API accepts tokens from a separate issuer, which is the case RFC 9068 describes: authorisation servers and resource servers from different vendors issuing and consuming access tokens in an interoperable way.

How to prove your verifier makes each decision

A verifier is easy to test because you control both ends.

Mint tokens with keys your test generates, give each one to your verifier, and assert both the outcome and the reason. Make each fixture break exactly one decision and leave the rest valid, so a refusal can only come from the check you meant to test, and put a few just inside a limit, so you also see the verifier accept what it should.

Do this against your own verifier in your own test environment, not by sending crafted tokens to a service you do not own or are not authorised in writing to test.

OWASP's Web Security Testing Guide has a JSON Web Tokens test, WSTG-SESS-10, in its latest edition, which the site says represents the latest contributions to the guide and may frequently change. v4.2, the stable release, lists nine session management tests, 4.6.1 to 4.6.9, and none of them covers JWTs.

WSTG-SESS-10's objectives are to determine whether JWTs expose sensitive information and whether they can be tampered with or modified. Its tests include modifying the body of a token without changing the header or signature to see whether the application accepts it, the none algorithm, HMAC and public key confusion, a public key embedded in the jwk header, kid manipulation, jku and x5u injection, and a token issued for one service, tenant or environment replayed against another.

Its remediation list includes using a secure and up to date library, checking that the signature is valid and uses the expected algorithm, and always validating exp, nbf, iss and aud.

MITRE's catalogue names the weakness. In CWE version 5.0, CWE-347, Improper Verification of Cryptographic Signature, is a Base weakness in which the product does not verify, or incorrectly verifies, the cryptographic signature for data, and MITRE files it under its OWASP Top Ten 2025 category for A04:2025 Cryptographic Failures.

Its parent, CWE-345, Insufficient Verification of Data Authenticity, is a Class weakness in which the product does not sufficiently verify the origin or authenticity of data in a way that causes it to accept invalid data.

For an evidence trail, record which ASVS 5.0 requirement each fixture exercises: 9.1.1 for the signature, 9.1.2 for the algorithm allowlist, 9.1.3 for key sources, 9.2.1 for exp and nbf, 9.2.2 for the token type, 9.2.3 for the audience and 7.4.1 for revocation. The decision table in the asset does this row by row.

Settings to check when a library does the verifying

Use a secure, up-to-date library to handle JWTs; it is the first point in WSTG-SESS-10's remediation list.

A library still makes only the decisions you configure, and its documentation says what happens when you leave an option out. The documentation of two Node.js libraries shows the pattern.

  • jsonwebtoken:its README says that when the algorithms option is not specified, a default list is used based on the type of key provided: HS256, HS384 and HS512 for a secret, and RS256, RS384 and RS512 for an RSA key. Of the audience option it says "if you want to check audience (aud), provide a value here"; issuer is optional, and clockTolerance sets the seconds to tolerate when checking nbf and exp. jwt.decode() returns the payload without verifying the signature, and the README warns not to use it for untrusted messages and to treat a decoded payload from an untrusted source like any other user input. For the two advisories above, the vendor advisories list versions up to 8.5.1 as affected and 9.0.0 as patched.
  • jose:its documentation says the algorithms option defaults to all algorithms applicable to the key or secret, and that unsecured JWTs (alg none) are never accepted. Its audience, issuer and subject options each set an expected value and require the claim to be present, typ does the same for the header parameter, requiredClaims names further claims that must be present, and clockTolerance applies to nbf and exp, and to iat when maxTokenAge is set.

Write the decisions into your configuration

In both libraries the algorithm list, the issuer, the audience and the leeway are values you pass. Pass them even where a default happens to match, so each decision is written in your own code; resolve keys per issuer rather than from one shared list; require the claims you rely on; and then run fixtures like the suite's against the verifier as configured. The tests check the configuration you deployed, not the library in general.

Running the verification suite on your own machine

The suite in the asset is an illustration, for learning and for testing a verifier you own.

It has five files and uses only modules that ship with Node.js: node:crypto makes three RSA key pairs when it starts, signs tokens and checks signatures, and node:test runs the regression test. Nothing is installed, no token, key or secret comes from outside the run, and nothing contacts another machine.

The issuers, the API and the users are invented. It was written and run on Node.js 26.0.0, the only version it was run on, and every output in the asset was copied from that run.

The flawed verifier is not a straw man: it checks signatures, so it refuses the tampered token in F02. Its mistakes are the ones described above, each marked FLAWED in the code: it takes the algorithm and the key from the header, keeps the production and staging keys in one table found by kid, and checks no claim.

The fixed verifier makes decisions D1 to D11 in order, each from its own configuration, and reports the first one a token fails.

  • Save the five files into an empty folder and open a terminal there.
  • Run node run-suite.mjs. For each of the sixteen fixtures it prints how the token was made, its header and claims, the token shortened to its first 16 and last 6 characters, the expected decision, and what each verifier decided and why. The keys and each jti are new on every run, so the end of each token differs every time; everything else repeats. The flawed verifier makes 4 of the 16 expected decisions and the fixed verifier all 16.
  • Run node jwt-verifier.test.mjs. Node's built-in test runner runs the sixteen fixtures against the fixed verifier and all pass. Run node jwt-verifier.test.mjs flawed and twelve fail, each with what was expected and what happened. The Node.js test runner documentation says the process exit code is set to 1 when any test fails, so a pipeline step running the test fails too.

Pointing the fixtures at your own verifier

Keep the minter and the fixtures, and change runVerifier so it calls your verifier, configured as in production except that its trusted key for your issuer is the suite's production public key. Keep the staging and outsider keys out of that configuration: they exist to be refused.

Give your verifier the suite's fixed clock as its current time, which the jsonwebtoken README calls clockTimestamp and the jose documentation calls currentDate. Run it in your test environment and in the pipeline that deploys your API, never against a live service.

Where an outside test fits

Your own fixtures cover the verifier you know about.

A Clever Ops web application and API penetration test covers authentication and sessions, what each role can see and change, and the API called directly rather than only through the screens; for an API that accepts JWTs, that includes how it checks the tokens it receives. Each finding comes with evidence, a fix written for your stack and the criteria the retest will use.

If Clever Ops built or hosts your application, the work is a security review rather than an independent test, and the report says who built it and who hosts it.

Frequently asked questions

It is the set of checks that decide whether a JSON Web Token can be trusted: that the algorithm and key come from the verifier's configuration rather than the token, that the signature is valid, that the token was issued by a trusted issuer for this service, is the right kind and is within its validity time, and that it has not been revoked. RFC 7519 says a JWT's contents cannot be relied on in a trust decision unless they are cryptographically secured and bound to the context the decision needs.

Yes, if it is only signed. OWASP's JWT cheat sheet says the payload of a signed JWT is only base64url encoded, not encrypted, so anyone who obtains the token can read every claim. Leave sensitive information out of the token; the cheat sheet suggests encryption only when the claims must travel with the token to a party that cannot look them up with the issuer.

An attack on a verifier that lets the token's alg header choose the algorithm. RFC 8725 describes an RS256 token changed to HS256 so that some libraries validate it as an HMAC, using the RSA public key as the shared secret. Because the public key is public, anyone can then make a token such a verifier accepts. Fix the accepted algorithm for each issuer in your verifier's configuration. RFC 8725 section 3.1 says libraries MUST let the caller specify the supported algorithms and MUST NOT use any other.

For a JWT access token, RFC 9068 requires iss, exp, aud, sub, client_id, iat and jti, and says the resource server MUST check that typ is at+jwt or application/at+jwt, that iss exactly matches the issuer, that aud includes the resource server and that exp has not passed. Check nbf too when it is present, as ASVS 5.0 requirement 9.2.1 asks, and refuse a token that lacks a claim you rely on.

By checking something on each request, because the token may stay valid until it expires. ASVS 5.0 requirement 7.4.1 gives three examples: a list of terminated tokens, refusing tokens produced before a per-user date and time, and rotating a per-user signing key. Short lifetimes limit how long an unrevoked token works; RFC 6750 says token servers SHOULD issue bearer tokens lasting one hour or less.

OWASP's HTML5 Security Cheat Sheet says not to store session identifiers in local storage, because the data is always accessible by JavaScript, and that cookies can mitigate this risk with the HttpOnly flag. RFC 6750 says bearer tokens MUST NOT go in cookies that can be sent in the clear and that tokens kept in cookies need precautions against cross-site request forgery. ASVS 5.0 allows session tokens in browser storage. Either way, the token depends on the page being free of injected script.

Not by default. OWASP's JWT cheat sheet says JWTs used for user sessions need a way to be invalidated, that a deny list means the sessions are no longer completely stateless, and that a plain session system is worth considering. JWT access tokens suit an API that accepts tokens from a separate authorisation server. For one application talking to its own backend, this page recommends a server-side session.

Scope the right test for your application

Tell us what you have built, who uses it and when it needs to launch. You will get a plain-English recommendation: a website audit, a web application test or a referral to a specialist.