How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I rollover certificates for an IdP or SP in AM 5.x or 6.x?

Last updated Apr 13, 2021

The purpose of this article is to provide information on performing key rollover for federation certificates (signing and encryption) in AM. This article includes steps for hosted and remote entity providers. It assumes you already have federation set up and working correctly, and your new certificates have already been imported into your AM keystore for hosted entity providers.


2 readers recommend this article

Overview

SAML signing and encryption uses AM's secret stores functionality as of AM 7. See Security Guide › Mapping and Rotating Secrets for further information on managing these secrets. 

Pre-AM 7

AM does not check for the certificate expiration date as discussed in FAQ: SAML certificate management in AM 5.x and 6.x (Q. Why isn't the SAML certificate expiration date checked?)

However, AM does support multiple signing keys to allow for key rollover; this means you can cutover to a new certificate when the current one is either revoked or expires.

This article covers the different ways you can perform key rollover:

Caution

These instructions assume you have already imported the new certificate in to the AM keystore for hosted entity providers, it has a different alias to the existing one and it is ready for use.

AM keystore

AM uses a JCEKS keystore as its default keystore. The default location is: /path/to/openAM/keystore.jceks. You can change this by navigating to: Configure > Server Defaults > Security > Key Store > Keystore File.

Note

It is recommended that you make a backup of your keystore.jceks.keypass and .storepass files before making any changes.

Testing federation

Throughout these procedures, you can verify federation is working with updated metadata files using the following calls to initiate the SAML flow:

  • SP initiated login URL: http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam
  • IdP initiated login URL: http://idp.acme.com:8080/openam/idpSSOinit.jsp?metaAlias=/idp&spEntityID=http%3A%2F%2Fsp.example.com%3A8080%2Fopenam

Replace the example FQDNs and port numbers with the appropriate values for your IdP and SP.

Performing key rollover for hosted entity providers (console)

You can perform key rollover for hosted entity providers via the console as follows:

  1. Navigate to:
    • AM 6.x console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Provider Name] > Assertion Content > Signing and Encryption > Certificate Aliases.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Provider Name] > Assertion Content > Signing and Encryption > Certificate Aliases.
  2. Add a new alias to the list of Signing and/or Encryption aliases. AM uses the first certificate listed.
  3. Export the updated metadata - you can export it via the browser, a curl command or ssoadm as detailed in How do I export and import SAML2 metadata in AM (All versions)?
  4. Provide the updated metadata to the remote SP or IdP.
  5. Remove the original alias from the list of Signing and/or Encryption aliases at the point you want to rollover to the new certificate.
  6. Export the updated metadata.
  7. Provide the updated metadata to the remote SP or IdP.

See SAML v2.0 Guide › Reference › Assertion Content (IdP) and SAML v2.0 Guide › Reference › Assertion Content (SP) for further information on certificate aliases used for signing keys.

Performing key rollover for remote entity providers (console)

You can perform key rollover for remote entity providers via the console as follows:

  1. Receive the first updated metadata file from the entity provider. This file will contain both the old and new aliases.
  2. Remove the remote entity provider configuration before importing the modified metadata files:
    • AM 6.x console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, select the check box next to the entity provider you want to delete and click Delete.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers, select the check box next to the entity provider you want to delete and click Delete.
  3. Import the received metadata:
    • AM 6.x console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, click Import Entity, specify the URLs of the metadata files and click OK.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers, click Import Entity, specify the URLs of the metadata files and click OK.
  4. Verify federation is still working with the updated metadata file.
  5. Receive the second updated metadata file from the entity provider containing the new alias.
  6. Remove the remote entity provider configuration before importing the modified metadata files:
    • AM 6.x console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, select the check box next to the entity provider you want to delete and click Delete.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers, select the check box next to the entity provider you want to delete and click Delete.
  7. Import the received metadata:
    • AM 6.x console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, click Import Entity, specify the URLs of the metadata files and click OK.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers, click Import Entity, specify the URLs of the metadata files and click OK.
  8. Verify federation is still working with the updated metadata file.

Performing key rollover for hosted IdPs (ssoadm)

Note

This example demonstrates updating the IdP's signing certificate. If you want to update the encryption certificate, you should use the -g option instead of the -b option in steps 1 and 4.

You can perform a key rollover for a hosted IdP using ssoadm as demonstrated by this example process where the existing signing certificate alias is called oldCertIdP and the new alias is called newCertIdP: 

  1. Update the hosted IdP's metadata to include the new alias (notice that you must specify both the existing and new aliases to prevent the new alias overwriting the old alias). For example: $ ./ssoadm update-entity-keyinfo -y http://idp.acme.com:8080/openam -u amadmin -f pwd.txt -e / -b oldCertIdP newCertIdP -c saml2 Update entity keyinfo succeeded : http://idp.acme.com:8080/openam
  2. Export the updated metadata, for example: $ ./ssoadm export-entity -y http://idp.acme.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2 -m IdPmetadatafile.xml -x IdPextendedfile.xml Entity descriptor was exported to file, IdPmetadatafile.xml.
  3. Provide the updated metadata to the remote SP.
  4. Update the hosted IdP's metadata to remove the original alias at the point you want to rollover to the new certificate (notice you use the same command as step 1 but only specify the new alias). For example: $ ./ssoadm update-entity-keyinfo -y http://idp.acme.com:8080/openam -u amadmin -f pwd.txt -e / -b newCertIdP -c saml2 Update entity keyinfo succeeded : http://idp.acme.com:8080/openam
  5. Export the updated metadata, for example: $ ./ssoadm export-entity -y http://idp.acme.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2 -m IdPmetadatafile2.xml -x IdPextendedfile2.xml Entity descriptor was exported to file, IdPmetadatafile2.xml.
  6. Provide the updated metadata to the remote SP.

