Ubisecure SSO supports rotation of signing and encryption keys. Signing keys are used to create and validate message signatures, for example, SAML assertions and OpenID Connect messages such as ID tokens and request objects. In addition to signing, Ubisecure SSO can use message encryption to protect data during transmission. These keys can be controlled using the Management API.
In addition to Ubisecure SSO signing and encryption keys, client applications (i.e. service providers) integrated to Ubisecure SSO may have their own keys which are not discussed in this document.
Why rotate keys?
Rotating signing and encryption keys is recommended security practice. For example, in asymmetric cryptography, having a key rotation strategy in place means an unlikely compromised key attack can be mitigated quickly. In addition, regular rotation of signing keys ensures that even with the required amount of computation to compromise a key, potential attackers will not be able to find the private key in time before a key rotation event occurs.
Initially when Ubisecure SSO is installed it must have at least one signing key. This key is automatically generated during the installation process to System/ServerKeyContainer site with name key-initial. As mentioned earlier, keys can be managed using the Management API. There is no current support for automatic key creation and association process thus keys need to be created and associated through the API. Ubisecure SSO will still automatically rotate keys according to the keys specifications in the system.
Ubisecure SSO uses only one signing and encryption key at a time. These keys can be the same key or two distinct keys. The key being used for signing or encryption is called theactive key.
SAML and OpenID Connect Provider metadata can contain multiple signing keys at the same time, but only one active encryption key. These signing keys can include previous, active and future keys. In order to allow smooth transition, your applications should be able to use all of the keys published in the Ubisecure SSO metadata.
A valid key is a key which fulfils the following criteria:
The key is enabled
The key's notBefore date and time is not set or is less than or equal to the the current time
The key's notOnOrAfter date and time is not set or is greater than the current time
The key is associated to a site
A valid key is not yet in use but is available in the metadata. If there are multiple valid keys available, the active key will be the key whose
notBefore is closest to the current time
notOnOrAfter is furthest from the current time
name is lexicographically the smallest value (e.g. key1 is smaller than key2)
Changes since version 8.9.0 to OpenID Connect authentication method
Since Ubisecure SSO 8.9.0 the OpenID Connect authentication method related metadata uses jwks_uri instead of jwks. This is to better support key rotation use cases.
If you still have the requirement to use OIDC metadata with explicit jwks, use the SSO OIDC Provider metadata to obtain the JWK Set and edit the authentication method related metadata manually.
Key rotation example
In this basic example we consider a simple signing key rotation. Assuming that the system has an active key called initial-sig-key. We can see it in the SSO metadata:
Now, assuming today's date is 2021-10-20, let's setup a new signing key called sig-key1 that will be active on 2021-10-27. After that let's make sure the initial-sig-key is deactivated by defining the expiration time for it:
It is essential to understand the impact before rotating keys.
Ubisecure suggests testing key rotation in a non-production environment first and verify that application integrations and external authentication methods work as expected. After verifying that the process works, you can perform the same process in production.
External authentication methods
External authentication methods such as SAML Authentication Provider, OpenID Connect, SPI OpenID Connect CIBA are affected when rotating Ubisecure SSO's keys. You may need to reconfigure the authentication provider if it is not able to dynamically discover keys from Ubisecure SSO, for example, by using the OpenID Connect Provider configuration and further, the JSON Web Key Set.
When rotating keys in Ubisecure SSO, all applications integrations are typically impacted. If an application can dynamically discover keys using the OpenID Connect Provider configuration and further, the JSON Web Key Set the integrations will typically work without changes. However, if your application uses WS-Federation or SAML2 you may need to reconfigure those applications and update Ubisecure SSO's changed metadata in those applications.
Use certified client libraries
Using certified OpenID Connect client libraries and frameworks guarantees that applications can handle the scenario where the OpenID Provider rotates its keys.