Configure Terraform Enterprise as the SAML service provider

This topic describes how to configure Terraform Enterprise as the SAML service provider (SP). SAML is an XML-based standard for authentication and authorization. Terraform Enterprise can act as a service provider (SP), also called a relying party, with your internal SAML identity provider (IdP).

Overview

Complete the following steps to configure Terraform Enterprise to authenticating and authorizing users with SAML.

Configure Terraform Enterprise as the service provider (SP). The SP also sometimes referred to as relying party (RP).
Configure the SAML identity provider (IdP). For instructions for specific IdPs, refer to Identity Provider Configuration.

Refer to the Admin Settings API documentation for instructions on how to configure SAML using the API.

Requirements

Only Terraform Enterprise users with the site-admin permission can modify SAML settings. For more information about site admins, refer to Site Administration Permissions.

Prior to activating SAML, we recommend that you create a non-SSO admin account for recovery to ensure that you are able to log in as an admin in case of error.

Terraform Enterprise supports the SAML 2.0 standard.

Configure Terraform Enterprise as the SP

Open your user icon menu and click Site Admin or go directly to https://<TFE HOSTNAME>/app/admin/saml.
Specify values for the SAML settings and click Save SAML Settings. Refer to SAML Configuration Settings Reference for details.

Configure the SAML Identity Provider

Configure the following values in the SAML Identity Provider (IdP):

Audience: https://<TFE HOSTNAME>/users/saml/metadata
Recipient: https://<TFE HOSTNAME>/users/saml/auth
ACS (Consumer) URL: https://<TFE HOSTNAME>/users/saml/auth

The SAML metadata document is available at https://<TFE HOSTNAME>/users/saml/metadata.xml

SAML Configuration Settings Reference

You can configure the following settings to configure Terraform Enterprise as the SP when integrating with a SAML identity provider.

SAML Settings

Enable SAML single sign-on: This checkbox must be enabled.

Identity Provider Settings

Single Sign-On URL: The HTTP(S) endpoint on your IdP for single sign-on requests. This value is provided by your IdP configuration.
Single Log-Out URL: The HTTP(s) endpoint on your IdP for single logout requests. This value is provided by your IdP configuration. Single Logout is not yet supported.
IdP Certificate: The PEM encoded X.509 Certificate as provided by the IdP configuration.

Note: When reconfiguring the IdP certificate, Terraform Enterprise will retain the old IdP certificate to allow for a rotation period. When you are sure that the new certificate is functioning correctly, you must explicitly remove the old IdP certificate. A button labeled "Revoke old IDP certificate" will appear below the IdP Certificate field if you are in a rotation period. You can also remove the old certificate via an API endpoint.

Attributes

Username Attribute Name: (default: Username) The name of the SAML attribute that determines the Terraform Enterprise username for a user logging in via SSO.
Site Admin Attribute Name: (default: SiteAdmin) The name of the SAML attribute that determines whether a user has site-admin permissions. The value of this attribute in the SAML assertion must be a boolean. Site admins can manage settings and resources for the entire Terraform Enterprise instance; see [Administering Terraform Enterprise][admin] for details.
Team Attribute Name: (default: MemberOf) The name of the SAML attribute that determines team membership. The value of this attribute in the SAML assertion must be either a string containing a comma-separated list of team names or separate AttributeValue items. Team membership mapping is case-sensitive.

Team Membership Mapping

Site Admin Role: (default: site-admins; make blank to disable) An alternate way of managing site-admin permissions; if a role with this name is present in the value of the Team Attribute Name attribute, the user is an admin.
We recommend using the "site admin attribute name" setting instead. If you are using the site admin attribute, you can disable "site admin role" by deleting its value.

User Session

API Token Session Timeout: (default: 1209600 seconds, or 14 days) The duration of time (in seconds) for which Terraform Enterprise will accept a user's API token before requiring the user to log in again. For more details about this behavior, see API Token Expiration.