Performing key rollover for hosted SPs (ssoadm)

Note

This example demonstrates updating the SP's signing certificate. If you want to update the encryption certificate, you should use the -r option instead of the -a option in steps 1 and 4.

You can perform a key rollover for a hosted SP using ssoadm as demonstrated by this example process where the existing signing certificate alias is called oldCertSP and the new alias is called newCertSP: 

  1. Update the hosted SP's metadata to include the new alias (notice that you must specify both the existing and new aliases to prevent the new alias overwriting the old alias). For example: $ ./ssoadm update-entity-keyinfo -y http://sp.example.com:8080/openam -u amadmin -f pwd.txt -e / -a oldCertSP newCertSP -c saml2 Update entity keyinfo succeeded : http://sp.example.com:8080/openam
  2. Export the updated metadata, for example: $ ./ssoadm export-entity -y http://sp.example.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2 -m SPmetadatafile.xml -x SPextendedfile.xml Entity descriptor was exported to file, SPmetadatafile.xml.
  3. Provide the updated metadata to the remote IdP.
  4. Update the hosted SP's metadata to remove the original alias at the point you want to rollover to the new certificate (notice you use the same command as step 1 but only specify the new alias). For example: $ ./ssoadm update-entity-keyinfo -y http://sp.example.com:8080/openam -u amadmin -f pwd.txt -e / -a newCertSP -c saml2 Update entity keyinfo succeeded : http://sp.example.com:8080/openam
  5. Export the updated metadata, for example: $ ./ssoadm export-entity -y http://sp.example.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2 -m SPmetadatafile2.xml -x SPextendedfile2.xml Entity descriptor was exported to file, SPmetadatafile2.xml.
  6. Provide the updated metadata to the remote IdP.

Performing key rollover for remote IdPs (ssoadm)

You can perform a key rollover for a remote IdP using ssoadm as demonstrated by this example process: 

  1. Receive the first updated metadata file from the IdP. This file will contain both the old and new aliases.
  2. Remove the remote IdP configuration before importing the modified metadata files, for example: $ ./ssoadm delete-entity -y http://idp.acme.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2 Descriptor was deleted for entity, http://idp.acme.com:8080/openam.
  3. Import the received metadata, for example: $ ./ssoadm import-entity -u amadmin -f pwd.txt -e / -c saml2 -t cot -m ../IdPmetadatafile.xml Import file, ../IdPmetadatafile.xml
  4. Verify federation is still working with the updated metadata file.
  5. Receive the second updated metadata file from the IdP containing the new alias.
  6. Remove the remote IdP configuration before importing the modified metadata files, for example: $ ./ssoadm delete-entity -y http://idp.acme.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2 Descriptor was deleted for entity, http://idp.acme.com:8080/openam.
  7. Import the received metadata, for example: $ ./ssoadm import-entity -u amadmin -f pwd.txt -e / -c saml2 -t cot -m ../IdPmetadatafile2.xml Import file, ../IdPmetadatafile2.xml
  8. Verify federation is still working with the updated metadata file.
Note

To minimize downtime, you can use the ssoadm do-batch command for steps 6 and 7 to do the delete and add in quick succession. See How do I make batch changes using ssoadm in AM (All versions)? for further information.

Performing key rollover for remote SPs (ssoadm)

You can perform a key rollover for a remote SP using ssoadm as demonstrated by this example process: 

  1. Receive the first updated metadata file from the SP. This file will contain both the old and new aliases.
  2. Remove the remote SP configuration before importing the modified metadata files, for example: $ ./ssoadm delete-entity -y http://sp.example.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2 Descriptor was deleted for entity, http://sp.example.com:8080/openam.
  3. Import the received metadata, for example: $ ./ssoadm import-entity -u amadmin -f pwd.txt -e / -c saml2 -t cot -m ../SPmetadatafile.xml Import file, ../SPmetadatafile.xml
  4. Verify federation is still working with the updated metadata file.
  5. Receive the second updated metadata file from the SP containing the new alias.
  6. Remove the remote SP configuration before importing the modified metadata files, for example: $ ./ssoadm delete-entity -y http://sp.example.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2 Descriptor was deleted for entity, http://sp.example.com:8080/openam.
  7. Import the received metadata, for example: $ ./ssoadm import-entity -u amadmin -f pwd.txt -e / -c saml2 -t cot -m ../SPmetadatafile2.xml Import file, ../SPmetadatafile2.xml
  8. Verify federation is still working with the updated metadata file.
Note

To minimize downtime, you can use the ssoadm do-batch command for steps 6 and 7 to do the delete and add in quick succession. See How do I make batch changes using ssoadm in AM (All versions)? for further information.

See Also

How do I export and import SAML2 metadata in AM (All versions)?

How do I renew expired certificates for a hosted IdP or SP in AM 5.x or 6.x?

How do I renew expired certificates for a remote IdP or SP in AM (All versions)?

FAQ: SAML certificate management in AM 5.x and 6.x

SAML Federation in AM

SAML v2.0 Guide

Setup and Maintenance Guide › Setting Up Keys and Keystores

Related Training

N/A

Related Issue Tracker IDs

N/A


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