Configuration
MicroProfile JWT properties
| Property Name | Default | Description |
|---|---|---|
|
|
Public Key supplied as a string, parsed from it in the order defined in section Supported Public Key Formats. |
|
|
Config property allows for an external or internal location of Public Key to be specified. |
|
|
Signature algorithm. Set it to |
|
|
Config property allows for an external or internal location of Private Decryption Key to be specified. |
|
|
Decryption algorithm, both |
|
|
Expected value of the JWT |
|
|
Comma separated list of the audiences that a token |
|
|
Clock skew in seconds used during the token expiration and age verification. An expired token is accepted if the current time is within the number of seconds specified by this property after the token expiration time. The default value is 60 seconds. |
|
|
Number of seconds that must not elapse since the |
|
|
Set this property if another header such as |
|
|
Name of the cookie containing a token. This property will be effective only if |
Supported Public Key Formats
Public Keys may be formatted in any of the following formats, specified in order of precedence:
-
Public Key Cryptography Standards #8 (PKCS#8) PEM
-
JSON Web Key (JWK) or JSON Web Key Set (JWKS)
-
Base64 URL encoded JSON Web Key (JWK) or JSON Web Key Set (JWKS)
SmallRye JWT properties
SmallRye JWT supports many properties which can be used to customize the token processing:
| Property Name | Default | Description |
|---|---|---|
|
|
Location of the verification key which can point to both public and secret keys. Secret keys can only be in the JWK format. Note that 'mp.jwt.verify.publickey.location' will be ignored if this property is set. |
|
|
Signature algorithm. Set it to |
|
|
Set this property to a specific key format such as |
|
|
By default, PEM, JWK or JWK key sets can be read from the local file system or fetched from URIs as required by MicroProfile JWT specification. Set this property to |
|
|
Relax the validation of the verification keys, setting this property to |
|
|
If this property is enabled then a signed token must contain either 'x5t' or 'x5t#S256' X509Certificate thumbprint headers. Verification keys can only be in JWK or PEM Certificate key formats in this case. JWK keys must have a 'x5c' (Base64-encoded X509Certificate) property set. |
|
|
Set this property if another header such as |
|
|
Key cache size. Use this property, as well as |
|
|
Key cache entry time-to-live in minutes. Use this property, as well as |
|
|
Name of the cookie containing a token. This property will be effective only if |
|
|
Set this property to |
|
|
Comma-separated list containing an alternative single or multiple schemes, for example, |
|
|
Key identifier. If it is set then the verification JWK key as well every JWT token must have a matching |
|
|
The maximum number of seconds that a JWT may be issued for use. Effectively, the difference between the expiration date of the JWT and the issued at date must not exceed this value. Setting this property to a non-positive value relaxes the requirement for the token to have a valid 'iat' (issued at) claim. |
|
|
If an application relies on |
|
|
Path to the claim containing the subject name. It starts from the top level JSON object and can contain multiple segments where each segment represents a JSON object name only, example: |
|
|
This property can be used to set a default sub claim value when the current token has no standard or custom |
|
|
Path to the claim containing the groups. It starts from the top level JSON object and can contain multiple segments where each segment represents a JSON object name only, example: |
|
|
Separator for splitting a string which may contain multiple group values. It will only be used if the |
|
|
This property can be used to set a default groups claim value when the current token has no standard groups claim available (or no custom groups claim when |
|
|
JWK cache refresh interval in minutes. It will be ignored unless the |
|
|
Forced JWK cache refresh interval in minutes which is used to restrict the frequency of the forced refresh attempts which may happen when the token verification fails due to the cache having no JWK key with a |
|
|
Expiration grace in seconds. By default an expired token will still be accepted if the current time is no more than 1 min after the token expiry time. This property is deprecated. Use |
|
|
Comma separated list of the audiences that a token |
|
|
Comma separated list of the claims that a token must contain. |
|
|
Config property allows for an external or internal location of Private Decryption Key to be specified. This property is deprecated, use |
|
|
Decryption key supplied as a string. |
|
|
Decryption algorithm. This property is deprecated, use |
|
|
Decryption Key identifier. If it is set then the decryption JWK key as well every JWT token must have a matching |
|
|
TLS trusted certificate which may need to be configured if the keys have to be fetched over |
|
|
Path to TLS trusted certificate which may need to be configured if the keys have to be fetched over |
|
|
Trust all the hostnames. If the keys have to be fetched over |
|
|
Set of trusted hostnames. If the keys have to be fetched over |
|
|
HTTP proxy host. |
|
|
HTTP proxy port. |
|
|
This property can be used to customize a keystore type if either |
|
This property can be used to customize a |
|
|
Keystore password. If |
|
|
This property has to be set to identify a public verification key which will be extracted from |
|
|
This property has to be set to identify a private decryption key if |
|
|
This property may be set if a private decryption key’s password in |
Create JsonWebToken with JWTParser
If the JWT token can not be injected, for example, if it is embedded in the service request payload or the service endpoint acquires it out of band, then one can use JWTParser:
import org.eclipse.microprofile.jwt.JsonWebToken;
import io.smallrye.jwt.auth.principal.JWTParser;
...
@Inject JWTParser parser;
String token = getTokenFromOidcServer();
// Parse and verify the token
JsonWebToken jwt = parser.parse(token);You can also use it to customize the way the token is verified or decrypted. For example, one can supply a local SecretKey:
import javax.crypto.SecretKey;
import javax.ws.rs.GET;
import javax.ws.rs.core.NewCookie;
import javax.ws.rs.core.Response;
import org.eclipse.microprofile.jwt.JsonWebToken;
import io.smallrye.jwt.auth.principal.JWTParser;
import io.smallrye.jwt.build.Jwt;
@Path("/secured")
public class SecuredResource {
@Inject JWTParser parser;
private SecretKey key = createSecretKey();
@GET
@Produces("text/plain")
public Response getUserName(@CookieParam("jwt") String jwtCookie) {
Response response = null;
if (jwtCookie == null) {
String newJwtCookie = Jwt.upn("Alice").sign(key);
// or newJwtCookie = Jwt.upn("alice").encrypt(key);
return Response.ok("Alice").cookie(new NewCookie("jwt", newJwtCookie)).build();
else {
// All mp.jwt and smallrye.jwt properties are still effective, only the verification key is customized.
JsonWebToken jwt = parser.verify(jwtCookie, key);
// or jwt = parser.decrypt(jwtCookie, key);
return Response.ok(jwt.getName()).build();
}
}Note that if you need to use JWTParser to verify the tokens with different verification constraints (for example, tokens have been signed by different providers, using different algorithms, etc) then please use a new instance of io.smallrye.jwt.auth.principal.DefaultJWTParser per every request - DefaultJWTParser has several methods for customizing the verification requirements.
If the same provider uses different keys to secure the token then using a JsonWebKey Set containing several keys may also work with the injected JWTParser.
Token Decryption
If your application needs to accept the tokens with the encrypted claims or with the encrypted inner signed claims then all you have to do is to set
smallrye.jwt.decrypt.key-location pointing to the decryption key.
If this is the only key property which is set then the incoming token is expected to contain the encrypted claims only.
If either mp.jwt.verify.publickey or mp.jwt.verify.publickey.location verification properties are also set then the incoming token is expected to contain
the encrypted inner-signed token.
See Generate JWT tokens and learn how to generate the encrypted or inner-signed and then encrypted tokens fast.
Custom Factories
io.smallrye.jwt.auth.principal.DefaultJWTCallerPrincipalFactory is used by default to parse and verify JWT tokens and convert them to JsonWebToken principals.
It uses MP JWT and smallrye-jwt properties listed in the Configuration section to verify and customize JWT tokens.
If you need to provide your own factory, for example, to avoid verifying the tokens again which have already been verified by the firewall, then you can either use a ServiceLoader mechanism by providing a META-INF/services/io.smallrye.jwt.auth.principal.JWTCallerPrincipalFactory resource or simply have an Alternative CDI bean implementation like this one:
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import javax.annotation.Priority;
import javax.enterprise.context.ApplicationScoped;
import javax.enterprise.inject.Alternative;
import org.jose4j.jwt.JwtClaims;
import org.jose4j.jwt.consumer.InvalidJwtException;
import io.smallrye.jwt.auth.principal.DefaultJWTCallerPrincipal;
import io.smallrye.jwt.auth.principal.JWTAuthContextInfo;
import io.smallrye.jwt.auth.principal.JWTCallerPrincipal;
import io.smallrye.jwt.auth.principal.JWTCallerPrincipalFactory;
import io.smallrye.jwt.auth.principal.ParseException;
@ApplicationScoped
@Alternative
@Priority(1)
public class TestJWTCallerPrincipalFactory extends JWTCallerPrincipalFactory {
@Override
public JWTCallerPrincipal parse(String token, JWTAuthContextInfo authContextInfo) throws ParseException {
try {
// Token has already been verified, parse the token claims only
String json = new String(Base64.getUrlDecoder().decode(token.split("\\.")[1]), StandardCharsets.UTF_8);
return new DefaultJWTCallerPrincipal(JwtClaims.parse(json));
} catch (InvalidJwtException ex) {
throw new ParseException(ex.getMessage());
}
}
}