Package org.apache.juneau.rest.server.auth.jwt

Class JwtTokenValidator

java.lang.Object
org.apache.juneau.rest.server.auth.jwt.JwtTokenValidator
All Implemented Interfaces:
TokenValidator
public class JwtTokenValidator extends Object implements TokenValidator
TokenValidator that validates signed JWTs against a JWKS-backed key source.

Designed to be paired with BearerTokenGuard in juneau-rest-server. It enforces a deliberately strict default policy so a misconfigured call site can't accidentally accept dangerous tokens:

  • Algorithm allowlisting — defaults to [RS256, ES256]. HS256 is rejected unless the caller explicitly opts in via algorithms(...). "none" (unsigned JWTs) is permanently rejected — there is no opt-in. This defeats the well-known algorithm confusion attack where a JWT is signed with HS256 using the RS256 public key as the HMAC secret.
  • Mandatory claims — iss, aud, exp, nbf are required by default. A token missing any of them is rejected.
  • Clock skew — defaults to 60 seconds tolerance for exp and nbf. Capped at 300 seconds by the builder.
  • JWKS caching — keys are fetched and cached for 5 minutes by default. On fetch failure the cache continues serving past TTL with a warning logged (see JwksCache). When a fresh-cache selection returns no keys (typically because an IdP rotated its signing key mid-TTL), the cache performs one eager out-of-band refresh before failing the request. This behavior is enabled by default (jwksEagerRefreshOnKidMiss(true)) and bounded by a per-cache cooldown (default 10 seconds) plus a single-in-flight guard. Opt out via jwksEagerRefreshOnKidMiss(false). Applies only to jwksUrl(...)-backed caches; a caller-supplied jwkSource(...) is unaffected.
Usage

var validator = JwtTokenValidator.create() .jwksUrl(URI.create("https://issuer.example.com/.well-known/jwks.json")) .issuer("https://issuer.example.com/") .audience("https://api.example.com") .build(); var guard = BearerTokenGuard.create() .realm("api") .validator(validator) .build();

Security notes
  • Never disable iss / aud validation. The builder enforces them.
  • Allowlist HS256 only when both ends of the connection are services you control AND you have a secure secret distribution mechanism. JWKS-published JWTs should be asymmetric.
  • Rotate JWKS keys on a schedule. JwksCache picks up new keys after the configured TTL.
See Also:
Since:
10.0.0

  • Constructor Details

  • Method Details

    • create

      public static JwtTokenValidator.Builder create()
      Static creator.

      Routes builder construction through BeanInstantiator so the jwksCacheTtl default is resolved via @Value from the active Settings chain (juneau.jwt.jwksCacheTtl property → PT5M).

      Returns:
      A new builder.

    • create

      public static JwtTokenValidator.Builder create(BeanStore beanStore)
      Static creator with explicit bean store.
      Parameters:
      beanStore - The bean store to use for dependency injection.
      Returns:
      A new builder.

    • getIssuer

      public String getIssuer()
      Returns the issuer this validator requires on tokens.
      Returns:
      The configured iss value.

    • getAudience

      public String getAudience()
      Returns the audience this validator requires on tokens.
      Returns:
      The configured aud value.

    • getAlgorithms

      public Set<com.nimbusds.jose.JWSAlgorithm> getAlgorithms()
      Returns the allowlist of signing algorithms.
      Returns:
      An unmodifiable copy of the allowlist.

    • getClockSkew

      public Duration getClockSkew()
      Returns the configured clock-skew tolerance.
      Returns:
      The clock skew duration.

    • validate

      public Principal validate(String token) throws AuthenticationException
      Description copied from interface: TokenValidator
      Validates the supplied bearer token and returns the associated Principal.
      Specified by:
      validate in interface TokenValidator
      Parameters:
      token - The raw token string from Authorization: Bearer <token>. Never null.
      Returns:
      The authenticated principal. Must not be null on success.
      Throws:
      AuthenticationException - If the token is invalid, expired, revoked, or otherwise unacceptable.