MicroProfile JSON Web Token2.12.01.21.11.0
This feature enables web applications or microservices to use the Eclipse JSON Web Token 1.1 specification to authenticate users instead of, or in addition to, the configured user registry.
You can use MicroProfile Config properties to provide configuration values for MicroProfile JSON Web Token. For more information, see MicroProfile Config Properties: JSON Web Token.
Enabling this feature
To enable the MicroProfile JSON Web Token 1.1 feature, add the following element declaration into your server.xml file, inside the featureManager element:
<feature>mpJwt-1.1</feature>
Examples
Configure MicroProfile JWT
The following example shows authentication with a JSON Web Token (JWT). The mpJwt element defines the configuration to process the inbound JSON Web Tokens. The jwksUri attribute points the mpjwt element towards the public key https://localhost:19443/jwt/ibm/api/myBuilder/jwk, to validate the JWT. The keyStore element defines the keystore and truststore where the public key is stored. The keyStore element validates the JSON Web Token when the JSON Web Key Set (JWKS) is not used:
<mpJwt id="mympjwt" issuer="https://example.com"
jwksUri="https://localhost:19443/jwt/ibm/api/myBuilder/jwk"/>
<keyStore id="defaultKeyStore" password="keyspass"/>In MicroProfile JSON Web Token 1.1 and later, this configuration is optional and you can also use MicroProfile Config properties to configure MicroProfile JWT. For more information, see Guide: Securing microservices with JSON Web Tokens.
Configure authentication filter to login with MicroProfile JWT
You can use an authentication filter to protect a subset of applications, URLs, or IP addresses. The security configuration works when the conditions in the filter are met. In the following example, any requests to the myApp application are authenticated with the mpJwt feature. The authFilterRef attribute that is named myAuthFilter filters the login requests to the myApp application:
<mpjwt authFilterRef="authFilter1" />
<authFilter id="myAuthFilter">
<webApp id="myWebApp"
name="myApp"
matchType="contains"/>
</authFilter>Import a truststore to verify a MicroProfile JWT
You can configure a truststore to verify JSON Web Tokens. The default keystore for MicroProfile does not contain the root certificates that are used to verify the authentication credentials that are stored in JSON Web Tokens. To verify JSON Web Tokens, you can import the default Java truststore, as shown in the following example:
<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" />
<keyStore id="defaultTrustStore" location="MyKeyStoreFile.p12" type="JKS" password="changeit" />
<mpJwt id="mympjwt" issuer="https://example.com"
jwksUri="https://localhost:19443/jwt/ibm/api/myBuilder/jwk"/>The id attribute in the keyStore element specifies the “defaultTrustStore” value to configure a truststore within the keystore. A truststore contains the certificates that are used to validate the requests that are sent to applications with JSON Web Tokens. The ssl element is used to specify how the application validates the SSL connection to a server. Within the ssl element, the id attribute specifies the "defaultSSLConfig" value that sets the SSL configuration as the default SSL configuration for the server that the application connects to. The trustStoreRef attribute specifies the “defaultTrustStore” value that configures the ssl element to reference the truststore so that the application recognizes the truststore when it attempts to connect to the server. The jwksUri attribute specifies the "https://localhost:19443/jwt/ibm/api/myBuilder/jwk” JWK endpoint URL value that the server uses to obtain the public keys from to verify the JWT.
Configure the restriction of MicroProfile JWT authentication
By default, if the MicroProfile JWT feature is configured, all authorized requests from applications must include a valid JSON Web Token in the HTTP header of the API. To modify the default behavior to require JSON Web Tokens in only some applications, you can set the ignoreApplicationAuthMethod attribute to “false” in the mpJwt element, as shown in the following example:
<mpJwt ignoreApplicationAuthMethod=“false”/>After you modify the authorization behavior, you can use either of two options to configure applications to use MicroProfile JWT as a login method. In the API, you can add a @LoginConfig annotation that contains the authMethod attribute to specify MicroProfile JWT as the authentication method as shown in the following example:
@LoginConfig(authMethod = "MP-JWT", realmName = "MP-JWT")You can also add MP-JWT to the auth-method element of the web.xml file to specify MicroProfile JWT as the authentication method in the login-config element, as shown in the following example:
<login-config> <auth-method>MP-JWT</auth-method> <realm-name>MP-JWT</realm-name></login-config>Define role mapping for MicroProfile JWT
By default, JSON Web Tokens use the upn claim from the JWT as the principal name and unique security name of the user. JSON Web Tokens also use the groups claim from the JWT as the group name for security role mapping. To change the default mapping, you can use the userNameAttribute attribute to choose a claim for the user principal. You can also use the groupNameAttribute attribute to choose a claim for the group name, as shown in the following example:
<mpJwt userNameAttribute="claim" groupNameAttribute="claim"/>Validate MicroProfile JWT claims with the user registry
By default, JSON Web Tokens authenticate user claims without validation from the user registry. To modify this behavior, you can set the mapToUserRegistry attribute to true in the the mpJwt element, as shown in the following example:
<mpJwt mapToUserRegistry="true"/>When you set the mapToUserRegistry attribute to true, JSON Web Tokens are forced to validate user claims with the user registry. The user claims are validated based on the user attributes that are contained in the user registry.
Stable API packages provided by this feature
org.eclipse.microprofile.auth
org.eclipse.microprofile.jwt
