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

Class JwtTokenValidator.Builder

java.lang.Object
org.apache.juneau.rest.server.auth.jwt.JwtTokenValidator.Builder
Enclosing class:
JwtTokenValidator
public static class JwtTokenValidator.Builder extends Object
Builder class for JwtTokenValidator.

  • Constructor Details

    • Builder

      protected Builder()
      Constructor.

  • Method Details

    • jwksUrl

      public JwtTokenValidator.Builder jwksUrl(URI value)
      Sets the JWKS endpoint URL the validator fetches keys from.

      Mutually exclusive with jwkSource(JWKSource) — set one or the other.

      The URL must use "https" or target a loopback host; the signing-key material fetched from this endpoint is the trust anchor for every token, so a plaintext transport to a non-loopback host is rejected.

      Parameters:
      value - The JWKS URL. Must not be null and must use HTTPS or target a loopback host.
      Returns:
      This object.

    • jwkSource

      public JwtTokenValidator.Builder jwkSource(com.nimbusds.jose.jwk.source.JWKSource<com.nimbusds.jose.proc.SecurityContext> value)
      Sets a custom JWKSource the validator fetches keys from.

      Mutually exclusive with jwksUrl(URI) — set one or the other. Useful for HSM-backed signers, multi-issuer federation, or unit tests that want to inject a deterministic key set without binding to a real HTTPS endpoint.

      Parameters:
      value - The JWK source. Must not be null.
      Returns:
      This object.

    • issuer

      public JwtTokenValidator.Builder issuer(String value)
      Sets the required iss (issuer) claim value.
      Parameters:
      value - The issuer. Must not be null or blank.
      Returns:
      This object.

    • audience

      public JwtTokenValidator.Builder audience(String value)
      Sets the required aud (audience) claim value.
      Parameters:
      value - The audience. Must not be null or blank.
      Returns:
      This object.

    • algorithms

      public JwtTokenValidator.Builder algorithms(com.nimbusds.jose.JWSAlgorithm... values)
      Sets the signing-algorithm allowlist.

      Replaces (not adds to) the default allowlist. Callers wanting HS256 support must include it explicitly. Algorithm.NONE is rejected at build time and at runtime regardless of what is passed here.

      Parameters:
      values - The allowed algorithms. Must contain at least one element; must not contain Algorithm.NONE.
      Returns:
      This object.

    • clockSkew

      public JwtTokenValidator.Builder clockSkew(Duration value)
      Sets the clock-skew tolerance for exp / nbf validation.
      Parameters:
      value - The tolerance. Must be non-negative and not exceed 5 minutes.
      Returns:
      This object.

    • jwksCacheTtl

      public JwtTokenValidator.Builder jwksCacheTtl(Duration value)
      Sets the JWKS cache TTL.
      Parameters:
      value - The TTL. Must be positive.
      Returns:
      This object.

    • jwksEagerRefreshOnKidMiss

      public JwtTokenValidator.Builder jwksEagerRefreshOnKidMiss(boolean value)
      Enables or disables the eager JWKS refresh that fires on a fresh-cache kid miss.

      When true (the default), the first request that presents a token whose signing key is not in the current (still-fresh) cache triggers a single out-of-band JWKS refresh. This closes the rotation window where an IdP publishes a new key mid-TTL and clients would otherwise see up to jwksCacheTtl minutes of spurious 401 responses for perfectly valid tokens. The refresh is bounded by jwksEagerRefreshCooldown(Duration) and a single-in-flight guard (no thundering herd).

      Applies only to jwksUrl(...)-backed caches. A caller-supplied jwkSource(...) is unaffected.

      Parameters:
      value - true to enable (default); false to restore pre-10.0.0 behavior.
      Returns:
      This object.

    • jwksEagerRefreshCooldown

      public JwtTokenValidator.Builder jwksEagerRefreshCooldown(Duration value)
      Sets the minimum spacing between consecutive eager JWKS refreshes.

      A burst of unknown-kid tokens (e.g. misconfigured client, replay attack) or a JWKS-endpoint outage will trigger at most one eager refresh per cooldown window. This prevents the eager-refresh path from becoming a vector for amplified JWKS-endpoint load.

      Must be positive, at most 60 seconds, and at most jwksCacheTtl (validated at build() time).

      Parameters:
      value - The cooldown. Must not be null.
      Returns:
      This object.

    • clock

      public JwtTokenValidator.Builder clock(Clock value)
      Overrides the Clock used for exp / nbf comparisons and JWKS cache TTL. Useful in tests.
      Parameters:
      value - The clock. Must not be null.
      Returns:
      This object.

    • build

      public JwtTokenValidator build()
      Builds the validator.
      Returns:
      A new JwtTokenValidator.