When the SSO signing and encryption key needs to be updated, it's performed in three distinct steps in order to enable a rollover period for existing integrations to update their metadata.
In principle, the procedure follows the following steps:
- Start rollover period: Include the new certificate in the SSO metadata and deliver the updated metadata to all SAML SP application integrations.
- Change the SSO signing and encryption key.
- All identity provider integrations as well as non-SAML SP application integrations should be updated now, since the key rollover described here works only with SAML SP integrations
- Inform all integrations to retrieve the updated the SSO metadata with only the new key.
All integrations encrypting some data to SSO with SSO's encryption key. Once the key is updated (i.e. the second step is finished, but 2.a step is not finished), SSO will not be able to decrypt their encrypted data before the final metadata with only the new key is updated to those integrations.
These integrations include at least:
- SAML2 Service Providers, that include encrypted subject in AuthnRequests or LogoutRequests.
- Ubisecure SAML SP component includes no subject in either element, unless explicitly done so in an AuthnRequestEventListener implemented by the integrator.
- All identity providers
To enable key rollover in these cases, Ubisecure SSO needs to be able to use two encryption keys simultaneously. This is a new feature and you can contact our support to enquire it's availability in future versions.
Step-by-step guide for Windows
All commands are expected to be run in a PowerShell console.
java requires Java Runtime Environment to be installed.
Preliminary steps to prepare the PowerShell session.
Change the current folder to ubilogin folder.
Steps for creating the new key in SSO config file and adding it to the SSO SAML2 metadata.
Create a new key pair in the SSO config file. Keysize can be set as desired.
Export the public key from the SSO config file in XML format in a separate XML-file.
Download the SAML2 metadata from SSO.
Add the public key in a XML form into the metadata.xml.
- The created metadata.xml now contains the new certificate and can be delivered to all integrations (applications and identity providers) for the duration of the rollover period.
Steps for updating the SSO signing and encryption key
Ensure that the new win32.config is valid with ubikt.
Expected output is something like:
Subject: CN=Ubilogin, DC=test
Issuer: CN=Ubilogin, DC=test
Stop SSO Server.
Run SSO setup script.
Update SSO Tomcat.
Import secrets.ldif to Ubilogin Directory.
Start SSO Server.
- SSO metadata with only the new certificate is now available in the SSO SAML2 metadata URL https://sso.example.com:8443/uas/saml2/metadata.xml to be fetched by integrations.