JwtConsumerBuilder (jose4j 0.5.4 API)

java.lang.Object
- org.jose4j.jwt.consumer.JwtConsumerBuilder

public class JwtConsumerBuilder
extends Object

Use the JwtConsumerBuilder to create the appropriate JwtConsumer for your JWT processing needs.

The specific validation requirements for a JWT are context dependent, however, it typically advisable to require a (reasonable) expiration time, a trusted issuer, and and audience that identifies your system as the intended recipient. For example, a JwtConsumer might be set up and used like this:


   JwtConsumer jwtConsumer = new JwtConsumerBuilder()
     .setRequireExpirationTime() // the JWT must have an expiration time
     .setMaxFutureValidityInMinutes(300) // but the  expiration time can't be too crazy
     .setExpectedIssuer("Issuer") // whom the JWT needs to have been issued by
     .setExpectedAudience("Audience") // to whom the JWT is intended for
     .setVerificationKey(publicKey) // verify the signature with the public key
     .build(); // create the JwtConsumer instance

   try
   {
     //  Validate the JWT and process it to the Claims
     JwtClaims jwtClaims = jwtConsumer.processToClaims(jwt);
     System.out.println("JWT validation succeeded! " + jwtClaims);
   }
   catch (InvalidJwtException e)
   {
     // InvalidJwtException will be thrown, if the JWT failed processing or validation in anyway.
     // Hopefully with meaningful explanations(s) about what went wrong.
     System.out.println("Invalid JWT! " + e);
   }

JwtConsumer instances created from this are thread safe and reusable (as long as any custom Validators or Customizers used are also thread safe).

Constructor Summary

Constructors
Constructor and Description
`JwtConsumerBuilder()` Creates a new JwtConsumerBuilder, which is set up by default to build a JwtConsumer that requires a signature and will validate the core JWT claims when they are present.

Method Summary

