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 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
mpJwt
element defines the configuration to process the inbound JWTs.The
jwksUri
attribute points thempjwt
element to thehttps://localhost:19443/jwt/ibm/api/myBuilder/jwk
JWK endpoint URL. The Liberty runtime obtains the public keys to verify the JWT from this endpoint.The
keyStore
element 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
id
attribute in thekeyStore
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 JWTs.The
ssl
element specifies how the application validates the SSL connection to a server. Within thessl
element, theid
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 thedefaultTrustStore
value to reference thessl
element configuration so that the application recognizes the truststore when it attempts to connect to the server.The
jwksUri
attribute specifies thehttps://localhost:19443/jwt/ibm/api/myBuilder/jwk
JWK 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
Platform Versions
microProfile-1.4
microProfile-2.0
microProfile-2.1
microProfile-2.2
microProfile-3.0
microProfile-3.2
microProfile-3.3