Troubleshoot SAML SSO Integrations

This topic describes troubleshooting steps for debugging SAML single sign-on integrations for Terraform Enterprise.

Requirements

You must use Terraform Enterprise v201807-2 or later to use debugging functionality. If you would like assistance with upgrading, contact support.

Disable SAML Single Sign-On

Before starting, disable SAML SSO by going to https://<TFE HOSTNAME>/app/admin/saml and unchecking the Enable SAML Single Sign-On checkbox. It's best to start from a clean setup.

Create a non-SSO admin account for recovery

Before troubleshooting, create a non-SSO admin account with an email address not associated with your identity provider (such as SAML).

This non-SSO admin account allows you to log in circumstances where someone accidentally revokes admin access to other SAML-controlled accounts. If your spare non-SSO admin account uses the same email address as your SAML-controlled account, both accounts are affected if your SAML-controlled account loses admin access.

Terraform Enterprise UI

Open https://<TFE HOSTNAME>/signup/account to create the account. Make sure to grant admin access to this user and verify they can log in at https://<TFE HOSTNAME>/.

Rails console

You can also use Rails commands to create a non-SSO admin account. You should only use the following commands when you cannot access a Terraform Enterprise instance through the UI due to a lack of a non-SSO recovery admin account. Refer to Terraform Enterprise UI for additional information.

Access the Rails console by running the following command to attach to the Terraform Enterprise container:

sudo docker exec -ti ptfe_atlas /usr/bin/init.sh /app/scripts/wait-for-token -- bash -ic 'cd /app && bin/rails c'

Create a user in the Rails console and assign it to a u variable:

u = User.create!(email: "example@email.com", username: "example", password: "example", is_admin: true)

Confirm the user. If you skip this step, Terraform Enterprise sends a request confirmation email:
```
u.confirm
u.save
```
Use the Rails console to add the new user to your organization's owners team:
```
Organization.find_by_name("your-org").add_owner!(u)
```
Log into the Terraform Enterprise instance as the new user and disable or reconfigure SSO to allow general access to the system.

Enable SAML SSO and SAML debugging

Enable SAML SSO

Enable SAML SSO by following the configuration instructions.

Enable SAML debugging

Enable SAML debugging by going to https://<TFE HOSTNAME>/app/admin/saml.

Test sign-on

Try signing on by going to https://<TFE HOSTNAME>/ and clicking the "Log in via SAML" button. Verify the page says WARNING: SAML debugging is enabled.

If login fails, the SAMLResponse XML document sent from the identity provider is shown. The XML document may contain the user's username, list of roles, and other attributes. Checking the format of the email address and username and whether the desired list of roles is included may assist with debugging.

If there is a configuration error, that is also shown on the login form.

Fix the configuration error and try to log in again.

Common configuration errors

Most errors will be from misconfiguration and will be shown in the red box on the Terraform Enterprise login form.

CONFIGURATION ERROR: https://<TFE HOSTNAME>/metadata is not a valid audience for this Response - Valid audiences: https://<TFE HOSTNAME>/users/saml/metadata
The audience URL was not configured correctly in the identity provider.
How to resolve: Open the Terraform Enterprise admin settings for SAML SSO, copy the ACS Consumer URL, then paste it into the identity provider settings.

CONFIGURATION ERROR: The response was received at https://<TFE HOSTNAME>/auth instead of https://<TFE HOSTNAME>/users/saml/auth
The recipient URL was not configured correctly in the identity provider.
How to resolve: Open the Terraform Enterprise admin settings for SAML SSO, copy the Metadata URL, then paste it into the identity provider settings.

CONFIGURATION ERROR: Invalid Signature on SAML Response
Incorrect IdP certificate stored on Terraform Enterprise.
How to resolve: Open the Terraform Enterprise admin settings for SAML SSO, and then paste the correct certificate under IDP certificate.

ERROR: Validation failed: Email is invalid, Email is not a valid email address, Username has already been taken
NameID is invalid. It must be an email address.
How to resolve: Open the identity provider settings and configure email address as the value for NameID.

ERROR: Mail::AddressList can not parse |{onelogin:email}|: Only able to parse up to "{onelogin:email}"
The NameID that was received was blank.
How to resolve: Open the identity provider settings and configure email address as the value for NameID.

ERROR: nested asn1 error
The identity provider certificate is invalid or was not pasted correctly into Terraform Enterprise.
How to resolve: Open the identity provider settings, copy the certificate, then paste it into the "IDP Certificate" field in Terraform Enterprise.

ERROR: Issuer of assertion not found or multiple
Terraform Enterprise was unable to determine the issuer of the SAML response.
How to resolve: The most common reason for this issue is that an F5 load balancer is not signing responses, resulting in the <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> and related elements not being present. Follow the steps under Configuring SAML SP Connectors on Using APM as a SAML IdP, particularly step 9c. If you are not using an F5 as part of your SAML setup, see below to contact support.

Contacting support

If you're not able to resolve the error using the steps above, contact out to support. When contacting support, please provide:

A screenshot of "SAML Response" and "Processed attributes" shown on the login page after failed login.
A screenshot of the error on the login page.
The SAMLResponse XML document.
A support bundle.