IBM Security Verify

JSON Web Key Sets(JWKS) are an effective mechanism for a server to propagate signing keys. Consisting of an array of JSON encoded keys a JWKS may contain symmetric, public and private key material, however most commonly only public keys are included in a JWKS. In order to propagate these keys a JWKS is often exposed by HTTP, usually hosted by an entity responsible for issuing JSON Web Tokens(JWT). Using this hosted JWKS any entity may retrieve the JWKS document and subsequently verify that the JWT has come from the expected issuer. A hosted JWKS is usually referred to as a jwks_uri.

One of the most widely spread uses of a JWKS is in OpenID connect(OIDC), where the JWT issued by the OP is verified by the RP, using a key in the JWKS retrieved from the OP. However JWKs usage is not limited to just federation. When issuing a JWT to a back end server to propagate information or as a security assertion, that back end can make use of a jwks_uri to verify the assertion.

Consuming a hosted JWKS has a few direct benefits:

• Key roll over does not cause an outage on clients, as the JWKS is dynamically fetched, so as long as the JWKS is updated with the new keys. This also covers revocation.

• Deployment of applications does not require a certificate to be burnt into the application.

ISAM supports hosting and consuming a JWKS in a few different contexts, the focus of this post will be on the first jwks_uri, added in 9.0.2.0. As part of the work to add the JWT STS module, an appliance global jwks_uri was added. this JWKS is available at the runtime path /sps/jwks.  An example of fetching the appliance global JWKS, hosted on WebSEAL with a junction labelled /isam is:

​$ curl https://www.myidp.ibm.com/isam/sps/jwks 

{"keys": [
 {
  "kty": "RSA",
  "kid": "ms-rfkPI2IDQayYqlN7u5LRlmYnD0Mrxm69kBeQat98",
  "use": "sig",
  "n": "ryQICCl6NZ5gDKrnSztO3Hy8PEUcuyvg_ikC-VcIo2SFFSf18a3IMYldIugqqqZCs4_4uVW3sbdLs_6PfgdX7O9D22ZiFWHPYA2k2N744MNiCD1UE-tJyllUhSblK48bn-v1oZHCM0nYQ2NqUkvSj-hwUU3RiWl7x3D2s9wSdNt7XUtW05a_FXehsPSiJfKvHJJnGOX0BgTvkLnkAOTdOrUZ_wK69Dzu4IvrN4vs9Nes8vbwPa_ddZEzGR0cQMt0JBkhk9kU_qwqUseP1QRJ5I1jR4g8aYPL_ke9K35PxZWuDp3U0UPAZ3PjFAh-5T-fc7gzCs9dPzSHloruU-glFQ",
  "e": "AQAB"
 },
 {
  "kty": "EC",
  "kid": "LihhKJtczt7K5MMb8mLg-wwptsFTBXNEJzHKZdgh6QE",
  "use": "sig",
  "x": "DxukkdfnrOfRTk63ZFvhj39uBNOrONtEt0Bcbb2Wljc",
  "y": "33mJhmf3sR8Inv1jO0aMn71T6BXclz4rgUathn8OATk",
  "crv": "P-256"
 }
]}

The contents of the JWKS hosted on ISAM is controlled by two advanced configuration properties. These properties set which key-store should be used to expose keys for a particular usage. By default these are set to the default rt_profile_keys key-store, but can be changed to any key-store. All certificates in the trust store for a selected keys-store will be included in the returned JWKS.

This global JWKS is an essential part of using the ISAM STS to issue JWTs to third parties. As JWT junctions are more common giving a back-end server a way of verifying an assertion is key to building an environment. 

ISAM also exposes a JWKS found at /sps/oauth/oauth20/jwks/<OP name> when configuring an OpenID Connect OP. This JWKS was added in 9.0.4.0 as part of the OIDC extension to API protection.  This JWKS is scoped to the certificates relevant to a given OP. These certificates are selected as part of the OP configuration:

Similarly to the global JWKS, all certificates in the trust store for the selected key-store will be exposed in the JWKS. This allows an OP to change its signing certificate, while still having a JWKS which contains the old public key for verification. 

For a definition named "myOp", the request to fetch the JWKS is:

This covers the two ways which a JWKS is exposed on ISAM. One specifically for use in OIDC flows when ISAM is the OP and another for more general use by any consumer of JWTs issued by ISAM.