Consuming JSON Web Tokens in Liberty

You can programmatically verify and parse JSON Web Token (JWT) tokens by configuring the JWT consumer element in the server configuration and implementing the com.ibm.websphere.security.jwt.JwtConsumer and com.ibm.websphere.security.jwt.JwtToken APIs in your applications.

[22.0.0.13 and later] In version 22.0.0.13 and later, documentation for the JSON Web Token feature is available on the Open Liberty website.

About this task

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 (jwtConsumer).

For information about JWT APIs, see the JSON Web Token Java documentation or the API documentation included in the product in the ${wlp.install.dir}/dev directory.

Procedure

In the server.xml file, add the jwt-1.0 feature.

<featureManager>
    <feature>jwt-1.0</feature>
    ...
</featureManager>

Optional: 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>
```
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.

For more information, see the JSON Web Token Java documentation.
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>");
```