JWT validation: algorithms, keys, claims and key rollover

A compact signed JWT has three base64url parts: protected header, payload, and signature. Decoding the first two reveals attacker-controlled data before verification, and anyone holding the token can read them: signing does not make claims confidential. A valid signature establishes that the signed bytes were produced by a holder of a particular key; it does not by itself establish that this token belongs to your issuer, audience, token type, time window, or authorization decision.

Choose a validation profile before reading claims: expected issuer, allowed algorithm set, trusted key source, expected audience, required claims, token purpose, and time policy. The header can select a candidate key by kid within an already trusted key set. It must not choose an arbitrary network location or turn an asymmetric verification key into a symmetric secret.

For an invoices API, a validated token might assert iss=https://issuer.example, aud=invoices-api, sub=alice, tenant=acme, and typ=at+jwt under the chosen profile. Authorization still has to compare alice and acme with the trusted invoice record. A signed tenant claim does not mean every invoice in that tenant is readable.

Each attack below has been exploited in real libraries or services. A verifier configured as in this guide rejects all of them; the tested examples further down include tokens for the first three. The JWT attacks guide at /domains/identity-crypto/authentication/jwt-attacks/ explains each one.

Use a maintained JOSE implementation with explicit algorithm and claim validation. Reject malformed encodings, unsupported algorithms, missing required fields, ambiguous key selection, and invalid signatures before using the payload as authenticated identity. Enforce exact issuer matching and the profile’s audience semantics; a substring match is not an audience check.

Apply a defined clock-skew allowance to time validation, and bound token lifetime where the application requires it. Avoid a blanket “ignore expiration during outages” fallback. The verifier’s unavailable key source is an availability problem, not evidence that an unverified token is acceptable.

Unknown kid values can trigger bounded refresh of the configured JWKS. Without caching, cooldowns, and limits, attackers can force a network fetch for every invented key ID. A token-supplied jku or x5u must not turn verification into arbitrary URL fetching. Key discovery belongs to trusted issuer configuration.

The downloadable “Secure a real HTTP API” project performs actual JOSE signing and verification in its tests. The learner edits authorization and profile-field selection in exercise.mjs, not the verifier. This is a useful boundary demonstration: bad signatures and audiences fail before the learner’s authorization function runs; same-tenant ownership errors occur afterward.

This verifier pins the algorithm, issuer, audience and RFC 9068 token type, and takes keys only from the issuer’s JWKS with a refresh cooldown. It was tested with jose 6.2.12 on Node.js 26 against a local JWKS: valid tokens pass, and alg: none, an HS256 token signed with the RSA public key, attacker keys in jwk or jku, wrong audience, issuer or type, and expired tokens all fail.

import {createRemoteJWKSet, jwtVerify} from 'jose';

// Keys come only from the issuer's configured JWKS URL, never from token headers
// (jku, x5u, jwk). Unknown kid values refresh the set at most once every 30 seconds.
const jwks = createRemoteJWKSet(new URL('https://issuer.example/.well-known/jwks.json'), {
  cooldownDuration: 30_000,
  cacheMaxAge: 600_000,
});

export async function verifyAccessToken(token) {
  const {payload} = await jwtVerify(token, jwks, {
    algorithms: ['RS256'], // exact allowlist: rejects "none", HS256 and anything else
    issuer: 'https://issuer.example',
    audience: 'invoices-api',
    typ: 'at+jwt', // RFC 9068 access tokens, so an ID token is refused
    requiredClaims: ['sub', 'iat'],
    maxTokenAge: '15m',
    clockTolerance: 30,
  });
  return payload; // authenticated claims; authorization still happens per request
}

PyJWT checks the signature, algorithm, issuer, audience and required claims in jwt.decode; the token type is checked afterwards because the header is covered by the signature. Tested with PyJWT 2.15.0 against the same attack tokens as the Node.js example.

import jwt  # PyJWT 2.x

# Keys come only from the issuer's JWKS URL; get_signing_key_from_jwt matches the kid there.
jwks = jwt.PyJWKClient("https://issuer.example/.well-known/jwks.json", cache_keys=True, lifespan=600)


