Package com.nimbusds.jwt.proc

Class DefaultJWTProcessor<C extends SecurityContext>

java.lang.Object

com.nimbusds.jwt.proc.DefaultJWTProcessor<C>

All Implemented Interfaces:

JOSEProcessorConfiguration<C>, ConfigurableJWTProcessor<C>, JWTProcessor<C>, JWTProcessorConfiguration<C>

public class DefaultJWTProcessor<C extends SecurityContext>
extends Object
implements ConfigurableJWTProcessor<C>

Default processor of unsecured (plain), signed and encrypted JSON Web Tokens (JWTs).

Must be configured with the following:

• To process signed JWTs: A JWS key selector using the header or the header and claims set to suggest key candidate(s) for the signature verification. The key selection procedure is application-specific and may involve key ID lookup, a certificate check and / or some context.
• To process encrypted JWTs: A JWE key selector using the header to suggest key candidate(s) for decryption. The key selection procedure is application-specific and may involve key ID lookup, a certificate check and / or some context.

An optional context parameter is available to facilitate passing of additional data between the caller and the underlying selector of key candidates (in both directions).

See sections 6 of RFC 7515 (JWS) and RFC 7516 (JWE) for guidelines on key selection.

This processor is configured with a standard header "typ" (type) parameter verifier which expects the signed, encrypted and plain (unsecured) JWTs to have the type header omitted or set to JWT. To accept other "typ" values pass an appropriately configured JWS and / or JWE type verifier.

This processor comes with the default JWS verifier factory and the default JWE decrypter factory; they can construct verifiers / decrypters for all standard JOSE algorithms implemented by the library.

Note that for security reasons this processor is hardwired to reject unsecured (plain) JWTs. Override the process(PlainJWT, SecurityContext) if you need to handle plain JWTs.

A default JWT claims verifier is provided, to perform a minimal check of the claims after a successful JWS verification / JWE decryption. It checks the token expiration (exp) and not-before (nbf) timestamps if these are present. The default JWT claims verifier may be extended to perform additional checks, such as issuer and subject acceptance.

To process generic JOSE objects (with arbitrary payloads) use the DefaultJOSEProcessor class.

Version:

2024-01-15

Author:

Vladimir Dzhuvinov, Misagh Moayyed

Constructor Summary

Constructors

Constructor	Description
DefaultJWTProcessor()

Method Summary

Modifier and Type	Method	Description
protected JWTClaimsSet	extractJWTClaimsSet(JWT jwt)	Extracts the claims set from the specified JWT.
JWEDecrypterFactory	getJWEDecrypterFactory()	Gets the factory for creating JWE decrypter instances.
JWEKeySelector<C>	getJWEKeySelector()	Gets the JWE key selector.
JOSEObjectTypeVerifier<C>	getJWETypeVerifier()	Gets the JWE header "typ" (type) parameter verifier.
JWSKeySelector<C>	getJWSKeySelector()	Gets the JWS key selector.
JOSEObjectTypeVerifier<C>	getJWSTypeVerifier()	Gets the JWS header "typ" (type) parameter verifier.
JWSVerifierFactory	getJWSVerifierFactory()	Gets the factory for creating JWS verifier instances.
JWTClaimsSetAwareJWSKeySelector<C>	getJWTClaimsSetAwareJWSKeySelector()	Gets the JWT claims set aware JWS key selector.
JWTClaimsSetVerifier<C>	getJWTClaimsSetVerifier()	Gets the optional JWT claims set verifier.
JWTClaimsSet	process(EncryptedJWT encryptedJWT, C context)	Processes the specified encrypted JWT by decrypting it.
JWTClaimsSet	process(JWT jwt, C context)	Processes the specified JWT (unsecured, signed or encrypted).
JWTClaimsSet	process(PlainJWT plainJWT, C context)	Processes the specified unsecured (plain) JWT, typically by checking its context.
JWTClaimsSet	process(SignedJWT signedJWT, C context)	Processes the specified signed JWT by verifying its signature.
JWTClaimsSet	process(String jwtString, C context)	Parses and processes the specified JWT (unsecured, signed or encrypted).
protected List<? extends Key>	selectKeys(JWSHeader header, JWTClaimsSet claimsSet, C context)	Selects key candidates for verifying a signed JWT.
void	setJWEDecrypterFactory(JWEDecrypterFactory factory)	Sets the factory for creating JWE decrypter instances.
void	setJWEKeySelector(JWEKeySelector<C> jweKeySelector)	Sets the JWE key selector.
void	setJWETypeVerifier(JOSEObjectTypeVerifier<C> jweTypeVerifier)	Sets the JWE header "typ" (type) parameter verifier.
void	setJWSKeySelector(JWSKeySelector<C> jwsKeySelector)	Sets the JWS key selector.
void	setJWSTypeVerifier(JOSEObjectTypeVerifier<C> jwsTypeVerifier)	Sets the JWS header "typ" (type) parameter verifier.
void	setJWSVerifierFactory(JWSVerifierFactory factory)	Sets the factory for creating JWS verifier instances.
void	setJWTClaimsSetAwareJWSKeySelector(JWTClaimsSetAwareJWSKeySelector<C> jwsKeySelector)	Sets the JWT claims set aware JWS key selector.
void	setJWTClaimsSetVerifier(JWTClaimsSetVerifier<C> claimsVerifier)	Sets the optional JWT claims set verifier.
protected JWTClaimsSet	verifyJWTClaimsSet(JWTClaimsSet claimsSet, C context)	Verifies the specified JWT claims set.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

