The signing certificate rollover feature offers a way to roll out a new signing certificate without removing the current one immediately. In short, the rollover process is:

1. The current (primary) signing certificate is going to expire.
2. You configure a new secondary certificate.
3. All connected Service Providers and Identity Providers update their systems to reflect the fact that there are now two signing certificates in use.
4. After a few days, the secondary certificate is promoted to be the primary certificate, and the former primary one is demoted to be the new secondary certificate.
5. After another few days, the demoted certificate is removed from Identify.

This process ensures that there is virtually no downtime caused by rolling out a new signing certificate.

Settings

To use the rollover feature, you must configure some settings in the System Setup correctly.

Secondary signing certificate

Firstly, you need to configure a secondary signing certificate:

Like the primary signing certificate, you can use certificates in either Windows certificate store or Azure Key Vault for the secondary signing certificate. After you have configured a secondary certificate correctly, Identify can:

• Generate metadata that has both the primary and the secondary certificates:

• Decrypt assertions (which are encrypted by either the primary or the secondary certificate) returned from Identity Providers.

Note that Identify always uses the primary certificate to sign messages that it sends to Service Providers and Identity Providers.

Certificate rollover settings

Now you can configure some other settings to specify the time stamp when the secondary certificate should be promoted, how many days to keep the demoted certificate in the system, and how often a background job needs to check if the promotion time stamp has come.

1. Promote the secondary certificate to be the primary one at (UTC): Specifies the specific timestamp when Identify will promote the secondary certificate to be the primary one. The actual promotion also depends on the Signing certificate rollover cron setting. For example, if the cron job causes the background process to wake up every 1 hour to check if the promotion timestamp (which is set to 0:00 AM) has come, the actual promotion action will happen somewhere between 0:00 AM and 1:00 AM.

   • Default value: none. When you configure a secondary certificate, you must also set a value for this setting.

   • The Promote the secondary certificate to be the primary one at (UTC) must be after the current time and must be before the primary signing certificate expires. It is recommended that you set the promotion time stamp to at least 5 days since the time you configure the secondary certificate and at least 2 days before the primary certificate expires.

2. Secondary certificate retention days: Specifies the number of days that Identify needs to retain the demoted secondary certificate.

   • Default value: 5. When you configure a secondary certificate, you must also set a value for this setting.

   • It is recommended that you set the Secondary certificate retention days to at least 5 days. A zero value means after Identify demotes the primary certificate to be the secondary one, it will remove the new secondary certificate immediately. However, please note that if expiration date of the demoted secondary certificate is less than 2 days from now, Identify will also remove it even if the number of retention days has not reached yet.

3. Signing certificate rollover cron: The cron expression to schedule the background job to promote the secondary signing certificate. The default value is every 1h (0 * * * *).

Rollover process

Dependent on the secondary signing certificate status and rollover settings, there is a corresponding background job to handle the secondary signing certificate: Promote and Remove the secondary signing certificate.

Promote the secondary signing certificate

When the secondary signing certificate is set, and it is not promoted yet, there is a background job running to check against the rollover settings to see if it is the time to promote the secondary signing certificate to the primary one. If yes, below is the list of changes that happen behind the scene:

• The primary and secondary signing certificates will be swapped.
• Decrypt data protection's encryption keys and re-encrypt them with the new primary signing certificate.
• The newly promoted primary certificate is marked as "promoted".

After finishing the promoting process, Identify re-initializes its internal data in memory and performs as normal. It also removes the promoting background job and starts the process to remove the demoted signing certificate:

1. The demoted certificate will be removed immediately if its expiration time is less than 2 days from now. Identify will remove it even if the number of retention days has not been reached yet.
2. Otherwise, Identify will register a new background job to remove the demoted signing certificate when the number of retention days is reached.

Limitation

• After finishing the promoting process, Identify re-initializes its internal data in memory and performs as normal. In a redundant setup, after a server finishes promoting a certificate, there can be a small window before the other server detects the promotion and updates its internal data in memory. If certificates are in the Windows certificate store, there will be no problem with that window. If the demoted signing certificate is in the Azure Key Vault, due to limitation of .NET API, your Identify instance may not be able to unprotect a new Data Protection encryption key stored in the CryptoKey table that is protected by the newly promoted certificate. However, this window is just a couple of minutes and the chance that a new encryption key is rolled out around that period is also small. Thus, downtime will be neglectable.