How To
ForgeRock Identity Cloud

How do I rotate SAML2 certificates in Identity Cloud using ESVs?

Last updated Apr 14, 2022

The purpose of this article is to provide information on rotating SAML2 certificates in ForgeRock Identity Cloud using Environment secrets and variables (ESVs). Many deployments issue SAML2 certificates for a limited period, which means they need to be rotated periodically.


Overview

Identity Cloud provides functionality that allows you to store signing and encryption keys in ESV secrets, which can then be mapped to secret IDs. See Use ESVs for Signing and Encryption Keys for further information. You can use this functionality to rotate SAML2 certificates as described in this article, that is, start signing tokens with a new key, while still accepting tokens signed with an old key. 

Caution

When you update a secret, the new secret value is used immediately.

In terms of rotating SAML2 certificates, as soon as you update the secret with the new certificate value, the new certificate is used for signing or encryption. In practical terms, this means you need to coordinate updating the secret with the remote entity provider. If the remote entity provider hasn't imported the updated metadata, federation will fail because you are using different certificates.

SAML2 certificates

The following certificates are used in SAML2 flows, where Identity Cloud is the hosted entity provider and a third party is the remote entity provider:

Certificates Identity Cloud role Third-party role Identity Cloud usage Third-party usage
Hosted IdP signing certificate Hosted IdP Remote SP Signs outbound SAML2 assertions Validates inbound signed SAML2 assertions
Hosted IdP encryption certificate Hosted IdP Remote SP Decrypts inbound encrypted SAML2 requests  Encrypts outbound SAML2 requests
Hosted SP signing certificate Hosted SP Remote IdP Signs outbound SAML2 requests Validates inbound signed SAML2 requests
Hosted SP encryption certificate Hosted SP Remote IdP Decrypts inbound SAML2 assertions Encrypts outbound SAML2 assertions

These are the certificates that can be rotated per this article, because SAML2 secrets are only applicable to hosted entity providers.

The Remote equivalents of these certificates are derived from the SAML2 metadata provided by the third party and are outside the scope of this article.

Steps involved

  1. Generate a CA certificate for signing
  2. Create initial SAML2 signing or encryption certificate
  3. Create ESV for certificate and apply to entity provider in Identity Cloud
  4. Test initial certificate works
  5. Create new SAML2 signing or encryption certificate for rotation
  6. Update ESV with new certificate
  7. Test new certificate works

Prerequisites

  • You have a working Identity Cloud tenant.
  • You have already set up the necessary entity providers in Identity Cloud and have a working SAML2 federation.

Generating a CA certificate for signing

You need to generate a CA certificate before you start. This certificate is then used to sign all the subsequent SAML2 signing and/or encryption certificates.

  1. Generate a new private key for the CA certificate. For example:$ openssl genrsa -out <CA-key.pem> 4096
  2. Generate the CA certificate using the private key you created. For example:$ openssl req -new -x509 -key <CA-key.pem> -out <CA-cert.pem> -days 365 -subj /CN=idcloud-ca

Creating initial SAML2 signing or encryption certificate

  1. Generate a new private key. For example:$ openssl genrsa -out <key1.pem> 4096
  2. Create a certificate signing request (CSR) using your private key. For example:$ openssl req -new -key <key1.pem> -out <csr1.csr> -days 365 -subj /CN=idcloud-cert-1
  3. Generate a certificate by signing the CSR using the CA key/certificate. For example:$ openssl x509 -req -in <csr1.csr> -CA <CA-cert.pem> -CAkey <CA-key.pem> -set_serial 01 -days 365 -out <cert1.pem>
  4. Combine the private key and certificate you created in steps 1 and 3 into a single certificate file. For example:$ cat <key1.pem> <cert1.pem> > <key-cert1.pem>
  5. Base64 encode the resulting certificate file. For example:$ base64 -i <key-cert1.pem> -o <key-cert1-base64.pem>
  6. Copy the contents of the base64 encoded pem file as you will need to send it when you create the ESV via REST. You can use a text editor such as vi to view the contents of the pem file.

