Document JWT header parameters used for JWK selection during signature verification

[tloodu]

Page to update: https://openliberty.io/docs/latest/json-web-token.html

---

Discussion has come up to update the Sign and verify JSON Web Tokens with JSON Web Keys documentation page to describe how Open Liberty selects a public key from a JWKS document using header parameters. Open Liberty supports the kid, x5t, and x5t#S256 JWT header parameters to assist with key selection, which should be briefly documented.

This content would be best situated under the Verify JWTs with JWKs section and before the description of how to enable JWK verification in Open Liberty.

Content:

During JWT signature verification, JWKS documents are used to identify the appropriate public key for validation. Open Liberty matches the parameters in the incoming JWT header against the corresponding fields in the key entries.

Open Liberty processes key selection using the kid (Key ID) header parameter within the JWT header, as well as with the x5t (SHA-1) and x5t#S256 parameters, which identify keys by their X.509 certificate thumbprints. While these parameters are optional in both the JWT header and the JWK entries, a matching value in both uniquely identifies the public key required for verification.

[ayoho]

Suggested edits:

During JWT signature verification, JWKS documents are used to identify the appropriate public key for validation. Open Liberty matches the parameters in the incoming JWT header against the corresponding fields in the key entries within a JWKS document.

Open Liberty processes performs key selection using one, and only one, of the following JWT headers, in this order:

• kid (Key ID)
• x5t#S256 (X.509 Certificate SHA-256 Thumbprint)
• x5t (X.509 Certificate SHA-1 Thumbprint)

For example, if Liberty is verifying a JWT that contains an x5t header parameter and does not contain either a kid or a x5t#S256 header parameter, a key in the JWKS document with a corresponding x5t value, if one exists, will be used to verify the JWT signature. If a key with a matching x5t value is not found in the JWKS document, signature verification will fail.

In another example, if Liberty is verifying a JWT that contains both a kid and x5t#S256 header parameter, Liberty will expect to find a key in the JWKS document with a matching kid value. If a matching key is not found, signature verification will fail; Liberty will not fall back to using the x5t#S256 value to look up a key to use for signature verification.

While these parameters are optional in both the JWT header and the JWK entries, a matching value in both uniquely identifies the public key required for verification.