Methods
Modifier and Type	Method and Description
`JwtConsumer`	`build()` Create the JwtConsumer with the options provided to the builder.
`JwtConsumerBuilder`	`registerValidator(Validator validator)` Custom Validator implementations, which will be invoked when the `JwtConsumer` is validating the JWT claims.
`JwtConsumerBuilder`	`setAllowedClockSkewInSeconds(int secondsOfAllowedClockSkew)` Set the amount of clock skew to allow for when validate the expiration time, issued at time, and not before time claims.
`JwtConsumerBuilder`	`setDecryptionKey(Key decryptionKey)` Set the key to be used for JWE decryption.
`JwtConsumerBuilder`	`setDecryptionKeyResolver(DecryptionKeyResolver decryptionKeyResolver)` Set the DecryptionKeyResolver to use to select the key for JWE decryption.
`JwtConsumerBuilder`	`setDisableRequireSignature()` Because integrity protection is needed in most usages of JWT, a signature on the JWT is required by default.
`JwtConsumerBuilder`	`setEnableLiberalContentTypeHandling()` According to section 5.2 of the JWT spec, when nested signing or encryption is employed with a JWT, the "cty" header parameter has to be present and have a value of "JWT" to indicate that a nested JWT is the payload of the outer JWT.
`JwtConsumerBuilder`	`setEnableRequireEncryption()` Require that the JWT be encrypted, which is not required by default.
`JwtConsumerBuilder`	`setEvaluationTime(NumericDate evaluationTime)` Set the time used to validate the expiration time, issued at time, and not before time claims.
`JwtConsumerBuilder`	`setExpectedAudience(boolean requireAudienceClaim, String... audience)` Set the audience value(s) to use when validating the audience ("aud") claim of a JWT.
`JwtConsumerBuilder`	`setExpectedAudience(String... audience)` Set the audience value(s) to use when validating the audience ("aud") claim of a JWT and require that an audience claim be present.
`JwtConsumerBuilder`	`setExpectedIssuer(boolean requireIssuer, String expectedIssuer)` Indicates whether or not the issuer ("iss") claim is required and optionally what the expected value is.
`JwtConsumerBuilder`	`setExpectedIssuer(String expectedIssuer)` Indicates the expected value of the issuer ("iss") claim and that the claim is required.
`JwtConsumerBuilder`	`setExpectedIssuers(boolean requireIssuer, String... expectedIssuers)` Indicates whether or not the issuer ("iss") claim is required and optionally what the expected values can be.
`JwtConsumerBuilder`	`setExpectedSubject(String subject)` Require that a subject ("sub") claim be present in the JWT and that its value match that of the provided subject.
`JwtConsumerBuilder`	`setJweAlgorithmConstraints(AlgorithmConstraints constraints)` Set the JWE algorithm constraints to be applied to key management when processing the JWT.
`JwtConsumerBuilder`	`setJweContentEncryptionAlgorithmConstraints(AlgorithmConstraints constraints)` Set the JWE algorithm constraints to be applied to content encryption when processing the JWT.
`JwtConsumerBuilder`	`setJweCustomizer(JweCustomizer jweCustomizer)` Set a callback JweCustomizer that provides a hook to call arbitrary methods on the/any JsonWebEncryption prior to the JwsConsumer using it for decryption.
`JwtConsumerBuilder`	`setJweProviderContext(ProviderContext jweProviderContext)` Sets the `ProviderContext` for any JWE operations to be done by the JwtConsumer being built.
`JwtConsumerBuilder`	`setJwsAlgorithmConstraints(AlgorithmConstraints constraints)` Set the JWS algorithm constraints to be applied when processing the JWT.
`JwtConsumerBuilder`	`setJwsCustomizer(JwsCustomizer jwsCustomizer)` Set a callback JwsCustomizer that provides a hook to call arbitrary methods on the/any JsonWebSignature prior to the JwsConsumer using it to verify the signature.
`JwtConsumerBuilder`	`setJwsProviderContext(ProviderContext jwsProviderContext)` Sets the `ProviderContext` for any JWS operations to be done by the JwtConsumer being built.
`JwtConsumerBuilder`	`setMaxFutureValidityInMinutes(int maxFutureValidityInMinutes)` Set maximum on how far in the future the "exp" claim can be.
`JwtConsumerBuilder`	`setRelaxDecryptionKeyValidation()` Bypass the strict checks on the decryption key.
`JwtConsumerBuilder`	`setRelaxVerificationKeyValidation()` Bypass the strict checks on the verification key.
`JwtConsumerBuilder`	`setRequireExpirationTime()` Require that the JWT contain an expiration time ("exp") claim.
`JwtConsumerBuilder`	`setRequireIssuedAt()` Require that the JWT contain an issued at time ("iat") claim.
`JwtConsumerBuilder`	`setRequireJwtId()` Require that a JWT ID ("jti") claim be present in the JWT.
`JwtConsumerBuilder`	`setRequireNotBefore()` Require that the JWT contain an not before ("nbf") claim.
`JwtConsumerBuilder`	`setRequireSubject()` Require that a subject ("sub") claim be present in the JWT.
`JwtConsumerBuilder`	`setSkipAllDefaultValidators()` Skip all the default claim validation but not those provided via `registerValidator(Validator)`.
`JwtConsumerBuilder`	`setSkipAllValidators()` Skip all claims validation.
`JwtConsumerBuilder`	`setSkipDefaultAudienceValidation()` Skip the default audience validation.
`JwtConsumerBuilder`	`setSkipSignatureVerification()` Skip signature verification.
`JwtConsumerBuilder`	`setVerificationKey(Key verificationKey)` Set the key to be used for JWS signature/MAC verification.
`JwtConsumerBuilder`	`setVerificationKeyResolver(VerificationKeyResolver verificationKeyResolver)` Set the VerificationKeyResolver to use to select the key for JWS signature/MAC verification.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - JwtConsumerBuilder
```
public JwtConsumerBuilder()
```
    Creates a new JwtConsumerBuilder, which is set up by default to build a JwtConsumer that requires a signature and will validate the core JWT claims when they are present. The various methods on the builder should be used to customize the JwtConsumer's behavior as appropriate.
- Method Detail
  - setEnableRequireEncryption
```
public JwtConsumerBuilder setEnableRequireEncryption()
```
    Require that the JWT be encrypted, which is not required by default.
    
    Returns:
    the same JwtConsumerBuilder
  - setDisableRequireSignature
