Documentation, Support selecting JWT signature and decryption algorithms from JOSE header

[tloodu]

Feature epic details

• For the title of this issue, type: Documentation, Development epic name
• Link to development epic: Support selecting JWT signature and decryption algorithms from JOSE header open-liberty#19498
• Target GA release: 26.0.0.4

Operating systems

Does the documentation apply to all operating systems?

• Yes
• No; specify operating systems: ______

Summary

Provide a concise summary of your feature. What is the update, why does it matter, and to whom? What do 80% of target users need to know to be most easily productive using your runtime update?

• Support is being added to use the algorithm parameter defined in the JOSE header of an incoming token for signature verification.

Configuration

List any new or changed properties, parameters, elements, attributes, etc. Include default values and configuration examples where relevant:

• Features affected: openIdConnectClient, oidcLogin, mpjwt, jwtConsumer
• FROM_HEADER added as a new metatype option for signatureAlgorithm attribute across
• allowedSignatureAlgorithms added as a new metatype attribute
  • Comma-separated list with cardinality of 9
  • Default value: RS256, RS384, RS512, HS256, HS384, HS512, ES256, ES384, ES512

Updates to existing topics

In the Configure JSON Web Token (JWT) authentication for OpenID Connect update the following sentence:

Recognized signature algorithms are listed as possible values for the signatureAlgorithm attribute of the openidConnectClient element. An unsigned JWT is accepted when the signatureAlgorithm attribute is set to none. JSON Web Encryption (JWE) is also supported.

to reference the new example sections specified below:

Recognized signature algorithms are listed as possible values for the signatureAlgorithm attribute of the openidConnectClient element. An unsigned JWT is accepted when the signatureAlgorithm attribute is set to none . For more information about signature algorithm configuration options, see [Accept signed tokens with signature algorithm validation]. JSON Web Encryption (JWE) is also supported.

Create a new topic

Create a new section under the Examples in the following pages:

• https://openliberty.io/docs/latest/reference/feature/openidConnectClient-1.0.html#jwt
• https://openliberty.io/docs/latest/reference/feature/socialLogin-1.0.html
• https://openliberty.io/docs/latest/reference/feature/mpJwt-2.1.html
• https://openliberty.io/docs/latest/reference/feature/jwt-1.0.html

---

Content (OpenID Connect Client)

Accept signed tokens with signature algorithm validation

The OpenID Connect client validates the signature of ID tokens and access tokens to ensure their authenticity and integrity. To configure the Open Liberty OIDC client to process signed tokens, you must set the signatureAlgorithm attribute to either a specific signature algorithm or to FROM_HEADER to use the algorithm specific in the token header.

Specify a fixed signature algorithm

You can configure the client to accept tokens signed with a specific algorithm by setting the signatureAlgorithm attribute to a recognized signature algorithm. When a fixed algorithm is specified, the client rejects any token that is not signed with that algorithm.

The following example shows a configuration that accepts only tokens signed with RS256:

<openidConnectClient 
    id="RP"
    clientId="client01"
    signatureAlgorithm="RS256"
    jwkEndpointUrl="https://example.com/jwtserver/jwk">
</openidConnectClient>

Use the signature algorithm from the token header

You can configure the client to use the signature algorithm from the token header by setting the signatureAlgorithm attribute to FROM_HEADER. This configuration allows the client to accept tokens signed with different algorithms without requiring separate client configurations.

When signatureAlgorithm is set to FROM_HEADER, the OpenID Connect client reads the alg claim from the JOSE header and uses that algorithm to retrieve the public key for signature verification. By default, tokens signed with any Liberty-supported signature algorithm are accepted. For enhanced security, you can restrict which signature algorithms are permitted by configuring the allowedSignatureAlgorithms attribute. This attribute accepts a comma-separated list of algorithm names. Only tokens signed by algorithms in this list will be validated.