def verify_access_token(token: str) -> dict:
    key = jwks.get_signing_key_from_jwt(token)
    claims = jwt.decode(
        token,
        key.key,
        algorithms=["RS256"],  # never take this list from the token header
        audience="invoices-api",
        issuer="https://issuer.example",
        leeway=30,
        options={"require": ["exp", "iat", "iss", "aud", "sub"]},
    )
    typ = str(jwt.get_unverified_header(token).get("typ", "")).lower().removeprefix("application/")
    if typ != "at+jwt":  # RFC 9068 access token; the header is covered by the verified signature
        raise jwt.InvalidTokenError("not an access token")
    return claims

Spring Security's resource server checks every bearer token with the JwtDecoder bean. createAtJwtValidator() (Spring Security 6.5 and later) enforces the RFC 9068 profile: typ of at+jwt, the required claims, and the exact issuer and audience. The decoder's own type check is off by default since Spring Security 7.0; validateType(false) keeps it off on 6.5, where it would reject at+jwt. The method is validateType even though Spring's reference documentation shows validateTypes. Tested with Spring Boot 4.1.1 (Spring Security 7.1.1, Nimbus JOSE + JWT 10.9.1) on JDK 21 against a local JWKS: a valid token passes, and alg: none, an HS256 token signed with the RSA public key, an ID-token type, a wrong audience or issuer, an expired token, a missing jti, and attacker keys in jku or jwk all fail, with no request to the jku URL.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtValidators;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
class ResourceServerConfig {

    @Bean
    SecurityFilterChain api(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(requests -> requests.anyRequest().authenticated())
                .oauth2ResourceServer(server -> server.jwt(Customizer.withDefaults())); // uses the bean below
        return http.build();
    }

    @Bean
    JwtDecoder jwtDecoder() {
        // Keys come only from the issuer's JWKS URL; the decoder ignores jku, x5u and jwk headers.
        NimbusJwtDecoder decoder = NimbusJwtDecoder
                .withJwkSetUri("https://issuer.example/.well-known/jwks.json")
                .jwsAlgorithm(SignatureAlgorithm.RS256) // exact allowlist: rejects none, HS256, ES256
                .validateType(false) // the RFC 9068 validator below checks typ instead
                .build();
        // RFC 9068: typ at+jwt; exp, iat, sub, jti and client_id present; exact iss and aud;
        // 60 seconds of clock skew by default.
        decoder.setJwtValidator(JwtValidators.createAtJwtValidator()
                .issuer("https://issuer.example")
                .audience("invoices-api")
                .build());
        return decoder;
    }
}

AddJwtBearer loads the issuer's metadata and signing keys from Authority and validates each token with TokenValidationParameters. ValidAlgorithms and ValidTypes are the two settings most often missing: without them any algorithm the key supports, and any token type, are accepted. The default clock skew is 5 minutes, so set it explicitly. These parameters were tested with Microsoft.AspNetCore.Authentication.JwtBearer 10.0.12 (Microsoft.IdentityModel 8.19.2) on .NET 10: a valid at+jwt token passes, and a typ of JWT, a wrong audience or issuer, an expired token, alg: none, HS256 with the public key, attacker keys in jwk or jku and an ES256 token all fail.

// Program.cs, ASP.NET Core 10 with Microsoft.AspNetCore.Authentication.JwtBearer
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        // Signing keys come from the issuer's discovery document and JWKS, never from the token.
        options.Authority = "https://issuer.example";
        options.MapInboundClaims = false; // keep "sub" and "client_id" as issued
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidIssuer = "https://issuer.example",
            ValidAudience = "invoices-api",
            ValidAlgorithms = [SecurityAlgorithms.RsaSha256], // exact allowlist: no "none", no HS256
            ValidTypes = ["at+jwt"], // RFC 9068 access tokens only, so an ID token is refused
            ClockSkew = TimeSpan.FromSeconds(30), // the default is 5 minutes
            RequireExpirationTime = true,
            RequireSignedTokens = true,
        };
    });
