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"
    ...
/>