Updating SAML Certificate on HCP Terraform

This article explains how to update the SAML certificate for an organization in HCP Terraform with SSO enabled.

Pre-requisites

• Ensure you're logged in with an owner account using username and password (not via SSO) when you disable SSO or your session will expire as soon as you disable SSO.

• You must be part of the Owners team in the organization.

• This process should be performed during a planned maintenance window, as SSO must be temporarily disabled and only owners will retain access during that time.

   

Steps to Update the SAML Certificate

1. Log in to HCP Terraform using your owner account credentials (username and password).

2. Navigate to the Organization that has SSO enabled.

3. Go to:
   Settings → SSO:
   

4. On the SSO settings page, click Disable SSO.

When disabling SSO, you will see a warning similar to:

“Disabling SAML will retain access for 5 users. Access for 40 users with SSO-only password-less accounts will be revoked.”

What this means:

• SSO is configured at the organization level. Users with SSO-only (password-less) accounts will temporarily lose access when SSO is disabled.

• The users with the retained access are typically the number of organization owners with username/password logins.

• Once SSO is re-enabled, access will be restored automatically based on the configuration in your Identity Provider (IdP).

Updating the Certificate

5. After SSO is disabled, click Edit Settings.

6. Generate a new X.509 certificate from your IdP (Identity Provider).

7. Paste the certificate in the X.509 Certificate field in the following format:

   -----BEGIN CERTIFICATE-----
   MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7Hgyd9Jv7ulJbB1Bv7hQ
   ...
   R6t8kikpQRy9sqZy5jl8A=
   -----END CERTIFICATE-----
   

   

8. Save the changes.

9. Once the new certificate is updated, re-enable SSO from the same settings page.

Conclusion

Since user management is handled through your IDP provider, and there are no changes to the existing user mappings, updating the certificate is a seamless process. Once SSO is re-enabled, all users assigned in your HCP Terraform SSO application will automatically regain access to HCP Terraform.