Handling JWTs in Java: validation, JWKS, and key rotation

At a glance

What this is: This guide explains how to handle JWTs securely in Java, with a focus on verification, JWKS, key rotation, and common validation pitfalls.

Why it matters: It matters because JWTs often carry authentication and authorisation decisions across APIs, microservices, and enterprise SSO flows, so weak verification can undermine human IAM, NHI service access, and federated identity alike.

👉 Read WorkOS's guide to handling JWTs securely in Java

Context

JWTs are compact bearer tokens used to let one system assert identity or permissions to another, but in Java the security boundary is easy to blur because parsing, decoding, and verifying are separate operations. The primary identity governance issue is not the token format itself, but whether your programme treats a signed assertion as trustworthy only after full verification.

Java teams usually encounter JWTs through Spring Security, Nimbus, or other libraries that hide key handling behind abstractions. That convenience can obscure the controls that matter most for IAM, especially when systems depend on RS256 verification, JWKS discovery, and key rotation across distributed services.

Key questions

Q: How should security teams validate JWTs in Java APIs?

A: Security teams should verify the signature, enforce the expected algorithm, and validate issuer, audience, and expiration before any claim is trusted. In Java, that usually means routing every token through one shared verification path rather than decoding it in controllers or relying on parsing alone. The safe rule is simple: if verification has not succeeded, the token is not trustworthy.

Q: Why do JWKS endpoints matter for JWT security?

A: JWKS endpoints let verifiers fetch the correct public key dynamically, which reduces manual key distribution errors and supports safe rotation. They matter because a token signed with a rotated key still needs to validate without breaking services, and the kid header exists to tell verifiers which key to use. Without JWKS, key drift becomes an operational and security problem.

Q: What do teams get wrong about JWT claims?

A: Teams often assume that a decoded token is already trustworthy, then use claims before signature verification or accept claims that are too broad for the service. Claims are only safe after verification, and they should be limited to the issuer, audience, and lifetime that match the intended trust boundary. Otherwise, a valid token can still create invalid access.

Q: How do you keep JWT verification consistent across microservices?

A: Use one central verification component, configured with the same algorithm rules, JWKS source, and claim checks for every service. That prevents small differences in controller logic from creating trust gaps between APIs. Consistency matters because an identity decision made in one place should mean the same thing everywhere the token is accepted.

Technical breakdown

JWT signatures, claims, and why parsing is not verification

A JWT has three parts: header, payload, and signature. The header states the algorithm, the payload carries claims such as iss, aud, sub, and exp, and the signature proves integrity and origin. Parsing a token only reveals its contents. Verification is the step that checks the signature against the expected key, confirms the algorithm, and validates claims before any access decision is made. In Java, that distinction is easy to lose when helper methods make decoding look authoritative. The real control boundary is verification, not readability.

Practical implication: require full verification before any claim is used for authorisation or session trust.

JWKS, kid, and key rotation in Java services

JWKS lets verifiers fetch public keys from a central endpoint instead of hardcoding PEM files or distributing keys manually. The kid value in the JWT header tells the verifier which key to use, which becomes essential when multiple signing keys are active during rotation. In Java, Nimbus can cache JWKS responses, re-fetch on unknown kid values, and reduce operational drift between issuers and consumers. Without that model, teams end up with stale keys, brittle deployments, and inconsistent verification across services.

Practical implication: use JWKS-backed verification and design rotation so old and new keys overlap until all issued tokens expire.

Algorithm confusion and claim validation in Spring-based APIs

Algorithm confusion happens when a verifier accepts whatever algorithm the token header declares instead of enforcing the one the application expects. That opens a path for attackers to exploit mismatched assumptions between symmetric and asymmetric signing. Claim validation is the second control layer: exp limits lifetime, iss confirms issuer, aud constrains intended audience, and nbf or iat can narrow acceptance windows. In Java API stacks, these checks should sit in one shared verification path, not be recreated in controllers or service methods.

Practical implication: enforce a single verification pipeline that rejects unexpected algorithms and fails closed on claim mismatches.

Breaches seen in the wild

• Salesloft OAuth token breach — hackers stole OAuth tokens to access Salesforce data via Salesloft.
• Internet Archive breach — unsecured GitLab authentication tokens exposed 31M Internet Archive accounts.

Read our 52 NHI Breaches Analysis report for a comprehensive view of breaches impacting Non-Human Identities including AI Agents.

NHI Mgmt Group analysis

JWT verification is an identity control, not a token-handling exercise. Java teams often treat JWTs as transport objects, but the governance decision happens at verification time, when the system decides whether a bearer assertion is still trustworthy. That makes JWT validation part of IAM, not just application plumbing. The moment a service accepts parsed claims before signature and claim checks, it creates an unauthorised trust path. Practitioners should treat verification as the boundary that determines whether identity assertions are real.