The following example shows a configuration that accepts tokens signed with a mixed group of algorithms (RS256, ES384, or HS512):

<openidConnectClient 
    id="RP"
    clientId="client02"
    clientSecret="{xor}LDo8LTor"
    signatureAlgorithm="FROM_HEADER"
    allowedSignatureAlgorithms="RS256, ES384, HS512"
    jwkEndpointUrl="https://example.com/jwtserver/jwk" >
</openidConnectClient>

Key selection for signature verification

When using FROM_HEADER with asymmetric algorithms and a trust store configuration. The client uses the following strategy to locate the appropriate public key for signature verification:

1. The client identifies the alg claim from the token header and searches the trust store for a key alias beginning with that value. For example, rs256_keyalias for RS256 tokens or es384_keyalias for ES384 tokens.
2. If no algorithm-prefixed key is found, the client falls back to using the key specified by the trustAliasName attribute.

Content (JWT Consumer)

Accept signed tokens with signature algorithm validation

JWT consumers support signature algorithm validation for signed tokens. The process for configuring signature algorithm validation for JWT consumers is similar to the [OpenID Connect Client 1.0] feature.

The following example shows a jwtConsumer configuration that accepts only tokens signed with RS256:

<jwtConsumer
    id="myJwtConsumer"
    signatureAlgorithm="RS256"
    trustStoreRef="myTrustStore"
    trustAliasName="myKeyAlias">
</jwtConsumer>

The following example shows a jwtConsumer configuration selects the signature algorithm from the token header and accepts tokens signed with RS256, ES384, or HS512:

<jwtConsumer
    id="myJwtConsumer"
    signatureAlgorithm="FROM_HEADER"
    allowedSignatureAlgorithms="RS256, ES384, HS512"
    jwkEndpointUrl="https://example.com/jwtserver/jwk"
    trustStoreRef="myTrustStore">
</jwtConsumer>

Content (MicroProfile JSON Web Token)

Accept signed tokens with signature algorithm validation

MicroProfile JWT supports signature algorithm validation for signed tokens. The process for configuring signature algorithm validation in MicroProfile JWT is similar to the [OpenID Connect Client 1.0] feature.

The following example shows a configuration that accepts only tokens signed with RS256:

<mpJwt
    id="myMpJwt"
    issuer="https://example.com"
    signatureAlgorithm="RS256"
    jwksUri="https://localhost:19443/jwt/ibm/api/myBuilder/jwk"/>

The following example shows a configuration that selects the signature algorithm from the token header and accepts tokens signed with RS256, ES384, or HS512:

<mpJwt
    id="myMpJwt"
    issuer="https://example.com"
    signatureAlgorithm="FROM_HEADER"
    allowedSignatureAlgorithms="RS256, ES384, HS512"
    jwksUri="https://localhost:19443/jwt/ibm/api/myBuilder/jwk"/>

Note: When using FROM_HEADER option, you cannot use MicroProfile Config properties to configure the signature algorithm (using mp.jwt.verify.publickey.algorithm). The signature algorithm configuration must be specified in the server.xml file.

Content (Social Media Login)

Accept signed tokens with signature algorithm validation

OpenID Connect clients that are configured by using the oidcLogin element in the Social Media Login feature support signature algorithm validation for signed tokens. The process for configuring signature algorithm validation in the Social Media Login feature is identical to the [OpenID Connect Client 1.0] feature.

The following example shows a configuration that accepts only tokens signed with RS256:

<oidcLogin
    id="myOidcLogin"
    clientId="client01"
    signatureAlgorithm="RS256"
    jwkEndpointUrl="https://example.com/jwtserver/jwk"
    ...
/>

The following example shows a configuration that selects the signature algorithm from the token header and accepts tokens signed with RS256, ES384, or HS512:

