Key Rotation

Only the primary Domino server can generate or manage keys, so you should enter the following console commands on the primary server. After keys are updated on the primary server, the changes will be replicated to all of the secondary servers.

• The oidcp show keys server console command can be used to view the keys used for signing and encyption by the Domino OIDC provider. The first character of the "type" column shows the state of the key -- (A)ctive, (P)ending, or (O)ld, and the second character shows whether the key is used for (e)xternal consumers to sign access tokens and ID tokens, or for (i)nternal consumption by the OIDC provider itself to sign and encrypt authorization codes and FailoverCookies.
• Active keys are actively being used to sign and encrypt new tokens. External pending keys are being published at the jwks_uri endpoint for clients to load and prepare to use, but are not being used yet. Old keys are no longer being actively used for signing and encryption, but external old keys are still published so clients and relying parties can use them to decrypt and verify previously generated tokens.
• Domino's jwks_uri endpoint now sends a Cache-Control header for one day (86400 seconds) by default, which aligns with common usage. These cache-control headers let clients know how long they can safely cache a set of published keys before they need to re-poll the jwks_uri endpoint and update their local cache. Administrators can use the OIDCP_JWKS_URI_CACHE_SEC notes.ini to change this value from the default of one day; the minimum value is 5 minutes (300 seconds) and the maximum value is one week. We recommend using only values of less than one day for testing purposes.
• Once per hour the Domino server checks for pending keys that are ready to be promoted into active use; when a pending key is promoted, the corresponding active key is "retired" and becomes an old key.
• Administrators can use the oidcp keys new <algorithm> server console command to create a new pending key of type <algorithm>. The algorithms are defined by JWS and are strings like "ES256" and "RS256"; the algorithms that are configured for use by your Domino OIDC provider can be determined with the oidcp show keys server console command. Pending keys will be published for a period of time before being activated and used to give clients time to update their local caches of signing keys. By default, this period of time will be identical to the Cache-Control time sent by the jwks_uri endpoint. This time can be increased but not decreased by adding an additional number to the end of the server console command, as in oidcp keys new <algorithm> <time> Longer times may be useful to accommodate applications that ignore jwks_uri endpoints' published cache-control headers.