JSON Web Token
1.0

This feature allows the runtime to create JSON Web Tokens(JWT).

Enabling this feature

To enable the JSON Web Token 1.0 feature, add the following element declaration into your server.xml file, inside the featureManager element:

<feature>jwt-1.0</feature>

Examples

Construct JWT for an application

The following example shows how to configure the server to construct a JSON Web Token (JWT) for an application.

<keyStore id="defaultKeyStore" password="keyspass"/>

<jwtBuilder id="myBuilder" keyAlias="default" issuer="https://example.com" expiresInSeconds="600"/>

The id attribute for the jwtBuilder element named myBuilder identifies the JWT builder, and uses the default keyAlias attribute to locate the private key. The issuer attribute in the example is the http://example.com URL that identifies who issued the JSON Web Token.

The expiresInSeconds attribute indicates the token expiration time, which is 600 seconds.

Configure the JWT consumer

When the JSON Web Token feature is enabled, Open Liberty creates a default configuration with the following values.

  • The alg header of the consumed JWT is RS256. You can configure this value on the signatureAlgorithm attribute.

  • A JWT is considered to be valid within 5 minutes of the exp, nbf, and iat claims. You can configure this value on the clockSkew attribute.

You can reconfigure these defaults by specifying a jwtConsumer element with an id value of defaultJWTConsumer and configuring attribute values. You can also create one or more other jwtConsumer elements. Each jwtConsumer element must have a unique, URL-safe string specified as the id attribute value. If the id value is missing, the jwtConsumer is not processed. For more information about the available configuration attributes, see JWT consumer.

For JWT tokens that are signed with RS256 and an X.509 certificate, configure the trustStoreRef and trustAliasName attributes to locate the signature verification key.

  1. Import the JWT issuer’s X.509 certificate into the truststore.

  2. In the jwtConsumer element, specify the truststore ID and the certificate alias.

<jwtConsumer id="defaultJWTConsumer" trustStoreRef="truststore_id" trustAliasName="certificate_alias">
</jwtConsumer>

Verify and parse JWT tokens in your application

The following examples show how to programmatically verify and parse JWT tokens by implementing the com.ibm.websphere.security.jwt.JwtConsumer and com.ibm.websphere.security.jwt.JwtToken APIs in your application.

  1. Create a JwtConsumer object. If you do not specify a configuration ID, the object is tied to the default jwtConsumer configuration.

com.ibm.websphere.security.jwt.JwtConsumer jwtConsumer = JwtConsumer.create();

If you specify a configuration ID, the object is tied to the jwtConsumer configuration with the specified ID.

com.ibm.websphere.security.jwt.JwtConsumer jwtConsumer = JwtConsumer.create("jwtConsumer_configuration_id");

2 . Verify and parse a JWT token by implementing the com.ibm.websphere.security.jwt.JwtToken API.

JwtToken jwtToken = jwtConsumer.createJwt("Base64_encoded_JWT_token>");

Sign and verify JWTs with JSON Web Keys (JWK)

You can configure Open Liberty to use JWKs to sign the JWTs it builds and to verify the JWTs it consumes. For more information, see Sign and verify JSON Web Tokens with JSON Web Keys.

Feature configuration elements

Liberty API packages provided by this feature

Features that this feature enables

Supported Java versions

  • JavaSE-1.8

  • JavaSE-11.0

  • JavaSE-17.0

  • JavaSE-21.0

  • JavaSE-23.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.

com.ibm.websphere.appserver.jwt-1.0; type="osgi.subsystem.feature"