Class JwtValidator.Builder
- Enclosing class:
JwtValidator
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 Summary
Modifier and TypeMethodDescriptionacceptAnyAudience(@Nullable Boolean acceptAnyAudience) Sets whether to accept a token for any audience, without checkingaud.allowedAlgorithms(@Nullable Set<@NonNull JwsAlgorithm> allowedAlgorithms) Sets the algorithms a token may use, compared exactly with itsalg.allowedTypes(@Nullable Set<@NonNull String> allowedTypes) Sets the allowed values of the header'styp.build()Builds the validator.Sets the clock that supplies the current time for the time checks.Sets the allowance for clock differences between the issuer and this application: a token is expired fromexpplus the skew, and is not yet valid, or issued in the future, only beforenbfor afteriatby more than the skew.expectedAudiences(@Nullable Set<@NonNull String> expectedAudiences) Sets the audiences a token may name: a token is accepted when at least one of itsaudvalues is one of these, compared exactly, and other audiences in it are allowed.jwksSource(@Nullable JwksSource jwksSource) Sets where the verification keys come from.maximumTokenLength(@Nullable Integer maximumTokenLength) Sets the longest token accepted, in characters; a longer one is rejected before it is examined.observer(@Nullable JoseObserver observer) Sets the observer that receives this validator's events.requiredClaims(@Nullable Set<@NonNull String> requiredClaims) Sets claims that must be present and not JSONnull, besides the ones always required:iss,exp, andaudunless any audience is accepted.typeRequired(@Nullable Boolean typeRequired) Sets whether a token withouttypis rejected.
-
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.nullclears it- Returns:
- this builder
- Since:
- 1.0.0
-
expectedAudiences
public @NonNull JwtValidator.Builder expectedAudiences(@Nullable Set<@NonNull String> expectedAudiences) Sets the audiences a token may name: a token is accepted when at least one of itsaudvalues 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;nullclears them. The set is copied- Returns:
- this builder
- Throws:
NullPointerException- if the set containsnull- Since:
- 1.0.0
-
acceptAnyAudience
Sets whether to accept a token for any audience, without checkingaud. 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 toJoseObserver.didAcceptAnyAudience(String)when the validator is built and on every validation. It cannot be combined withexpectedAudiences(Set).- Parameters:
acceptAnyAudience- whether to accept any audience;nullrestores the default,false- Returns:
- this builder
- Since:
- 1.0.0
-
allowedAlgorithms
public @NonNull JwtValidator.Builder allowedAlgorithms(@Nullable Set<@NonNull JwsAlgorithm> allowedAlgorithms) Sets the algorithms a token may use, compared exactly with itsalg.The default allows
RS256alone. Widen it only to algorithms your identity provider signs with. An RSA key without analgmember 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 asRS256andPS256, needs keys that name theiralg. Microsoft Entra ID publishes RSA keys withoutalg, 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.nullrestores the default,RS256. The set is copied- Returns:
- this builder
- Throws:
NullPointerException- if the set containsnull- Since:
- 1.0.0
-
allowedTypes
Sets the allowed values of the header'styp. Each is a media type without parameters; a value without/hasapplication/implied (RFC 7515 section 4.1.9), and values are compared ignoring the case of ASCII letters. So the default,JWT, acceptsJWT,jwtandapplication/jwt, and rejects types that mark other profiles, such asat+jwtandlogout+jwt.- Parameters:
allowedTypes- the allowed media types; may be empty, which allows only tokens withouttyp.nullrestores the default,JWT. The set is copied- Returns:
- this builder
- Throws:
NullPointerException- if the set containsnull- Since:
- 1.0.0
-
typeRequired
Sets whether a token withouttypis rejected.- Parameters:
typeRequired- whether the header must havetyp;nullrestores 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 JSONnull, besides the ones always required:iss,exp, andaudunless any audience is accepted.- Parameters:
requiredClaims- claim names, none empty;nullrestores the default, none. The set is copied- Returns:
- this builder
- Throws:
NullPointerException- if the set containsnull- Since:
- 1.0.0
-
clockSkew
Sets the allowance for clock differences between the issuer and this application: a token is expired fromexpplus the skew, and is not yet valid, or issued in the future, only beforenbfor afteriatby more than the skew.- Parameters:
clockSkew- from zero to 5 minutes;nullrestores 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;nullrestores 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;nullrestores 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;nullrestores 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 tooIllegalStateException- if no key source is set, or no expected audiences are set and any audience is not accepted- Since:
- 1.0.0
-