Introduction
Terraform Enterprise (TFE) supports SAML (Security Assertion Markup Language) for Single Sign-On (SSO) integration, enabling a seamless and secure authentication experience. This article provides step-by-step instructions to configure and use the following SAML settings in TFE.
SAML Settings
1. Enable SAML Single Sign-On
This setting enables SAML as the authentication mechanism for users logging into Terraform Enterprise. Once enabled, users are redirected to the configured Identity Provider (IdP) for authentication.
Steps to Enable
1. Navigate to the Terraform Enterprise administrative console.
2. Go to the Authentication section.
3. Enable the checkbox for **SAML Single Sign-On**.
2. Enable SAML Debugging
This setting allows detailed debugging for SAML authentication issues. When a sign-on fails, the raw `SAMLResponse` XML is displayed on the login page, helping diagnose and resolve configuration problems.
Steps to Enable
1. In the SAML configuration section, check the box for Enable SAML Debugging.
2. Use this setting cautiously in production environments, as the `SAMLResponse` XML might contain sensitive information.
Certificate and Private Key
Certificate
This is the certificate used for signing SAML requests and assertions. It ensures the integrity and authenticity of the communication between Terraform Enterprise and the IdP.
Steps to Configure
1. Obtain the X.509 certificate from your IdP or generate one if necessary.
2. Paste the certificate in the Certificate field in the TFE SAML settings.
Private Key
The private key is used for signing SAML requests and assertions. It must match the uploaded certificate.
Steps to Configure
1. If you need to update the private key, paste the new private key in the Private Key field.
2. Leave this field empty to retain the existing private key.
Advanced SAML Configuration
1. Enable AuthnRequestsSigned
When enabled, `<samlp:AuthnRequest>` messages sent from Terraform Enterprise to the IdP are digitally signed. This ensures that the authentication request originates from a trusted source.
Steps to Enable
1. Check the box for Enable AuthnRequestsSigned in the SAML settings.
2. Ensure your IdP is configured to accept signed authentication requests.
2. Enable WantAssertionsSigned
When enabled, Terraform Enterprise requires that `<saml:Assertion>` elements in the IdP's SAMLResponse be signed. This ensures the authenticity of the assertion.
Steps to Enable
1. Check the box for Enable WantAssertionsSigned.
2. Confirm that your IdP signs the assertions in its SAMLResponse.
Signature Configuration
1. Signature Signing Method
Defines the algorithm used for signing SAML requests and assertions. TFE supports SHA256 and SHA1 as options.
Configuration
- Select SHA256 or SHA1 from the dropdown in the SAML settings.
2. Signature Digest Method
Defines the hash algorithm used for digesting the signed content. SHA256 and SHA1 are recommended options for security.
Configuration
- Select SHA256 or SHA1 from the dropdown in the SAML settings.
Testing and Validation
1. After configuring the SAML settings, test the integration by logging out and attempting to log in using SAML SSO.
2. If authentication fails, enable SAML Debugging temporarily to inspect the `SAMLResponse` XML.
3. Validate the certificate and private key pairing to ensure signing works as expected.
Troubleshooting
- **Invalid Certificate or Private Key**: Ensure the uploaded certificate and private key match.
- **Authentication Fails**: Verify that the IdP configuration matches TFE settings (e.g., assertion signing, endpoints).
- **SAML Debugging Output**: Use the `SAMLResponse` XML to diagnose issues like mismatched attributes or incorrect assertion signatures.
Additional Information
https://developer.hashicorp.com/terraform/enterprise/saml/configuration