Documentation, JWT Builder Workload Identity and JWK Rotation #8529

Activity

1. jimmy1wu

   added

   26.0.0.11

   on Sep 2, 2026
2. jimmy1wu

   added

   26.0.0.12

   and removed

   26.0.0.11

   on Oct 7, 2026
3. jimmy1wu commented on Oct 7, 2026

   

   jimmy1wu

   on Oct 7, 2026

   MemberAuthor

   More actions

   moving out to 26.0.0.12
4. Zech-Hein commented on Oct 28, 2026

   

   Zech-Hein

   on Oct 28, 2026

   More actions

   Update Details - Page 1

   • https://openliberty.io/docs/latest/reference/feature/jwt-1.0.html

     • After the "construct JWT for an application" section create new section with an example jwtBuilder with workload identity claim

     • Copy section from the beta blog

   Enable workload identity

   To enable workload identity in the JWT Builder, set the workloadIdentityClaim attribute in the jwtBuilder element to your desired claim name. For example:

   <jwtBuilder id="myJwtBuilder" workloadIdentityClaim="workload-identity" />

   When the JwtBuilder API is used to create a JWT, it automatically injects the workload identity into the workload-identity claim. For example:

   JwtBuilder.create("myJwtBuilder")
       .subject("jdoe")
       .audience(List.of("server"))
       .claim("email", "jdoe@example.com")
       .buildJwt();
   

   This code creates a JWT with the following payload:

   {
     "token_type": "Bearer",
     "aud": "server",
     "sub": "jdoe",
     "email": "jdoe@example.com",
     "workload-identity": "myHost,/wlp/usr/,myServer,myApp",
     "iss": "https://localhost:9443/jwt/myJwtBuilder",
     "exp": 1790280039,
     "iat": 1790272839
   }
   
   The format of the workload identity claim’s value is <host-name>,<path-to-usr-dir>,<server-name>,<app-name>. In a containerized environment, you can use the CONTAINER_HOST and CONTAINER_NAME environment variables to customize the <host-name> and <server-name> values.
   
5. Zech-Hein commented on Oct 28, 2026

   

   Zech-Hein

   on Oct 28, 2026

   More actions

   Update details - Page 2

   • https://openliberty.io/docs/latest/json-web-token.html
     • Modify the "dynamic JWK generation" section to include the rotation time and max keys attributes. Right after the sentence "After creation, the key is rotated automatically every 12 hours."

   By default, after creation, the key is rotated automatically every 12 hours. The maximum number of JWKs is 2 by default.

   To configure the JWK rotation interval and the maximum number of JWKs published on the JWK endpoint, set the jwkRotationTime and jwkMaxKeys attributes in the jwtBuilder element. For example:

   <jwtBuilder jwkRotationTime="30m" jwkMaxKeys="4" />

   In this example, the JWKs are rotated every 30 minutes and the JWK endpoint publishes a maximum of 4 JWKs.
6. Zech-Hein commented on Oct 28, 2026

   

   Zech-Hein

   on Oct 28, 2026

   More actions

   Update details - Page 3

   • https://www.ibm.com/docs/en/was-liberty/nd?topic=liberty-building-json-web-tokens-in
     • reference the OL docs for workload identity info - https://openliberty.io/docs/latest/reference/feature/jwt-1.0.html
     • reference the OL docs for JWK additional info - https://openliberty.io/docs/latest/json-web-token.html

   In the second procedure 2.

   Configure the JWT builder by modifying the jwtBuilder element.
   
   For information about jwtBuilder attributes that you can configure, see [JWT Builder (jwtBuilder)](https://www.ibm.com/docs/en/SSAW57_liberty/com.ibm.websphere.liberty.autogen.nd.doc/ae/rwlp_config_jwtBuilder.html).
   

   Add a link to the OL docs, say
   Additional Information in Open Liberty Docs -
   https://openliberty.io/docs/latest/reference/feature/jwt-1.0.html

   And then after the step about

   If the JWT token is signed by using the RS256 algorithm, you can configure the JWT builder to sign the JWT token with JSON Web Key (JWK) by setting jwkEnabled="true". When JWK is enabled, the JWT builder dynamically generates key pairs and signs the JWT token with the private key. To validate the signature, the JWT consumer can retrieve the key from the JWK API, which has the following format:
   
   https://<host_name>:<ssl_port>/jwt/ibm/api/<jwtBuilder_configuration_id>/jwk
   

   Add Additional Information in Open Liberty Docs -
   https://openliberty.io/docs/latest/json-web-token.html
7. Zech-Hein commented on Oct 28, 2026

   

   Zech-Hein

   on Oct 28, 2026

   More actions

   Update Details - Page 4

   • https://openliberty.io/docs/latest/server-configuration-hardening.html

   Add a new section at the bottom called "JWT Workload Identity"
   to say

   Consumers of the workload identity must ensure that the server issuing
   the JWT has the workload identity feature enabled to guarantee that
   the workload identity is generated by Liberty and not by the Java API.