```
public JwtConsumerBuilder setDisableRequireSignature()
```
    Because integrity protection is needed in most usages of JWT, a signature on the JWT is required by default. Calling this turns that requirement off. It may be necessary, for example, when integrity is ensured though other means like a JWE using a symmetric key management algorithm.
    
    Returns:
    the same JwtConsumerBuilder
  - setEnableLiberalContentTypeHandling
```
public JwtConsumerBuilder setEnableLiberalContentTypeHandling()
```
    According to section 5.2 of the JWT spec, when nested signing or encryption is employed with a JWT, the "cty" header parameter has to be present and have a value of "JWT" to indicate that a nested JWT is the payload of the outer JWT.
    
    Not all JWTs follow that requirement of the spec and this provides a work around for consuming non-compliant JWTs. Calling this method tells the JwtConsumer to be a bit more liberal in processing and make a best effort when the "cty" header isn’t present and the payload doesn't parse as JSON but can be parsed into a JOSE object.
    
    Returns:
    the same JwtConsumerBuilder
  - setSkipSignatureVerification
```
public JwtConsumerBuilder setSkipSignatureVerification()
```
    Skip signature verification.
    This might be useful in cases where you don't have enough information to set up a validating JWT consumer without cracking open the JWT first. For example, in some contexts you might not know who issued the token without looking at the "iss" claim inside the JWT. In such a case two JwtConsumers cab be used in a "two-pass" validation of sorts - the first JwtConsumer parses the JWT but doesn't validate the signature or claims due to the use of methods like this one and the second JwtConsumers does the actual validation.
    
    Returns:
    the same JwtConsumerBuilder
  - setSkipAllValidators
```
public JwtConsumerBuilder setSkipAllValidators()
```
    Skip all claims validation.
    This might be useful in cases where you don't have enough information to set up a validating JWT consumer without cracking open the JWT first. For example, in some contexts you might not know who issued the token without looking at the "iss" claim inside the JWT. In such a case two JwtConsumers cab be used in a "two-pass" validation of sorts - the first JwtConsumer parses the JWT but doesn't validate the signature or claims due to the use of methods like this one and the second JwtConsumers does the actual validation.
    
    Returns:
    the same JwtConsumerBuilder
  - setSkipAllDefaultValidators
```
public JwtConsumerBuilder setSkipAllDefaultValidators()
```
    Skip all the default claim validation but not those provided via registerValidator(Validator).
    
    Returns:
    the same JwtConsumerBuilder
  - setJwsAlgorithmConstraints
```
public JwtConsumerBuilder setJwsAlgorithmConstraints(AlgorithmConstraints constraints)
```
    Set the JWS algorithm constraints to be applied when processing the JWT.
    
    Parameters:
    constraints - the AlgorithmConstraints to use for JWS processing
    
    Returns:
    the same JwtConsumerBuilder
  - setJweAlgorithmConstraints
```
public JwtConsumerBuilder setJweAlgorithmConstraints(AlgorithmConstraints constraints)
```
    Set the JWE algorithm constraints to be applied to key management when processing the JWT.
    
    Parameters:
    constraints - the AlgorithmConstraints to use for JWE key management algorithm processing
    
    Returns:
    the same JwtConsumerBuilder
  - setJweContentEncryptionAlgorithmConstraints
```
public JwtConsumerBuilder setJweContentEncryptionAlgorithmConstraints(AlgorithmConstraints constraints)
```
    Set the JWE algorithm constraints to be applied to content encryption when processing the JWT.
    
    Parameters:
    constraints - the AlgorithmConstraints to use for JWE content encryption processing
    
    Returns:
    the same JwtConsumerBuilder
  - setVerificationKey
```
public JwtConsumerBuilder setVerificationKey(Key verificationKey)
```
    Set the key to be used for JWS signature/MAC verification.
    
    Parameters:
    verificationKey - the verification key.
    
    Returns:
    the same JwtConsumerBuilder
  - setVerificationKeyResolver
