Written by Simon Moffat
May 2017
Note
Instructions for configuring Certificate rollover for SAML2 federation in Access Management are available in our Docs and Knowledge base for all versions of Access Management (relevant URLs are provided below for further reference).
This article includes screenshots reflecting legacy versions of Access Management; however, the principles and instructions of the extended information still apply through AM 6.x.
AM 7 and later, SAML2 signing and encryption use AM’s secret stores. See How do I rotate SAML2 certificates in AM 7.x using secrets? for further information on managing these secrets.
--- ### Overview ForgeRock AM 5.0 introduced [Amster](https://backstage.forgerock.com/docs/amster/5/release-notes), a lightweight command line tool and interactive shell that allows for the automation of many management and configuration tasks.A common task often associated with SAML2 identity provider configs, is the updating of certificates that are used for signing and the possible encryption of assertions. A feature added in OpenAM 13, was the ability to have multiple certificates within an IDP config. This is useful to overcome the age-old challenge of how to handle certificate expiration. An invalid cert can brake integrations with service providers. The process to remove, then add a new certificate would require any entities within the circle of trust to retrieve new metadata into their configs – and thus create downtime, so the timing of this is often an issue. The ability to have multiple certificates in the config, would allow service providers to pull down meta data at a known date, instead of specifically when certificates expired.
Here we see the basic admin view of the IDP config…showing the list of certs available. These certs are stored in the JCEKS keystore in AM5.0 (previously the JKS keystore).
So the config contains am1 and am2 certs – an export of the meta data (from the …/openam/saml2/jsp/exportmetadata.jsp?entityid=idp endpoint) will list both certs that could be used for signing:
The first certificate listed in the config, is the one that is used to sign. When that expires, just remove from the list and the second certificate is then used. As the service provider already has both certs in their originally downloaded metadata, there should be no break in service.
Anyway….back to automation. Amster can manage the the SAML2 entities, either via the shell or script. This allows admins to operationally create, edit and update entities…and a regular task could be to add new certificates to the IDP list as necessary.
To do this, you can create a basic bash script that utilizes Amster to read, edit then re-import the entity as a JSON wrapped XML object.
For more information on IDP certificate management, see the docs here.
Further Reading
Docs
Knowledge Base