DefaultJWTProcessor

public DefaultJWTProcessor()

Method Details

getJWSTypeVerifier

public JOSEObjectTypeVerifier<C> getJWSTypeVerifier()

Description copied from interface: JOSEProcessorConfiguration

Gets the JWS header "typ" (type) parameter verifier. This verifier is also applied to plain (unsecured) JOSE objects. If none JWS and plain objects will be rejected.

Specified by:

getJWSTypeVerifier in interface JOSEProcessorConfiguration<C extends SecurityContext>

Returns:

The JWS type verifier, null if not specified.

setJWSTypeVerifier

public void setJWSTypeVerifier(JOSEObjectTypeVerifier<C> jwsTypeVerifier)

Description copied from interface: JOSEProcessorConfiguration

Sets the JWS header "typ" (type) parameter verifier. This verifier is also applied to plain (unsecured) JOSE objects. If none JWS and plain objects will be rejected.

Specified by:

setJWSTypeVerifier in interface JOSEProcessorConfiguration<C extends SecurityContext>

Parameters:

jwsTypeVerifier - The JWS type verifier, null if not specified.

getJWSKeySelector

public JWSKeySelector<C> getJWSKeySelector()

Description copied from interface: JOSEProcessorConfiguration

Gets the JWS key selector. If none JWS objects will be rejected.

Specified by:

getJWSKeySelector in interface JOSEProcessorConfiguration<C extends SecurityContext>

Returns:

The JWS key selector, null if not specified.

setJWSKeySelector

public void setJWSKeySelector(JWSKeySelector<C> jwsKeySelector)

Description copied from interface: JOSEProcessorConfiguration

Sets the JWS key selector. If none JWS objects will be rejected.

Specified by:

setJWSKeySelector in interface JOSEProcessorConfiguration<C extends SecurityContext>

Parameters:

jwsKeySelector - The JWS key selector, null if not specified.

getJWTClaimsSetAwareJWSKeySelector

public JWTClaimsSetAwareJWSKeySelector<C> getJWTClaimsSetAwareJWSKeySelector()

Description copied from interface: JWTProcessorConfiguration

Gets the JWT claims set aware JWS key selector.

Specified by:

getJWTClaimsSetAwareJWSKeySelector in interface JWTProcessorConfiguration<C extends SecurityContext>

Returns:

The JWT claims set aware JWS key selector, null if not specified.

setJWTClaimsSetAwareJWSKeySelector

public void setJWTClaimsSetAwareJWSKeySelector(JWTClaimsSetAwareJWSKeySelector<C> jwsKeySelector)

Description copied from interface: JWTProcessorConfiguration

Sets the JWT claims set aware JWS key selector.

Specified by:

setJWTClaimsSetAwareJWSKeySelector in interface JWTProcessorConfiguration<C extends SecurityContext>

Parameters:

jwsKeySelector - The JWT claims set aware JWS key selector, null if not specified.

getJWETypeVerifier

public JOSEObjectTypeVerifier<C> getJWETypeVerifier()

Description copied from interface: JOSEProcessorConfiguration