builder.Services.AddAuthorization();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapGet("/invoices", () => Results.Ok()).RequireAuthorization();
app.Run();

For planned rollover, publish new public key K2 alongside K1, allow verifiers to refresh, then begin issuing with K2. Continue accepting K1 only for the period when legitimately issued K1 tokens can remain valid. After their maximum expiry plus the configured clock-skew allowance, retire K1 from normal validation and ensure caches converge.

For example, if the last K1 token was issued at 10:00 with a ten-minute lifetime and a thirty-second skew allowance, the normal overlap must account for acceptance until just before 10:10:30 under an exclusive cutoff rule. The publication lead time depends on cache behavior, so write it down rather than assuming immediate propagation.

Compromise rollover is different: an attacker with K1 can issue fresh-looking tokens. Waiting for an ordinary expiry window may preserve the attacker’s access. Remove or deny K1 promptly, revoke affected sessions or grants where possible, and accept the controlled disruption required by the incident. Merely changing the signer while every verifier still trusts K1 is incomplete. JWTs stay valid until they expire, so keep access-token lifetimes short and keep server-side state, such as session versions or a deny list keyed by jti, for revocation before expiry.

A valid K1 token before cutoff and valid K2 token after propagation should pass. Wrong issuer, audience, purpose, signature, and expired tokens must fail even when their kid is known. Unknown kid refresh should be bounded, then fail if no authorized key matches.

Test stale caches and a JWKS outage using a defined policy for already cached trusted keys. Verify that a removed compromised key cannot persist beyond the stated revocation target. Record which key ID and policy version made the decision, but avoid logging whole bearer tokens.

Two local projects on this page run real JOSE verification. In the “Secure a real HTTP API” project, use a supported Node.js release (22 or later) and npm, run npm ci --ignore-scripts and then npm test. The tests start a loopback HTTP service, generate temporary signing keys, and issue real tokens; they exercise wrong audience, expired token, invalid signature, wrong token purpose, and missing credentials. The “Verify tokens through rotation and revocation” project adds 24 tests against a real local JWKS, including a cached key that outlives its removal from the key set.

Repair the policy functions as instructed by each project: owner and tenant must match trusted invoice fields, and profile updates must select the permitted displayName field. Keep the verifier tests intact. The JWT validation lab at /labs/token-validation/ practices the claim checks in the browser.

Repair the code

JWT validation lab: Validate the purpose and audience of a token

JWT verification lab: Verify a JWT before trusting it

Sources & further reading

The standards, specifications and documentation behind the guidance above. Each is the evidence for a claim on this page; consult it for detail beyond the defaults and versions listed here.

1. RFC 8725: JWT best current practices. February 2020 (BCP 225).
2. IETF draft: JWT best current practices update (rfc8725bis). draft-ietf-oauth-rfc8725bis-10.
3. RFC 9068: JWT profile for OAuth 2.0 access tokens. October 2021.
4. RFC 7519: JWT claims. May 2015.
5. RFC 7518: JSON Web Algorithms, HMAC key size. May 2015; updated by RFC 9864.
6. RFC 7517: JSON Web Key. May 2015.
7. OWASP JSON Web Token Cheat Sheet
8. jose: jwtVerify options
9. Neil Madden: psychic signatures in Java (CVE-2022-21449). 19 April 2022.
10. Spring Security: OAuth 2.0 resource server JWT, RFC 9068 validation
11. Microsoft: configure JWT bearer authentication in ASP.NET Core

Reference information

Tags

OAuth and OpenID ConnectJSON Web Tokens (JWT)Key management

SDLC phase

Development

Role

Developers

ASVS 5.0.0 requirements

v5.0.0-9.1.1 · v5.0.0-9.1.2 · v5.0.0-9.1.3 · v5.0.0-9.2.1 · v5.0.0-9.2.2 · v5.0.0-9.2.3

CAPEC attack patterns

• CAPEC-475 at MITRE

Download this guide as Markdown

Continue exploring