JWT (v6.4)

pac4j allows you to validate JSON web tokens.

The JWT support is based on the excellent Nimbus JOSE JWT library and you should consider reading this algorithm selection guide.

1) Dependency

You need to use the following module: pac4j-jwt.

Example (Maven dependency):

<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-jwt</artifactId>
    <version>${pac4j.version}</version>
</dependency>

2) `JwtAuthenticator`

The JwtAuthenticator validates JWT tokens produced by the JwtGenerator or by other systems.

It can be defined for HTTP clients which deal with TokenCredentials.

It supports plain text, signed and/or encrypted JWT tokens.

In all cases, the JwtAuthenticator requires the JWT to have a subject (sub claim) unless you have defined an identifierGenerator (of type ValueGenerator) to generate an identifier. Otherwise it will throw an exception.

If the provided JWT has an expiration date, then JwtAuthenticator may also be configured to only accept JWTs that pass a date criteria that is compared against the JWT expiration date, via JwtAuthenticator#setExpirationTime()

Notice that for security reasons, plain text JWT tokens will be accepted ONLY if no signature configuration is defined. If one or more signature configurations are defined, the JWT tokens are expected to be signed accordingly.

a) Signature

To handle signed JWT, you must define one or more SignatureConfiguration with the addSignatureConfiguration method.

Three signature configurations are available: with a secret (SecretSignatureConfiguration), using an RSA key pair (RSASignatureConfiguration) or using an elliptic-curve key pair (ECSignatureConfiguration).

To verify a signed JWT, the defined signature configurations will be tried successfully (if the algorithm of the JWT matches the one supported by the signature configuration).

b) Encryption

To handle encrypted JWT, you must define one or more EncryptionConfiguration with the addEncryptionConfiguration method.

Like for signature configurations, three encryption configurations are available: with a secret (SecretEncryptionConfiguration), using an RSA key pair (RSAEncryptionConfiguration) or using an elliptic-curve key pair (ECEncryptionConfiguration).

To decrypt an encrypted JWT, the defined encryption configurations will be tried successfully (if the algorithm of the JWT matches the one supported by the encryption configuration).

Behavior notes (signature vs encryption)

Signature (JWS)
- If at least one SignatureConfiguration is defined on the JwtAuthenticator, a non-signed JWT (PlainJWT) is rejected.
- If no SignatureConfiguration is defined, non-signed JWTs may be accepted (with a warning at startup).
Encryption (JWE)
- Encryption is controlled by the encryptionRequired flag (default: false).
- If encryptionRequired is false, encryption remains optional: even if EncryptionConfigurations are configured, a JWT may be only signed (JWS) and not encrypted, and it will be accepted if the signature is valid.
- If encryptionRequired is true and at least one EncryptionConfiguration is configured, a non-encrypted JWT (JWS or plain) is rejected.
- If a token is encrypted (JWE) and SignatureConfigurations are defined, the decrypted payload must be a signed JWT (nested JWT); a JWE decrypting to a plain (unsigned) JWT is rejected.

Example:

JwtAuthenticator jwtAuthenticator = new JwtAuthenticator();

# define two signature configurations (one based on the KEY2 secret and the other one based on a generated RSA key pair)
jwtAuthenticator.addSignatureConfiguration(new SecretSignatureConfiguration(KEY2));
KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSA");
KeyPair rsaKeyPair = keyGen.generateKeyPair();
jwtAuthenticator.addSignatureConfiguration(new RSASignatureConfiguration(rsaKeyPair));

# define two encryption configurations (one based on the SECRET secret and the other one based on a generated elliptic curve key pair)
jwtAuthenticator.addEncryptionConfiguration(new SecretEncryptionConfiguration(SECRET));
KeyPairGenerator keyGen = KeyPairGenerator.getInstance("EC");
KeyPair ecKeyPair = keyGen.generateKeyPair();
ECEncryptionConfiguration encConfig = new ECEncryptionConfiguration(ecKeyPair);
encConfig.setAlgorithm(JWEAlgorithm.ECDH_ES_A128KW);
encConfig.setMethod(EncryptionMethod.A192CBC_HS384);
jwtAuthenticator.addEncryptionConfiguration(encConfig);

jwtAuthenticator.validate(new TokenCredentials(token, "myclient"));

The JwtAuthenticator also offers two convenient methods to handle JWT:

CommonProfile validateToken(final String token) validates a token and directly returns a pac4j user profile
Map<String, Object> validateTokenAndGetClaims(final String token) validates a token and directly returns a set of claims/attributes, this method is completely agnostic from pac4j profiles.

c) User profiles

if the provided JWT has been generated from a pac4j profile (like FacebookProfile for example) using the JwtGenerator, the JwtAuthenticator will re-create the same profile
if the provided JWT has been created with any other mean, the JwtAuthenticator will create a JwtProfile.

3) `JwtGenerator`

To generate a plain text, signed and/or encrypted JWT, a JwtGenerator can be defined with a SignatureConfiguration or/and EncryptionConfiguration.

Example:

JwtGenerator generator = new JwtGenerator(new SecretSignatureConfiguration(SECRET), new SecretEncryptionConfiguration(SECRET));
String token = generator.generate(facebookProfile);

JWTs may also be generated with an assigned expiration time:

generator.setExpirationTime(new Date());

4) JWK

If your configuration is available as a JSON JWK, you can use the methods of the JWKHelper to:

retrieve the secret from the JSON using the buildSecretFromJwk method
build the RSA key from the JSON using the buildRSAKeyPairFromJwk method
build the elliptic curve key from the JSON using the buildECKeyPairFromJwk method.

Then, you’ll be able to build the appropriate signature or encryption configuration.