Introduction
This article explains the correct procedure for rotating Identity Provider (IDP) SAML signing certificates in Terraform Enterprise to ensure a seamless transition without causing login failures.
Expected Outcome
You will successfully replace an expiring SAML certificate with a new one, allowing both the old and new certificates to be valid temporarily during the transition period.
Prerequisites
- An operational Terraform Enterprise instance.
- SAML single sign-on (SSO) is enabled and configured.
- You have access to the new IDP certificate content.
Use Case
This procedure is necessary when your IDP's SAML signing certificate is approaching its expiration date and needs to be replaced.
Procedure
Follow these steps in order to avoid configuration errors.
- Navigate to the SAML settings page in the Terraform Enterprise UI at
https://<TFE_HOSTNAME>/app/admin/saml. -
In the Identity Provider Settings section, check for the presence of the Revoke old IDP certificate button.
Warning: If the Revoke old IDP certificate button is visible, you must click it before adding your new certificate. Failure to do so will cause your current certificate to be discarded, leading to login failures with the error
CONFIGURATION ERROR: Invalid Signature on SAML Response. When you add a new certificate, the current one is moved to the "old" slot. If the "old" slot is already occupied, the current certificate is lost. - After ensuring the old certificate slot is empty (the Revoke old IDP certificate button is no longer visible), paste the contents of your new IDP certificate into the IDP certificate text box.
- Click Save.
After saving, your previous certificate is now stored as the "old IDP certificate," and the new certificate is active. This allows your identity provider to use either certificate during the transition, preventing service disruption.