Creating ESV for certificate and applying to entity provider in Identity Cloud

  1. Create a new ESV for the certificate using the REST API; you can choose any <esv-name> providing it complies with the ESV API naming convention. For example:$ curl \ --location -g --request PUT 'https://<tenant-name>.forgeblocks.com/environment/secrets/<esv-name>' \ --header 'authorization: Bearer <access-token>' \ --header 'content-type: application/json' \ --header 'Accept-API-Version: resource=1.0' \ --data-raw '{   "encoding": "pem",    "valueBase64": "<base64 encoded certificate from key-cert1-base64.pem>",    "useInPlaceholders": false,    "description": "<key description, for example: SAML signing or SAML encryption>" }'
  2. Verify the changes have been applied in Identity Cloud:
    1. In the Identity Cloud admin UI, go to Tenant Settings > Global Settings > Environment Secrets & Variables.
    2. Click the Secrets tab and check your secret is there.
  1. In the Identity Cloud admin UI, go to Native Consoles > Access Management > Applications > Federation > Entity Providers and click the name of your entity provider.
  2. On the Assertion Content tab, go to Secret ID And Algorithms and enter the ID of the secret (for example, idpcloud) you want to use for this entity provider in the Secret ID Identifier field.
  1. Scroll down and click Save Changes.
  2. In the Identity Cloud admin UI, go to Native Consoles > Access Management > Secret Stores > ESV > Mappings and click Add Mapping.
  3. Select the applicable secret from the Secret ID field. This will be in the format am.applications.federation.entity.providers.saml2.<secretID>.<purpose>, where <secretID> is the ID you entered for the entity provider in step 4 and <purpose> is either signing or encryption, depending on what you are using your certificate for.

For example, if your secret ID was idpcloud and you are using your certificate for signing, you would select am.applications.federation.entity.providers.saml2.idpcloud.signing in this field.

  1. Enter the name of the ESV you created in step 1 in the aliases field and click Add.

For example, if you did a PUT to the environment/secrets/esv-saml-idp endpoint, your ESV would be called esv-saml-idp. 

  1. Click Create.

Testing initial certificate works

  1. Export the entity provider metadata and exchange it with the remote entity provider. See How do I export and import SAML2 metadata in Identity Cloud? for further information.
  2. Test your SAML2 federation flow using the URL or journey you normally use.
  3. Verify the certificate in the SAML2 assertion corresponds to the newly created certificate. There are third-party tools you can use, for example, CSR Decoder and Certificate Decoder.

Creating new SAML2 signing or encryption certificate for rotation

  1. Generate a new private key. For example:$ openssl genrsa -out <key2.pem> 4096
  2. Create a certificate signing request (CSR) using your private key. For example:$ openssl req -new -key <key2.pem> -out <csr2.csr> -days 365 -subj /CN=idcloud-cert-2
  3. Generate a certificate by signing the CSR using the CA key/certificate. For example:$ openssl x509 -req -in <csr2.csr> -CA <CA-cert.pem> -CAkey <CA-key.pem> -set_serial 01 -days 365 -out <cert2.pem>
  4. Combine the private key and certificate you created in steps 1 and 3 into a single certificate file. For example:$ cat <key2.pem> <cert2.pem> > <key-cert2.pem>
  5. Base64 encode the resulting certificate file. For example:$ base64 -i <key-cert2.pem> -o <key-cert2-base64.pem>
  6. Copy the contents of the base64 encoded pem file as you will need to send it when you update the ESV via REST. You can use a text editor such as vi to view the contents of the pem file.

Updating ESV with new certificate

  1. Update the ESV you created previously with the new certificate using the REST API. For example:$ curl \ --location -g --request POST 'https://<tenant-name>.forgeblocks.com/environment/secrets/<esv-name>/versions?_action=create' \ --header 'authorization: Bearer <access-token>' \ --header 'content-type: application/json' \ --header 'Accept-API-Version: resource=1.0' \ --data-raw '{   "valueBase64": "<base64 encoded certificate from key-cert2-base64.pem>" }'

This curl command adds a new secret version, which is enabled immediately; you do not need to make any changes to the entity provider or secret mapping.

  1. Verify the changes have been applied in Identity Cloud:
    1. In the Identity Cloud admin UI, go to Tenant Settings > Global Settings > Environment Secrets & Variables and click the Secrets tab.
    2. Click Update against the ESV you updated and verify a new version has been created.

You can disable the previous version of the secret in this window when you are ready.

Testing new certificate works

  1. Export the entity provider metadata and exchange it with the remote entity provider. See How do I export and import SAML2 metadata in Identity Cloud? for further information. If the previous secret is not disabled, the metadata will show both signing or encryption certificates.
  2. Test your SAML2 federation flow again using the URL or journey you normally use.
  3. Verify the certificate in the SAML2 assertion corresponds to the rotated certificate. There are third-party tools you can use, for example, CSR Decoder and Certificate Decoder.

See Also

Use ESVs for Signing and Encryption Keys

Configure ESV using API

Environment Secrets and Variables (ESVs)

Test SAML2 SSO using JSP flows


Copyright and Trademarks Copyright © 2022 ForgeRock, all rights reserved.