SAML Settings in Terraform Enterprise

Introduction

Terraform Enterprise (TFE) supports Security Assertion Markup Language (SAML) for Single Sign-On (SSO) integration to provide a secure authentication experience. This guide explains how to configure the available SAML settings in the TFE administrative console.

SAML Configuration Settings

General Settings

Enable SAML Single Sign-On

This setting enables SAML as the authentication mechanism for users logging into Terraform Enterprise. When you enable this option, TFE redirects users to the configured Identity Provider (IdP) for authentication.

To enable:

1. Navigate to the Terraform Enterprise administrative console.
2. Go to the Authentication section.
3. Select the Enable SAML Single Sign-On checkbox.

Enable SAML Debugging

This setting provides detailed debugging information for SAML authentication issues. When a sign-on attempt fails, TFE displays the raw SAMLResponse XML on the login page, which helps you diagnose and resolve configuration problems.

To enable:

1. In the SAML configuration section, select the Enable SAML Debugging checkbox.
2. Use this setting with caution in production environments, as the SAMLResponse XML may contain sensitive information.

Certificate and Key

Certificate

This is the X.509 certificate used for signing SAML requests and assertions. It ensures the integrity and authenticity of the communication between Terraform Enterprise and the IdP.

To configure:

1. Obtain the X.509 certificate from your IdP or generate one if necessary.
2. Paste the certificate into the Certificate field in the TFE SAML settings.

Private Key

The private key is used for signing SAML requests and assertions and must correspond to the uploaded certificate.

To configure:

• To update the private key, paste the new key into the Private Key field.
• To retain the existing private key, leave this field empty.

Advanced Security Settings

Enable AuthnRequestsSigned

When enabled, Terraform Enterprise digitally signs the <samlp:AuthnRequest> messages it sends to the IdP. This signature ensures that the authentication request originates from a trusted source.

To enable:

1. Select the Enable AuthnRequestsSigned checkbox in the SAML settings.
2. Ensure your IdP is configured to accept signed authentication requests.

Enable WantAssertionsSigned

When enabled, Terraform Enterprise requires that <saml:Assertion> elements in the IdP's SAMLResponse are signed. This ensures the authenticity of the assertion.

To enable:

1. Select the Enable WantAssertionsSigned checkbox.
2. Confirm that your IdP signs the assertions in its SAMLResponse.

Signature Configuration

Signature Signing Method

This setting defines the algorithm used for signing SAML requests and assertions. TFE supports SHA256 and SHA1.

To configure:

• Select SHA256 or SHA1 from the dropdown menu.

Signature Digest Method

This setting defines the hash algorithm used for digesting the signed content. SHA256 and SHA1 are the available options.

To configure:

• Select SHA256 or SHA1 from the dropdown menu.

Testing and Troubleshooting

After configuring the SAML settings, test the integration by logging out and attempting to log in again using SAML SSO.

• Invalid Certificate or Private Key: Ensure the uploaded certificate and private key match.
• Authentication Fails: Verify that the IdP configuration (e.g., assertion signing, endpoints) matches the TFE settings.
• SAML Debugging Output: If authentication fails, temporarily enable SAML debugging to inspect the SAMLResponse XML. This output can help diagnose issues like mismatched attributes or incorrect assertion signatures.

Additional Information

• SAML Configuration for Terraform Enterprise