MicroProfile JSON Web Token
2.1
2.0
1.2
1.1
1.0

This feature enables web applications or microservices to use the Eclipse MicroProfile JSON Web Token 2.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 2.1 feature, add the following element declaration into your server.xml file, inside the featureManager element:

<feature>mpJwt-2.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 the mpjwt element to the https://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 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 JWTs.

  • The ssl element specifies 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 to reference the ssl element configuration 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 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.

Feature configuration elements

Standard API packages provided by this feature

  • jakarta.annotation

  • jakarta.annotation.security

  • jakarta.annotation.sql

Stable API packages provided by this feature

  • org.eclipse.microprofile.auth

  • org.eclipse.microprofile.jwt

Liberty API packages provided by this feature

Features that this feature enables

Supported Java versions

  • JavaSE-11.0

  • JavaSE-17.0

  • JavaSE-21.0

Features that enable this feature

Developing a feature that depends on this feature

If you are developing a feature that depends on this feature, include the following item in the Subsystem-Content header in your feature manifest file.

io.openliberty.mpJwt-2.1; type="osgi.subsystem.feature"

SPI packages provided by this feature