Introduction

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.

Feature description

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 the active 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:

HTTP GET /uas/oauth2/metadata.jwks

{
    "keys": [
        {
            "use": "sig",
            "kid": "initial-sig-key",
            "kty": "RSA",
            "n": "... redacted ...",
            "e": "AQAB"
        }
    ]
}

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:

Create a new signing key and associate it

PUT /sso-api/credential/System/ServerKeyContainer/sig-key1 HTTP/1.1
Host: sso.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Bearer ... redacted ...

kty=RSA&kid=sig-key1&enabled=true&use=sig&notBefore=2021-10-27


PUT /sso-api/server/$link/credential/System/ServerKeyContainer/sig-key1 HTTP/1.1
Host: sso.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Bearer ... redacted ...

Set current key expiration

PUT /sso-api/credential/System/ServerKeyContainer/initial-sig-key HTTP/1.1
Host: localhost:8443
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Bearer ... redacted ...

kty=RSA&notOnOrAfter=2021-10-27

When looking at the metadata at this point we have two signing keys published:

HTTP GET /uas/oauth2/metadata.jwks

{
    "keys": [
        {
            "use": "sig",
            "kid": "initial-sig-key",
            "kty": "RSA",
            "n": "... redacted ...",
            "e": "AQAB"
        },
        {
            "use": "sig",
            "kid": "sig-key1",
            "kty": "RSA",
            "n": "... redacted ...",
            "e": "AQAB"
        }
    ]
}

This makes sure the applications have time to prepare to the key rotation event that will occur 2021-10-27. After 2021-10-27 the metadata shows only the new signing key as follows:

HTTP GET /uas/oauth2/metadata.jwks

{
    "keys": [
        {
            "use": "sig",
            "kid": "sig-key1",
            "kty": "RSA",
            "n": "... redacted ...",
            "e": "AQAB"
        }
    ]
}

After this, key rotation has been successfully completed. It is safe to remove the old signing key shortly after the rotation event.

To recap the process, we did the following steps:

Create a new signing key that becomes active in 7 days. Clients are now able to see the key
Set the currently active signing key to expire in 7 days
Automatic rotation of keys happens on 2021-10-27 at 00:00 UTC time

Using a signed certificate

In this basic example we consider signing our certificate with Certification Authority (CA).

First get CSR (Certificate Signing Request) for existing key. Assuming that the system has an key called key1 we can obtain CSR for it:

GET /sso-api/credential/System/ServerKeyContainer/key1/$attribute/csr

Content-Type: application/pkcs10

-----BEGIN CERTIFICATE REQUEST-----
... redacted ...
-----END CERTIFICATE REQUEST-----

Response contains base64 encoded PKCS#10 value.

Next you need to sign this request on a CA. This process is out of the scope of this example.

You are going to need your signed certificate in PEM format for saving it to your credential key.

PUT /sso-api/credential/System/ServerKeyContainer/key1/$attribute/csr

Content-Type: application/pkix-cert

-----BEGIN CERTIFICATE-----
... redacted ...
-----END CERTIFICATE-----

Now the signed certificate can be linked to Server to be used in OAuth2 and SAML authentication.

More detailed information for API calls can be from Management API / Using Management API to manage keys.

Key rotation impact

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.

Applications

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.

Browser not supported