```
public JwtConsumerBuilder setVerificationKeyResolver(VerificationKeyResolver verificationKeyResolver)
```
    Set the VerificationKeyResolver to use to select the key for JWS signature/MAC verification. A VerificationKeyResolver enables a verification key to be chosen dynamically based on more information, like the JWS headers, about the message being processed.
    
    Parameters:
    verificationKeyResolver - the VerificationKeyResolver
    
    Returns:
    the same JwtConsumerBuilder
    See Also:
    HttpsJwksVerificationKeyResolver, JwksVerificationKeyResolver, X509VerificationKeyResolver
  - setDecryptionKey
```
public JwtConsumerBuilder setDecryptionKey(Key decryptionKey)
```
    Set the key to be used for JWE decryption.
    
    Parameters:
    decryptionKey - the decryption key.
    
    Returns:
    the same JwtConsumerBuilder
  - setDecryptionKeyResolver
```
public JwtConsumerBuilder setDecryptionKeyResolver(DecryptionKeyResolver decryptionKeyResolver)
```
    Set the DecryptionKeyResolver to use to select the key for JWE decryption. A DecryptionKeyResolver enables a decryption key to be chosen dynamically based on more information, like the JWE headers, about the message being processed.
    
    Parameters:
    decryptionKeyResolver - the VerificationKeyResolver
    
    Returns:
    the same JwtConsumerBuilder
    See Also:
    JwksDecryptionKeyResolver
  - setExpectedAudience
```
public JwtConsumerBuilder setExpectedAudience(String... audience)
```
    Set the audience value(s) to use when validating the audience ("aud") claim of a JWT and require that an audience claim be present. Audience validation will succeed, if any one of the provided values is equal to any one of the values of the "aud" claim in the JWT.
    
    From Section 4.1.3 of RFC 7519: The "aud" (audience) claim identifies the recipients that the JWT is intended for. Each principal intended to process the JWT MUST identify itself with a value in the audience claim. If the principal processing the claim does not identify itself with a value in the "aud" claim when this claim is present, then the JWT MUST be rejected. In the general case, the "aud" value is an array of case- sensitive strings, each containing a StringOrURI value. In the special case when the JWT has one audience, the "aud" value MAY be a single case-sensitive string containing a StringOrURI value. The interpretation of audience values is generally application specific. Use of this claim is OPTIONAL.
    
    Equivalent to calling setExpectedAudience(boolean, String...) with true as the first argument.
    
    Parameters:
    audience - the audience value(s) that identify valid recipient(s) of a JWT
    
    Returns:
    the same JwtConsumerBuilder
  - setExpectedAudience
```
public JwtConsumerBuilder setExpectedAudience(boolean requireAudienceClaim,
                                     String... audience)
```
    Set the audience value(s) to use when validating the audience ("aud") claim of a JWT. Audience validation will succeed, if any one of the provided values is equal to any one of the values of the "aud" claim in the JWT.
    
    If present, the audience claim will always be validated (unless explicitly disabled). The requireAudienceClaim parameter can be used to indicate whether or not the presence of the audience claim is required. In most cases requireAudienceClaim should be true.
    
    From Section 4.1.3 of RFC 7519: The "aud" (audience) claim identifies the recipients that the JWT is intended for. Each principal intended to process the JWT MUST identify itself with a value in the audience claim. If the principal processing the claim does not identify itself with a value in the "aud" claim when this claim is present, then the JWT MUST be rejected. In the general case, the "aud" value is an array of case- sensitive strings, each containing a StringOrURI value. In the special case when the JWT has one audience, the "aud" value MAY be a single case-sensitive string containing a StringOrURI value. The interpretation of audience values is generally application specific. Use of this claim is OPTIONAL.
    
    Parameters:
    requireAudienceClaim - true, if an audience claim has to be present for validation to succeed. false, otherwise
    audience - the audience value(s) that identify valid recipient(s) of a JWT
    
    Returns:
    the same JwtConsumerBuilder
  - setSkipDefaultAudienceValidation
```
public JwtConsumerBuilder setSkipDefaultAudienceValidation()
```
    Skip the default audience validation.
    
    Returns:
    the same JwtConsumerBuilder
  - setExpectedIssuers
```
public JwtConsumerBuilder setExpectedIssuers(boolean requireIssuer,
                                    String... expectedIssuers)
```
    Indicates whether or not the issuer ("iss") claim is required and optionally what the expected values can be.
    
    Parameters:
    requireIssuer - true if issuer claim is required, false otherwise
    expectedIssuers - the values, one of which the issuer claim must match to pass validation, null means that any value is acceptable
    
    Returns:
    the same JwtConsumerBuilder
  - setExpectedIssuer