<oidcLogin
    id="myOidcLogin"
    clientId="client01"
    clientSecret="{xor}LDo8LTor"
    signatureAlgorithm="FROM_HEADER"
    allowedSignatureAlgorithms="RS256, ES384, HS512"
    jwkEndpointUrl="https://example.com/jwtserver/jwk"
    ...
/>

[ramkumar-k-9286]

Hi Taj @tloodu

Suggested changes have been made to the pages.

Draft link:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/openidConnectClient-1.0.html#jwt

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/socialLogin-1.0.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/mpJwt-2.1.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/jwt-1.0.html

Please review the same and add the Developer Reviewed label if you are satisfied with the changes.

Regards,
Ramkumar.

[tloodu]

@ramkumar-k-9286 I have the following suggestions, many of which I missed in my initial issue so sorry about that!

For OpenId Connect Client (https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/openidConnectClient-1.0.html#jwt)

1. Could we make Accept signed tokens with signature algorithm validation into a separate example as done on the other pages. It currently falls under the Configure JSON Web Token (JWT) authentication for OpenID Connect example.
2. Update the following sentence to improve clarity and grammar:

To configure the Open Liberty OIDC client to process signed tokens, you must set the signatureAlgorithm attribute to either a specific single signature algorithm or to FROM_HEADER to use the algorithm specific algorithm specified in the token header.

3. Remove the following snippet of the line:

When signatureAlgorithm is set to FROM_HEADER, the OpenID Connect client reads the alg claim from the JOSE header and uses that algorithm to retrieve the public key for signature verification.

4. Add a few new sentences to improve clarity:

By default, when this option is selected, tokens signed with any Liberty-supported signature algorithm are accepted.

When using FROM_HEADER with asymmetric algorithms and a trust store configuration, the public keys must be prefixed with their corresponding algorithm (for example, RS256_keyalias) for automatic selection. The client uses the following strategy to locate the appropriate public key for signature verification:

5. Under Key selection for signature verification add a sentence for non-FROM_HEADER configs and JWK reference:

When not using FROM_HEADER (using a single algorithm), the client only uses the key specified by the trustAliasName attribute for signature verification. Alternatively, you can configure JWK-based verification as described in Sign and verify JSON Web Tokens with JSON Web Keys

MicroProfile JWT (https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/mpJwt-2.1.html)

1. Change the note to improve wording:

Note: You cannot use MicroProfile Config properties to configure the ‘FROM_HEADER’ signature algorithm option (using mp.jwt.verify.publickey.algorithm). This signature algorithm option must be configured in a server.xml file.

2. Update title of example to: Accept signed MicroProfile JWTs with signature algorithm validation

3. Minor additions to specify the mpjwt configuration:

MicroProfile JWT supports signature algorithm validation for signed tokens JWTs.

The following example shows an mpjwt configuration that accepts only JWTs signed with RS256:

The following example shows an mpjwt configuration that selects the signature algorithm from the JWT header and accepts JWTs signed with either RS256, ES384, or HS512:

For Social Media Login (https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/socialLogin-1.0.html#signtoken)

1. Minor additions to specify the oidcLogin configuration:

The following example shows an oidcLogin configuration that accepts only tokens signed with RS256:

The following example shows an oidcLogin configuration that selects the signature algorithm from the token header and accepts tokens signed with either RS256, ES384, or HS512:

For JWT Consumer (https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/jwt-1.0.html)

1. Update title of example to: Accept signed JWTs with signature algorithm validation

2. Minor additions for clarity:

MicroProfile JWT supports signature algorithm validation for signed tokens JWTs.

The following example shows a jwtConsumer configuration that accepts only tokens JWTs signed with RS256:

The following example shows a jwtConsumer configuration selects the signature algorithm from the token JWT header and accepts tokens JWTs signed with either RS256, ES384, or HS512:

General:

• Can we update the following links added to Social Media Login, MicroProfile JWT and JSON Web Token to point directly to the new OpenID Connect Client example. They currently point to the feature page in general. For example: