Class JwtValidator.Builder

java.lang.Object
com.revetsec.jose.JwtValidator.Builder
Enclosing class:
JwtValidator

@NotThreadSafe @CheckReturnValue public static final class JwtValidator.Builder extends Object
Builds a JwtValidator.

Each setter stores its value, and build() checks them all. null restores a setting's default. A key source is required, and so are expected audiences unless any audience is accepted: without them build() throws IllegalStateException. A value out of range or a conflicting pair throws IllegalArgumentException.

Since:
1.0.0
Author:
Mark Allen
  • Method Details

    • jwksSource

      Sets where the verification keys come from. Required.
      Parameters:
      jwksSource - the key source; share one only among validators with the same issuer. null clears it
      Returns:
      this builder
      Since:
      1.0.0
    • expectedAudiences

      Sets the audiences a token may name: a token is accepted when at least one of its aud values is one of these, compared exactly, and other audiences in it are allowed. Required unless any audience is accepted.
      Parameters:
      expectedAudiences - at least one audience, none empty; null clears them. The set is copied
      Returns:
      this builder
      Throws:
      NullPointerException - if the set contains null
      Since:
      1.0.0
    • acceptAnyAudience

      Sets whether to accept a token for any audience, without checking aud. That lets a token issued for another application of the same issuer through, so use it only when the issuer serves this application alone. The choice is reported to JoseObserver.didAcceptAnyAudience(String) when the validator is built and on every validation. It cannot be combined with expectedAudiences(Set).
      Parameters:
      acceptAnyAudience - whether to accept any audience; null restores the default, false
      Returns:
      this builder
      Since:
      1.0.0
    • allowedAlgorithms

      Sets the algorithms a token may use, compared exactly with its alg.

      The default allows RS256 alone. Widen it only to algorithms your identity provider signs with. An RSA key without an alg member verifies a token only while exactly one RSA algorithm is allowed, because a key must serve one algorithm (RFC 8725 section 3.1); allowing two RSA algorithms, such as RS256 and PS256, needs keys that name their alg. Microsoft Entra ID publishes RSA keys without alg, so they stop verifying if a second RSA algorithm is allowed (see the supported-algorithms document).

      Parameters:
      allowedAlgorithms - at least one algorithm, and no HMAC algorithm: this validator verifies only with public keys. null restores the default, RS256. The set is copied
      Returns:
      this builder
      Throws:
      NullPointerException - if the set contains null
      Since:
      1.0.0
    • allowedTypes

      Sets the allowed values of the header's typ. Each is a media type without parameters; a value without / has application/ implied (RFC 7515 section 4.1.9), and values are compared ignoring the case of ASCII letters. So the default, JWT, accepts JWT, jwt and application/jwt, and rejects types that mark other profiles, such as at+jwt and logout+jwt.
      Parameters:
      allowedTypes - the allowed media types; may be empty, which allows only tokens without typ. null restores the default, JWT. The set is copied
      Returns:
      this builder
      Throws:
      NullPointerException - if the set contains null
      Since:
      1.0.0
    • typeRequired

      Sets whether a token without typ is rejected.
      Parameters:
      typeRequired - whether the header must have typ; null restores the default, false, which accepts a token without one
      Returns:
      this builder
      Since:
      1.0.0
    • requiredClaims

      Sets claims that must be present and not JSON null, besides the ones always required: iss, exp, and aud unless any audience is accepted.
      Parameters:
      requiredClaims - claim names, none empty; null restores the default, none. The set is copied
      Returns:
      this builder
      Throws:
      NullPointerException - if the set contains null
      Since:
      1.0.0
    • clockSkew

      Sets the allowance for clock differences between the issuer and this application: a token is expired from exp plus the skew, and is not yet valid, or issued in the future, only before nbf or after iat by more than the skew.
      Parameters:
      clockSkew - from zero to 5 minutes; null restores the default, 60 seconds. build() checks the range
      Returns:
      this builder
      Since:
      1.0.0
    • clock

      Sets the clock that supplies the current time for the time checks.
      Parameters:
      clock - the clock; null restores the default, Clock.systemUTC()
      Returns:
      this builder
      Since:
      1.0.0
    • maximumTokenLength

      Sets the longest token accepted, in characters; a longer one is rejected before it is examined.
      Parameters:
      maximumTokenLength - from 8,192 to 1,048,576; null restores the default, 65,536. build() checks the range
      Returns:
      this builder
      Since:
      1.0.0
    • observer

      Sets the observer that receives this validator's events.
      Parameters:
      observer - the observer; null restores the default, JoseObserver.disabledInstance()
      Returns:
      this builder
      Since:
      1.0.0
    • build

      Builds the validator. It does no I/O, even over a remote key source.
      Returns:
      a new validator
      Throws:
      IllegalArgumentException - if a value is out of range: an empty set of algorithms or audiences, an HMAC algorithm, an empty audience or claim name, an allowed type that is not a media type without parameters, a required type with no allowed type, a clock skew or token length out of range; or if any audience is accepted and expected audiences are set too
      IllegalStateException - if no key source is set, or no expected audiences are set and any audience is not accepted
      Since:
      1.0.0