SMART OIDC Keystore Definitions
Smile CDR issues signed JWTs for several purposes, including serving as Access Tokens according to RFC 9068, and as credentials for OAuth2 client authentication.
These tokens are signed using a cryptographic signature so that consuming resource providers can verify the authenticity of the token, and trust that it has not been modified. This signature uses a key that is stored within a JSON Web KeyStore (JWKS) file. These keystores provide a convenient way to manage key lifecycles.
Each keystore allows defining a set of keys either as json text, or via a Resource Path to a file that contains said keys.
Keystores can then be updated with new values to keep resources secure.
When saving a keyset, if multiple keys are provided, the first will be used as the primary key for signing all newly issued keysets.
NB: When updating keys, it's advisable to keep the previous primary key along with a newer key, so that existing issued tokens still remain valid until refresh.
Keystores can be created and managed within the Web Admin Console by accessing the Config OpenID Keystores menu. They can also be created and managed using the JSON Admin API using the OpenID Connect Keystores Endpoint.
A Keystore consists of a Keystore Id, and either JWKS Text (the raw JSON text of the JWKS to use) or a path to a file containing the JWKS.
The Keystore Id must consist only of alphanumeric characters, underscores, hyphens, and no white space (a-z, 0-9, _, -). It is not editable.
JWKS Text is the raw JSON text of the Key set. It can be provided, or left blank if a file path is provided instead.
JWKS file path is the path to the keyset. If defined, it will be given priority over raw text fields.
In order to generate OpenID Connect Access Tokens, this module requires a JSON Web Key Set (JWKS). This keyset is used to sign the tokens that are generated so that Resource Servers may verify and ultimately trust that they are legitimate.
Note that anyone who is in possession of the key used here is able to generate access tokens. For this reason it is very important that the key be safely stored.
There are a number of tools that can be used to generate JWKS files. One popular option is the MKJWK tool maintained by the MIT Kerberos and Internet Trust. The steps below show how to create a JWKS file using the online version of their tool; however, for increased security you may wish to download a copy and use it locally:
2048 (this is the default, which should be sufficient for most purposes)SigningRS256 should be sufficient)my-openid-token-signature)Once a key is generated, copy its value to the Signing JWKS textbox of an existing or new Keystore, or save it to a file in the Smile CDR classes directory. In the latter case,
the field should be prefixed with classpath as follows: classpath://[filename].
Note that a JWKS file will have contents similar to the following:
{
"keys": [
{
"kty": "RSA",
"d": "cSYq2di [trimmed]",
"e": "AQAB",
"use": "sig",
"kid": "test",
"alg": "RS512",
"n": "mVuJygm [trimmed]"
}
]
}