```
public JwtConsumerBuilder setExpectedIssuer(boolean requireIssuer,
                                   String expectedIssuer)
```
    Indicates whether or not the issuer ("iss") claim is required and optionally what the expected value is.
    
    Parameters:
    requireIssuer - true if issuer is required, false otherwise
    expectedIssuer - the value that the issuer claim must have to pass validation, null means that any value is acceptable
    
    Returns:
    the same JwtConsumerBuilder
  - setExpectedIssuer
```
public JwtConsumerBuilder setExpectedIssuer(String expectedIssuer)
```
    Indicates the expected value of the issuer ("iss") claim and that the claim is required. Equivalent to calling setExpectedIssuer(boolean, String) with true as the first argument.
    
    Parameters:
    expectedIssuer - the value that the issuer claim must have to pass validation, null means that any value is acceptable
    
    Returns:
    the same JwtConsumerBuilder
  - setRequireSubject
```
public JwtConsumerBuilder setRequireSubject()
```
    Require that a subject ("sub") claim be present in the JWT.
    
    Returns:
    the same JwtConsumerBuilder
  - setExpectedSubject
```
public JwtConsumerBuilder setExpectedSubject(String subject)
```
    Require that a subject ("sub") claim be present in the JWT and that its value match that of the provided subject. The subject ("sub") claim is defined in Section 4.1.2 of RFC 7519.
    
    Parameters:
    subject - the required value of the subject claim.
    
    Returns:
    the same JwtConsumerBuilder
  - setRequireJwtId
```
public JwtConsumerBuilder setRequireJwtId()
```
    Require that a JWT ID ("jti") claim be present in the JWT.
    
    Returns:
    the same JwtConsumerBuilder
  - setRequireExpirationTime
```
public JwtConsumerBuilder setRequireExpirationTime()
```
    Require that the JWT contain an expiration time ("exp") claim. The expiration time is always checked when present (unless explicitly disabled) but calling this method strengthens the requirement such that a JWT without an expiration time will not pass validation.
    
    Returns:
    the same JwtConsumerBuilder
  - setRequireIssuedAt
```
public JwtConsumerBuilder setRequireIssuedAt()
```
    Require that the JWT contain an issued at time ("iat") claim.
    
    Returns:
    the same JwtConsumerBuilder
  - setRequireNotBefore
```
public JwtConsumerBuilder setRequireNotBefore()
```
    Require that the JWT contain an not before ("nbf") claim.
    
    Returns:
    the same JwtConsumerBuilder
  - setEvaluationTime
```
public JwtConsumerBuilder setEvaluationTime(NumericDate evaluationTime)
```
    Set the time used to validate the expiration time, issued at time, and not before time claims. If not set (or null), the current time will be used to validate the date claims.
    
    Parameters:
    evaluationTime - the time with respect to which to validate the date claims.
    
    Returns:
    the same JwtConsumerBuilder
  - setAllowedClockSkewInSeconds
```
public JwtConsumerBuilder setAllowedClockSkewInSeconds(int secondsOfAllowedClockSkew)
```
    Set the amount of clock skew to allow for when validate the expiration time, issued at time, and not before time claims.
    
    Parameters:
    secondsOfAllowedClockSkew - the number of seconds of leniency in date comparisons
    
    Returns:
    the same JwtConsumerBuilder
  - setMaxFutureValidityInMinutes
```
public JwtConsumerBuilder setMaxFutureValidityInMinutes(int maxFutureValidityInMinutes)
```
    Set maximum on how far in the future the "exp" claim can be.
    
    Parameters:
    maxFutureValidityInMinutes - how far is too far (in minutes)
    
    Returns:
    the same JwtConsumerBuilder
  - setRelaxVerificationKeyValidation
```
public JwtConsumerBuilder setRelaxVerificationKeyValidation()
```
    Bypass the strict checks on the verification key. This might be needed, for example, if the JWT issuer is using 1024 bit RSA keys or HMAC secrets that are too small (smaller than the size of the hash output).
    
    Returns:
    the same JwtConsumerBuilder
  - setRelaxDecryptionKeyValidation