JWKS centralises trust, but it also shifts the failure mode from distribution to rotation discipline. Manual key handling fails at scale because each service becomes a separate trust endpoint with its own stale-key risk. JWKS reduces that fragmentation, but only if the issuer publishes overlapping keys and consumers cache and refresh correctly. This aligns with zero trust patterns from NIST SP 800-207 Zero Trust Architecture, where key freshness and continuous validation matter more than initial setup. Practitioners should measure key freshness, not just key presence.

Algorithm enforcement is a governance boundary, not a code style preference. Accepting whatever algorithm is embedded in the header turns verifier discretion into attacker leverage. The problem is broader than cryptography because it shows how identity systems fail when the trust policy is implicit instead of explicit. This is the same design weakness that appears across NHI and federation implementations when verification rules are left to defaults. Practitioners should hard-code accepted algorithms per issuer and reject all others.

Claim scope should match the intended trust domain, or JWTs become overbroad identity carriers. A token that is valid cryptographically can still be wrong for the service that receives it if audience, issuer, or lifetime are too loose. That is where identity blast radius expands: one assertion starts moving across systems that were never meant to trust it. The named concept here is claim trust drift, meaning the gap between where a token was issued and where it is later accepted. Practitioners should limit claim scope to the smallest viable trust boundary.

Centralised JWT logic is how Java teams prevent inconsistent identity decisions across microservices. When each service implements its own partial checks, the programme no longer has one policy. It has many slightly different policies, and attackers look for the weakest one. That is especially risky in Spring-based estates where framework abstractions can hide what is actually verified. Practitioners should centralise token validation and make the verification path observable, testable, and uniform.

From our research:

• The average estimated time to remediate a leaked secret is 27 days, despite 75% of organisations expressing strong confidence in their secrets management capabilities, according to The State of Secrets in AppSec.
• Only 44% of developers are reported to follow security best practices for secrets management, exposing a significant developer behaviour gap.
• That gap is why teams should pair token verification discipline with broader identity controls, as explained in Ultimate Guide to NHIs , Why NHI Security Matters Now.

What this signals

JWT security in Java should be treated as part of the access governance stack, not as a library choice. Teams that centralise verification, enforce explicit issuer rules, and refresh JWKS automatically will reduce the chance that a single token becomes a reusable trust primitive across multiple services.

claim trust drift: the longer a token remains valid and the broader its audience, the easier it is for identity assertions to travel beyond the service that was meant to trust them. That risk grows quickly in microservice estates, where one misconfigured verifier can undermine many downstream decisions. Practitioners should watch for services that accept tokens without checking the full trust boundary.

Java estates that rely on framework defaults should expect more scrutiny on verification observability and key management. If the team cannot show which algorithm, key source, and claim rules are enforced at runtime, it does not have a defensible JWT governance model.

For practitioners

• Enforce full token verification before trust decisions Route every JWT through a single verification path that checks signature, issuer, audience, expiration, and not-before before any claim is consumed for access control.
• Bind each issuer to one allowed algorithm set Configure your Java verifier to accept only the expected signing algorithm for that issuer and reject tokens that attempt algorithm switching or downgrade.
• Adopt JWKS with overlap during rotation Publish new signing keys before use, keep retired keys available until all issued tokens have expired, and let verifiers refresh from the JWKS endpoint automatically.
• Centralise JWT validation in one shared component Implement verification in a filter, security configuration, or interceptor so controllers and services never make ad hoc token trust decisions.

Key takeaways

• JWTs only become trustworthy after signature, algorithm, issuer, audience, and expiry checks all pass in one verification flow.
• JWKS reduces manual key drift, but rotation discipline and cache refresh behaviour decide whether it actually improves control.
• Java teams that scatter token checks across services create inconsistent identity policy and enlarge the effective trust boundary.

Key terms

• Json Web Token: A JWT is a compact signed token used to carry identity or permission claims between systems. In Java estates, it is a bearer credential whose safety depends on strict verification of signature, issuer, audience, and lifetime before any access decision is made.
• Jwks: A JWKS is a published set of public keys that verifiers can fetch to validate signed tokens dynamically. It reduces manual key distribution and supports rotation, but only if issuers overlap keys correctly and consumers refresh them without trusting stale cache state.
• Kid: The kid is a key identifier in the JWT header that tells verifiers which public key to use from a JWKS. It is operationally important in rotated key environments because it lets Java services select the right key without hardcoding a single signing key.
• Claim Trust Drift: Claim trust drift is the gap between where a token was issued and where it is later accepted without enough restriction. It happens when audience, issuer, or lifetime controls are too broad, allowing a valid cryptographic token to create invalid access across systems.

Deepen your knowledge

JWT verification, JWKS rotation, and claim validation are core topics in our NHI Foundation Level course, the industry's only accredited NHI security programme. If you are building a Java identity control model that must hold up across APIs and microservices, it is worth exploring.

This post draws on content published by WorkOS: How to handle JWT in Java. Read the original.