Gets the JWE header "typ" (type) parameter verifier. If none JWE objects will be rejected.

Specified by:

getJWETypeVerifier in interface JOSEProcessorConfiguration<C extends SecurityContext>

Returns:

The JWE verifier, null if not specified.

setJWETypeVerifier

public void setJWETypeVerifier(JOSEObjectTypeVerifier<C> jweTypeVerifier)

Description copied from interface: JOSEProcessorConfiguration

Sets the JWE header "typ" (type) parameter verifier. If none JWE objects will be rejected.

Specified by:

setJWETypeVerifier in interface JOSEProcessorConfiguration<C extends SecurityContext>

Parameters:

jweTypeVerifier - The JWE type verifier, null if not specified.

getJWEKeySelector

public JWEKeySelector<C> getJWEKeySelector()

Description copied from interface: JOSEProcessorConfiguration

Gets the JWE key selector. If none JWE objects will be rejected.

Specified by:

getJWEKeySelector in interface JOSEProcessorConfiguration<C extends SecurityContext>

Returns:

The JWE key selector, null if not specified.

setJWEKeySelector

public void setJWEKeySelector(JWEKeySelector<C> jweKeySelector)

Description copied from interface: JOSEProcessorConfiguration

Sets the JWE key selector. If none JWE objects will be rejected.

Specified by:

setJWEKeySelector in interface JOSEProcessorConfiguration<C extends SecurityContext>

Parameters:

jweKeySelector - The JWE key selector, null if not specified.

getJWSVerifierFactory

public JWSVerifierFactory getJWSVerifierFactory()

Description copied from interface: JOSEProcessorConfiguration

Gets the factory for creating JWS verifier instances. If none JWS objects will be rejected.

Specified by:

getJWSVerifierFactory in interface JOSEProcessorConfiguration<C extends SecurityContext>

Returns:

The JWS verifier factory, null if not specified.

setJWSVerifierFactory

public void setJWSVerifierFactory(JWSVerifierFactory factory)

Description copied from interface: JOSEProcessorConfiguration

Sets the factory for creating JWS verifier instances. If none JWS objects will be rejected.

Specified by:

setJWSVerifierFactory in interface JOSEProcessorConfiguration<C extends SecurityContext>

Parameters:

factory - The JWS verifier factory, null if not specified.

getJWEDecrypterFactory

public JWEDecrypterFactory getJWEDecrypterFactory()

Description copied from interface: JOSEProcessorConfiguration

Gets the factory for creating JWE decrypter instances. If none JWE objects will be rejected.

Specified by:

getJWEDecrypterFactory in interface JOSEProcessorConfiguration<C extends SecurityContext>

Returns:

The JWE decrypter factory, null if not specified.

setJWEDecrypterFactory

public void setJWEDecrypterFactory(JWEDecrypterFactory factory)

Description copied from interface: JOSEProcessorConfiguration

Sets the factory for creating JWE decrypter instances. If none JWE objects will be rejected.

Specified by:

setJWEDecrypterFactory in interface JOSEProcessorConfiguration<C extends SecurityContext>

Parameters:

factory - The JWE decrypter factory, null if not specified.

getJWTClaimsSetVerifier

public JWTClaimsSetVerifier<C> getJWTClaimsSetVerifier()

Description copied from interface: JWTProcessorConfiguration

Gets the optional JWT claims set verifier. Ensures that the claims set of a JWT complies with an application's requirements.

Specified by:

getJWTClaimsSetVerifier in interface JWTProcessorConfiguration<C extends SecurityContext>

Returns:

The JWT claims set verifier, null if not specified.

setJWTClaimsSetVerifier

public void setJWTClaimsSetVerifier(JWTClaimsSetVerifier<C> claimsVerifier)

Description copied from interface: JWTProcessorConfiguration

Sets the optional JWT claims set verifier. Ensures that the claims set of a JWT complies with an application's requirements.

Specified by:

setJWTClaimsSetVerifier in interface JWTProcessorConfiguration<C extends SecurityContext>

Parameters:

claimsVerifier - The JWT claims set verifier, null if not specified.

extractJWTClaimsSet

protected JWTClaimsSet extractJWTClaimsSet(JWT jwt)
                                    throws BadJWTException

Extracts the claims set from the specified JWT.

Parameters:

jwt - The JWT. Must not be null.

Returns:

The JWT claims set.

Throws:

BadJWTException - If the payload of the JWT doesn't represent a valid JSON object and a JWT claims set.

verifyJWTClaimsSet

protected JWTClaimsSet verifyJWTClaimsSet(JWTClaimsSet claimsSet,
 C context)
                                   throws BadJWTException

Verifies the specified JWT claims set.

Parameters:

claimsSet - The JWT claims set. Must not be null.

context - Optional context, null if not required.

Returns:

The verified JWT claims set.

Throws:

BadJWTException - If the JWT claims set is rejected.

selectKeys

protected List<? extends Key> selectKeys(JWSHeader header,
 JWTClaimsSet claimsSet,
 C context)
                                  throws KeySourceException,
BadJOSEException

Selects key candidates for verifying a signed JWT.

Parameters:

header - The JWS header. Must not be null.

claimsSet - The JWT claims set (not verified). Must not be null.

context - Optional context, null if not required.

Returns:

The key candidates in trial order, empty list if none.

Throws:

KeySourceException - If a key sourcing exception is encountered, e.g. on remote JWK retrieval.

BadJOSEException - If an internal processing exception is encountered.

process

public JWTClaimsSet process(String jwtString,
 C context)
                     throws ParseException,
BadJOSEException,
JOSEException

Description copied from interface: JWTProcessor

Parses and processes the specified JWT (unsecured, signed or encrypted).

Specified by:

process in interface JWTProcessor<C extends SecurityContext>

Parameters:

jwtString - The JWT, compact-encoded to a URL-safe string. Must not be null.

context - Optional context, null if not required.

Returns:

The JWT claims set on success.

Throws:

ParseException - If the string couldn't be parsed to a valid JWT.

BadJOSEException - If the JWT is rejected.

JOSEException - If an internal processing exception is encountered.

process

public JWTClaimsSet process(JWT jwt,
 C context)
                     throws BadJOSEException,
JOSEException

Description copied from interface: JWTProcessor

Processes the specified JWT (unsecured, signed or encrypted).

Specified by:

process in interface JWTProcessor<C extends SecurityContext>

Parameters:

jwt - The JWT. Must not be null.

context - Optional context, null if not required.

Returns:

The JWT claims set on success.

Throws:

BadJOSEException - If the JWT is rejected.

JOSEException - If an internal processing exception is encountered.

process

public JWTClaimsSet process(PlainJWT plainJWT,
 C context)
                     throws BadJOSEException,
JOSEException

Description copied from interface: JWTProcessor

Processes the specified unsecured (plain) JWT, typically by checking its context.

Specified by:

process in interface JWTProcessor<C extends SecurityContext>

Parameters:

plainJWT - The unsecured (plain) JWT. Not null.

context - Optional context, null if not required.

Returns:

The JWT claims set on success.

Throws:

BadJOSEException - If the unsecured (plain) JWT is rejected, after examining the context or due to the payload not being a JSON object.

JOSEException - If an internal processing exception is encountered.

process

public JWTClaimsSet process(SignedJWT signedJWT,
 C context)
                     throws BadJOSEException,
JOSEException

Description copied from interface: JWTProcessor

Processes the specified signed JWT by verifying its signature. The key candidate(s) are selected by examining the JWS header and / or the message context.

Specified by:

process in interface JWTProcessor<C extends SecurityContext>

Parameters:

signedJWT - The signed JWT. Not null.

context - Optional context, null if not required.

Returns:

The JWT claims set on success.

Throws:

BadJOSEException - If the signed JWT is rejected, typically due to a bad signature or the payload not being a JSON object.

JOSEException - If an internal processing exception is encountered.

process

public JWTClaimsSet process(EncryptedJWT encryptedJWT,
 C context)
                     throws BadJOSEException,
JOSEException

Description copied from interface: JWTProcessor

Processes the specified encrypted JWT by decrypting it. The key candidate(s) are selected by examining the JWS header and / or the message context.

Specified by:

process in interface JWTProcessor<C extends SecurityContext>

Parameters:

encryptedJWT - The encrypted JWT. Not null.

context - Optional context, null if not required.

Returns:

The JWT claims set on success.

Throws:

BadJOSEException - If the encrypted JWT is rejected, typically due to failed decryption or the payload not being a JSON object.

JOSEException - If an internal processing exception is encountered.