Documentation Center

Changing the signing certificate with key rollover

If you need to change the certificate that Access Management uses for signing tokens, we recommend you follow a key-rollover process.

About this task

Rather than completely replacing old signing certificates with new ones in one step, Access Management supports a key rollover process. With Access Management, this involves staged edits to the appsettings.json configuration file. The following are the essential steps, which are described in detail in the task that follows:

  1. First edit -- Add a new certificate first as a validation certificate.
  2. Wait for a period of time for clients to become aware of the certificate.
  3. Second edit -- Switch the new certificate from a validation certificate to the primary signing certificate, while making old one the validation certificate.
  4. Wait again until you are sure old certificates are no longer needed.
  5. Third edit -- Remove old certificate entirely when you are confident it is no longer needed.

Procedure

  1. Install the new certificate on the server in a location that is accessible to Access Management (to the user account under which the service runs).
  2. Go to the bin\ subfolder of the root folder where the Access Management service is installed.
  3. Find the Certificates section.
    The section contains two subsections:
    • Signing with a single signing certificate, which is the one currently used to sign all new tokens.
    • Validation with zero or more validation certificates, which may be used for validating new tokens while phasing in a new certificate or for validating tokens in old certificates that you are phasing out.
  4. In the Validation subsection, add a new entry with the Path set to the location of the new certificate. If the certificate is password protected, define the Password attribute as well.
    In the following example, we've called the new certificate "Incoming.pfx" and the old one "Outgoing.pfx":
    "Certificates": {
      "Signing": {
        "Path": "Certificates/Outgoing.pfx",
        "Password": "encaes256://CfDJ8AavlhI-H2JBmcauXoBe5KeMPLVSdPkte8GyJYb53jWWKJF5t3mdcgxtf-3I7s6-FrjbGX5tgstjYV05fRuXG7vE9CIWgeTHt_1i0rTItEeRoOv23OLq-4HWNwGDy5jtDg"
      },
      "Validation": [
        {
          "Path": "Certificates/Incoming.pfx",
          "Password": "encaes256://CfDJ8AavlhI-H2JBmcauXoBe5Kf-MROnxKlxfBxpoQOtK6BMhi8Eas1IKctRJEFW9-GOSW6Vh8a6nxlKPfNFmx_swU6DP7ePFpGLsPZbFbxy-tWTaUyyPj2NIkGIuxZHcrfL8w"
        }
      ]
    },
  5. Save and close appsettings.json.
  6. Wait for at least 24 hours so that all software clients have time to become aware of the new certificate.
  7. Open appsettings.json for editing once again.
  8. In the Certificates section, swap the positions of the old and new certificates. In other words, move the old certificate (outgoing) from Signing to Validation and the new (incoming) certificate from Validation to Signing.
    The following example shows the section after the switch:
    "Certificates": {
      "Signing": {
        "Path": "Certificates/Incoming.pfx",
        "Password": "encaes256://CfDJ8AavlhI-H2JBmcauXoBe5Kf-MROnxKlxfBxpoQOtK6BMhi8Eas1IKctRJEFW9-GOSW6Vh8a6nxlKPfNFmx_swU6DP7ePFpGLsPZbFbxy-tWTaUyyPj2NIkGIuxZHcrfL8w"
      },
      "Validation": [
        {
          "Path": "Certificates/Outgoing.pfx",
          "Password": "encaes256://CfDJ8AavlhI-H2JBmcauXoBe5KeMPLVSdPkte8GyJYb53jWWKJF5t3mdcgxtf-3I7s6-FrjbGX5tgstjYV05fRuXG7vE9CIWgeTHt_1i0rTItEeRoOv23OLq-4HWNwGDy5jtDg"
        }
      ]
    },
  9. Save and close appsettings.json.
  10. Restart the Access Management service.

What to do next

After some time, when you are confident the outgoing certificate is no longer needed, you can remove it entirely from the configuration. We recommend that you maintain validation certificates as long as they are still needed for validating longer-lived tokens.