Troubleshooting single sign-on (SSO) on HCP

This page describes the troubleshooting process when setting up a preferred identity provider for SSO on HCP.

Overview

When enabling SSO for HCP, errors issues belong to one of two categories:

Errors in HCP setup are within our support scope.
Errors in IdP setup are outside the scope of our support. Refer to your identity provider’s documentation for more information and additional troubleshooting resources.

Common error messages

Access was denied while authenticating

Error message: Access was denied while authenticating.

Cause: This error can occur if you have a misconfigured Entity ID in SAML SSO that does not match the assigned Entity ID in HCP.

Solutions: Ensure the configured Entity ID matches the one in HCP.

An error occurred with authentication

Error message: An error occurred with authentication.

Cause: This error indicates an issue verifying a token or claim request against user metadata.

Solutions: Follow the instructions in the error page, which provides additional information about the error.

Error message: invalid_request: IdP-Initiated login is not enabled.

Cause: Currently, the HCP SSO integration requires you to log in directly from the HCP UI with your SSO credentials. It is currently expected to receive an error similar to the one below if you try to log into HCP directly from your SSO platform.

invalid_request: IdP-Initiated login is not enabled for connection "HCP-SSO-11eb58f9-5983-1701-8c33-0242ac110016-samlp".
TRACKING ID: 1ee9c265894f363dd226

You may also receive an Oops!, something went wrong message as well.

Solutions: Log into HCP directly from the HCP Portal with your SSO credentials.

Okta SAML workaround

As an alternative workaround, you can use the bookmark app in Okta to have a tile that will mimic the IdP-initiated from HCP. The URL that can be used is https://portal.cloud.hashicorp.com/login/signin?conn-id=HCP-SSO-<ORGID>-samlp.

You should replace the ORGID with the actual organization ID, which can be found under Organization Settings in the HCP Portal.

Microsoft Entra ID (Azure AD) SAML workaround

As an alternative workaround, you can set the "Sign-on URL" under the Basic SAML Configuration settings. The URL that can be used is https://portal.cloud.hashicorp.com/login/signin?conn-id=HCP-SSO-<ORGID>-samlp.

You should replace the ORGID with the actual organization ID which can be found under Organization Settings in the HCP Portal.

Not recognized as a verified TXT record

Error message: Not recognized as a verified TXT record.

Cause: This can be caused if the appropriate TXT record was not created or if it was incorrectly configured within your domain host.

Solutions: Add the TXT record to your domain host or edit the existing TXT record to match the expected format.

You can validate whether you see a TXT entry for HCP using either the dig or host command.
```
$ dig -t txt domain.com 
```
```
$ host -t TXT domain.com
```
Alternatively, you can use this website to validate the TXT records.

The expectation is you should see a TXT record with a value which follows a format similar to hcp-domain-verification=c886c6010596fb39XXXX18bd80c77073b3584 when querying your domain's TXT records.

After the domain is successfully verified, you can continue with the rest of the SSO setup steps.

Something went wrong (OIDC)

Error message: Something went wrong.

This error redirects you to the HCP portal.

Cause: The issuer URL must have the following pattern: https://<domain>/

Solutions: Add the trailing slash to the URL, or adjust as necessary to match the pattern.

Something went wrong (SAML)

Error message: Something went wrong.

Cause: Either the user provided an invalid certificate to validate the SAML Response signature, or the user did not set the email as an attribute assertion name on the upstream IDP.

Solutions: To check the certificate, you can usually obtain the required information from the identity provider's metadata.xml. Identity providers usually provide an endpoint to download this file.

For more information on attribute assertion, refer to the list of supported SAML attributes.

Unable to proceed with request

Error message: Unable to proceed with the request.

Cause: This error is caused by a misconfigured certificate or a invalid ACS URL.

Solutions:

Mismatch of the certificates. Please make sure the certificates match. Check to make sure that there is not an extra space at the end or any extra character added while setting up the certificate.
Invalid ACS URL. While we provide a "SSO Sign-On URL" in the "Initiate SAML Integration" instructions, some IdPs receive the request at a path which omits the ?connection=HCP-SSO-<ORGID>-saml argument. Try to use this URL instead for your ACS URL in your IdP settings:
```
https://auth.hashicorp.com/login/callback
```

Reused domains

You need a DNS record (secret value to set as TXT) to prove ownership of a domain. HCP uses the domain to match the email addresses for SSO. You must use different SSO domains for each HCP organization. If you try to reuse a domain name, the DNS connection request will fail.

Support

If you experience other issues when enabling SSO for your HCP organization, refer to the HashiCorp Help Center or contact our Support team.