```
public JwtConsumerBuilder setRelaxDecryptionKeyValidation()
```
    Bypass the strict checks on the decryption key.
    
    Returns:
    the same JwtConsumerBuilder
  - registerValidator
```
public JwtConsumerBuilder registerValidator(Validator validator)
```
    Custom Validator implementations, which will be invoked when the JwtConsumer is validating the JWT claims.
    
    Parameters:
    validator - the validator
    
    Returns:
    the same JwtConsumerBuilder
  - setJwsCustomizer
```
public JwtConsumerBuilder setJwsCustomizer(JwsCustomizer jwsCustomizer)
```
    Set a callback JwsCustomizer that provides a hook to call arbitrary methods on the/any JsonWebSignature prior to the JwsConsumer using it to verify the signature. This might be used, for example, to allow for critical ("crit") headers vai JsonWebStructure.setKnownCriticalHeaders(String...) that the caller knows how to handle and needs to tell the JwsConsumer to allow them.
    
    Parameters:
    jwsCustomizer - the JwsCustomizer implementation
    
    Returns:
    the same JwtConsumerBuilder
  - setJweCustomizer
```
public JwtConsumerBuilder setJweCustomizer(JweCustomizer jweCustomizer)
```
    Set a callback JweCustomizer that provides a hook to call arbitrary methods on the/any JsonWebEncryption prior to the JwsConsumer using it for decryption. This might be used, for example, to allow for critical ("crit") headers vai JsonWebStructure.setKnownCriticalHeaders(String...) that the caller knows how to handle and needs to tell the JwsConsumer to allow them.
    
    Parameters:
    jweCustomizer - the JweCustomizer implementation
    
    Returns:
    the same JwtConsumerBuilder
  - setJwsProviderContext
```
public JwtConsumerBuilder setJwsProviderContext(ProviderContext jwsProviderContext)
```
    Sets the ProviderContext for any JWS operations to be done by the JwtConsumer being built. This allows for a particular Java Cryptography Architecture provider to be indicated by name to be used for signature/MAC verification operations.
    
    Parameters:
    jwsProviderContext - the ProviderContext object indicating the Java Cryptography Architecture provider to be used for JWS signature/MAC verification operations when consuming a JWT.
    
    Returns:
    the same JwtConsumerBuilder
  - setJweProviderContext
```
public JwtConsumerBuilder setJweProviderContext(ProviderContext jweProviderContext)
```
    Sets the ProviderContext for any JWE operations to be done by the JwtConsumer being built. This allows for a particular Java Cryptography Architecture provider to be indicated by name to be used for decryption and related operations.
    
    Parameters:
    jweProviderContext - the ProviderContext object indicating the Java Cryptography Architecture provider to be used for decryption and related operations operations when consuming a JWT.
    
    Returns:
    the same JwtConsumerBuilder
  - build
```
public JwtConsumer build()
```
    Create the JwtConsumer with the options provided to the builder.
    
    Returns:
    the JwtConsumer

Class JwtConsumerBuilder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

JwtConsumerBuilder

Method Detail

setEnableRequireEncryption

setDisableRequireSignature

setEnableLiberalContentTypeHandling

setSkipSignatureVerification

setSkipAllValidators

setSkipAllDefaultValidators

setJwsAlgorithmConstraints

setJweAlgorithmConstraints

setJweContentEncryptionAlgorithmConstraints

setVerificationKey

setVerificationKeyResolver

setDecryptionKey

setDecryptionKeyResolver

setExpectedAudience

setExpectedAudience

setSkipDefaultAudienceValidation

setExpectedIssuers

setExpectedIssuer

setExpectedIssuer

setRequireSubject

setExpectedSubject

setRequireJwtId

setRequireExpirationTime

setRequireIssuedAt

setRequireNotBefore

setEvaluationTime

setAllowedClockSkewInSeconds

setMaxFutureValidityInMinutes

setRelaxVerificationKeyValidation

setRelaxDecryptionKeyValidation

registerValidator

setJwsCustomizer

setJweCustomizer

setJwsProviderContext

setJweProviderContext

build