Problem
When setting up SAML Single Sign-On (SSO) in HCP Terraform, users may encounter a generic “failed” message after clicking the Test/Retest button during configuration. Additionally, testing the SAML configuration from the identity provider (IdP) may result in an error like:
Not Found
Sorry, the page /sso/saml/samlconf-nGMD7rkzxxxxxxxxxxxx/acs could not be found.
This error could mean one of two things:
· The resource doesn't exist
· The resource exists, but you do not have permission to access it
If someone has linked you to this resource, ensure that they have given you proper permissions to access it.
Cause
This error typically occurs when the X.509 Certificate used in the SAML configuration is missing, outdated, or not properly encoded. While the Entity ID and Assertion Consumer Service (ACS) URL might be correct, a mismatched or incorrect certificate can cause the service to reject SAML assertions, resulting in a failed configuration.
Solution
To resolve the issue, follow these steps to update the X.509 certificate:
Step 1: Obtain the Correct Certificate
-
In your identity provider (e.g., Microsoft Entra ID / Azure AD), navigate to the Single Sign-On settings.
-
Locate the SAML Signing Certificate section.
-
Download the certificate in Base64 format.
Step 2: Update Settings in HCP Terraform
-
Log in to HCP Terraform.
-
Go to Organization Settings > SSO.
-
Click Edit Settings.
-
Upload the downloaded Base64-encoded X.509 Certificate.
-
Click Save Settings.
-
Review all configuration details and click Enable to activate SSO.
After completing these steps, the SAML SSO configuration should pass the test successfully.
Conclusion
A failed SAML SSO setup in HCP Terraform often points to issues with the X.509 certificate rather than the ACS URL or Entity ID. Always ensure that the certificate is correctly exported in Base64 format and matches the IdP's signing configuration. Proper certificate management is essential for successful SAML integration.