Sovrain
  1. Documentation
  2. Identity provider
  3. For admins

How-to guide

Rotate signing keys

Replace the key that signs OpenID Connect tokens or a SAML application's assertions without breaking sign-in.

This guide replaces a signing key, for example on a schedule or after a suspected leak. Rotation has two steps: you stage a next key so that applications learn it, then you make it the signing key.

Sovrain never rotates keys on its own. There are two kinds of keys:

  • one key set for all OpenID Connect applications of the organization, on the Signing keys page;
  • one key set per SAML application, on that application’s Identity Provider tab.

Warning: The key buttons act at once, without asking you to confirm.

Rotate the OpenID Connect key

OpenID Connect applications read Sovrain’s public keys from the JWKS address, so most of them pick up a new key on their own.

  1. On your home page, under Administration, select Open admin, then select Signing keys in the admin menu.
  2. Select Generate next key. A key with the status next appears. Sovrain publishes it at once but does not sign with it yet.
  3. Wait until your applications have refreshed their copy of the keys. How long that takes depends on each application.
  4. Select Promote on the next key.

The next key becomes active and signs every new token. The old key is retired but stays published for 65 minutes, so tokens it signed keep working until they expire.

To check an application afterwards, open it and select Test sign-in on its Access & diagnostics tab.

If you change your mind

Select Discard on the next key before promoting it. Only one next key can exist at a time.

If the active key must go now

Generate a next key, then select Retire on the active key. This promotes the next key in its place. Sovrain refuses to retire the only key.

Rotate a SAML application’s key

A SAML application trusts one certificate that you gave it. It must have the new certificate before Sovrain starts signing with the new key.

  1. In the admin menu, select Applications and open the SAML application.
  2. Open the Identity Provider tab.
  3. Under Signing keys, choose the algorithm for the new key and select Generate next key. Keep the algorithm the application already accepts unless you know it supports another. Do not choose RSA-2048 · SHA-1: generating it always fails.
  4. Give the application the new certificate:
    • if it reads Sovrain’s metadata URL, wait until it has refreshed it. The metadata lists the next key alongside the active one;
    • otherwise use Copy certificate or Download certificate on the next key and add it in the application, next to the current one if it allows two.
  5. Select More actions on the next key, then Promote.

The new key signs from now on. The old key is retired and leaves the metadata, so remove it from the application when you are done.

  1. On the Access & diagnostics tab, select Run test SSO, then sign in to the application to check.

If you change your mind

Select More actions, then Discard on the next key before promoting it.

If the active key must go now

Generate a next key, then select More actions, then Deactivate on the active key. This promotes the next key in its place, so the application rejects sign-ins until it has the new certificate.