Prerequisites for Installation

Apart from the prerequisites listed here for Orchestrator installation, Identity Server needs valid certificates.

Certificates

Identity Server requires the following valid certificates:

• A certificate for the HTTPS protocol.

• A certificate used to sign the tokens generated by the Identity Server.The certificate is used for signing OpenID access tokens that are used for user identification via browser and for service-to-service communication between Orchestrator and Identity Server. Click here for more details about OpenID Connect.

  Important:

  You can use a maximum key length of 4096 bits for signing certificates. We highly recommend you to use a key length of at least 512 bits (64 bytes) as a best practice.

  Important:

  For security reasons, the certificate used by the Identity Server needs to:

  • have a public key on 2048 bits
  • have a private key accessible by the AppPool user,
  • be in its validity period (not expired).

  The certificate's location is set in Identity Server's configuration file appsettings.Production.json, in the Signing Credential section.

Certificate Rotation

You can employ certificate rotation to avoid the risk of certificate expiration and, implicitly, an Identity Server outage. This method entails maintaining two certificates and rotating them periodically. Note, however, that you can only use one signing key at a time.

To initiate the certificate rotation process, take the following steps:

1. Specify the initial certificate's Name, Location, and NameType using the StoreLocation parameter in appsettings.Production.json’s SigningCredentialSettings section. Note that this is the default signing key.
2. Specify the second certificate's Name, Location, and NameType using the ValidationKeys parameter in the same section of the appsettings.Production.json file. Make sure you complete this step before the rotation date.
3. At this stage, the second certificate is published using the identity/.well-known/openid-configuration/jwks endpoint. This ensures everyone has enough time to update their cached discovery document.
4. At rotation time, switch the certificates and restart Identity Server. The new certificate can now be used for signing whereas the previous one continues to be available for validation purposes for as long as you need.
5. The previous certificate can be safely removed from the configuration after 48 hours.

In the following example, SigningCredential references the currently used certificate, whereas ValidationKeys references the newly published validation key.

"SigningCredentialSettings": {
      "StoreLocation": {
        "Name": "2816a67bc34496ca0acabbe04eb149b88ade0684",
        "Location": "LocalMachine",
        "NameType" : "Thumbprint",
        "ValidationKeys": [
            {
            "Name": "2cde6c443f0147c6258a6fe2203e71a997bfcd44",
            "Location": "LocalMachine",
            "NameType" : "Thumbprint"
            }
        ]
      }
    }

Important: If you are using AI Center, make sure to redeploy it whenever updating the Identity Server certificate.

Impact on the AppSettings.Production.json encryption

Rotating the certificates may impact the encryption of AppSetting.Production.json data.

To rotate signing certificates, while keeping the settings encryption safe, proceed as follows:

1. Decrypt the AppSettings.Production.json file.
2. Update the signing certificate in the AppSettings.Production.json file.
3. Re-encrypt the AppSettings.Production.json file.
4. Restart Identity Server.