MicroProfile JSON Web Token2.12.01.21.11.0
This feature enables web applications or microservices to use the Eclipse JSON Web Token 1.0 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.0 feature, add the following element declaration into your server.xml file, inside the featureManager element:
<feature>mpJwt-1.0</feature>
Examples
Configure authentication with MicroProfile JWT
The following example shows how to configure authentication with a JSON Web Token (JWT) in your server.xml file.
<mpJwt id="mympjwt" issuer="https://example.com"
jwksUri="https://localhost:19443/jwt/ibm/api/myBuilder/jwk"/>
<keyStore id="defaultKeyStore" password="keyspass"/>The
mpJwtelement defines the configuration to process the inbound JWTs.The
jwksUriattribute points thempjwtelement to thehttps://localhost:19443/jwt/ibm/api/myBuilder/jwkJWK endpoint URL. The Liberty runtime obtains the public keys to verify the JWT from this endpoint.The
keyStoreelement defines the keystore where the public key is stored. This element validates the JWT when the JSON Web Key Set (JWKS) is not used.
In MicroProfile JSON Web Token 1.1 and later, this configuration is optional and you can use MicroProfile Config properties to configure MicroProfile JWT instead. For more information, see Guide: Securing microservices with JSON Web Tokens.
Configure an authentication filter to log in with MicroProfile JWT
You can use an authentication filter to protect a subset of applications, URLs, or IP addresses with MicroProfile JWT. The security configuration uses MicroProfile JWT 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="myauthFilter"... />
<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 JWTs. 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
idattribute in thekeyStoreelement 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 JWTs.The
sslelement specifies how the application validates the SSL connection to a server. Within thesslelement, theidattribute specifies the"defaultSSLConfig"value that sets the SSL configuration as the default SSL configuration for the server that the application connects to.The
trustStoreRefattribute specifies thedefaultTrustStorevalue to reference thesslelement configuration so that the application recognizes the truststore when it attempts to connect to the server.The
jwksUriattribute specifies thehttps://localhost:19443/jwt/ibm/api/myBuilder/jwkJWK endpoint URL where the server obtains the public keys to verify the JWT.
Configure MicroProfile JWT authentication for only certain applications
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")Alternatively, ypu can configure MicroProfile JWT authorization in the web.xml file. Specify MP-JWT as the value for the auth-method sub-element 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. JWTs 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 mpJwt element, as shown in the following example:
<mpJwt mapToUserRegistry="true"/>When you set the mapToUserRegistry attribute to true, JWTs are forced to validate user claims 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
