HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Terraform Home

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 authenticate and authorize users with SAML.

When Terraform Enterprise is configured to provision users through SCIM, SAML is used only for authentication. Terraform Enterprise ignores team membership from SAML assertions, does not use SAML site-admin or site-auditor settings for site administrator or site auditor provisioning, and requires users to already be provisioned through SCIM before they can authenticate with SAML.

  1. Configure Terraform Enterprise as the service provider (SP). The SP is also sometimes referred to as a relying party (RP).
  2. 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

  1. Open your user icon menu and click Site Admin or go directly to https://<TFE HOSTNAME>/app/admin/saml.
  2. 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):

  1. Audience: https://<TFE HOSTNAME>/users/saml/metadata
  2. Recipient: https://<TFE HOSTNAME>/users/saml/auth
  3. 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 Certificates: One or more PEM encoded X.509 certificates as provided by the IdP configuration. Refer to Manage IdP certificates.

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 when SCIM is not enabled. Terraform Enterprise ignores this setting for SCIM-managed users when SCIM is enabled.
  • 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 Site Administration Permissions for details. Terraform Enterprise ignores this setting when SCIM is enabled.
  • Site Auditor Attribute Name: (default: SiteAuditor) The name of the SAML attribute that determines whether a user has the Site Auditor role. The value of this attribute in the SAML assertion must be a boolean. The Site Auditor role provides read-only, cross-organization visibility into all resources in the instance without organization-level membership. The Site Auditor role is separate from site admin: a user can hold either role or both at the same time. Terraform Enterprise ignores this setting when SCIM is enabled.
  • 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. Terraform Enterprise ignores this attribute when SCIM is enabled.

Team Membership Mapping

When SCIM provisioning is enabled, Terraform Enterprise ignores team membership from SAML assertions. SCIM takes precedence for team membership management. Refer to Link SCIM groups to teams for more information.

  • Site Admin Role: (default: site-admins; make blank to disable) An alternate way to manage site administrator access when SCIM is not enabled. If a role with this name is present in the value of the Team Attribute Name attribute, Terraform Enterprise grants site administrator access to that user. Terraform Enterprise ignores this setting when SCIM is enabled.

    We recommend using Site Admin Attribute Name instead. If you are using Site Admin Attribute Name, you can disable Site Admin Role by deleting its value.

  • Site Auditor Role: (default: site-auditors; make blank to disable) An alternate way to manage Site Auditor access when SCIM is not enabled. If a role with this name is present in the value of the Team Attribute Name attribute, Terraform Enterprise grants the Site Auditor role to that user. Terraform Enterprise ignores this setting when SCIM is enabled.

    We recommend using Site Auditor Attribute Name instead. If you are using Site Auditor Attribute Name, you can disable Site Auditor Role by deleting its value.

Manage IdP certificates

Terraform Enterprise verifies the signature on each SAML response against the IdP certificates stored in its SAML settings. Terraform Enterprise can trust multiple IdP certificates at the same time and tries each trusted certificate until one validates the signature. As a result, you can do the following without interrupting logins:

  • Run an IdP across multiple regions, where each region signs SAML responses with a different certificate.
  • Migrate between identity providers while both providers are live.
  • Rotate a certificate by adding the new certificate before removing the old one.

Each certificate is a separate resource with its own ID, display name, fingerprint, issuer, and expiration date. Manage certificates from Site Admin > SAML in the UI, or with the SAML IdP certificates API.

Requirements and behavior

  • Terraform Enterprise rejects a certificate that it cannot parse as an X.509 certificate and a certificate that has already expired.
  • Terraform Enterprise rejects a certificate whose SHA-256 fingerprint matches a certificate that it already trusts.
  • Terraform Enterprise stores at most 1,000 IdP certificates, including legacy certificates. When you reach the limit, delete expired or unused certificates before you add more.
  • You can add, rename, replace, and delete certificates whether or not SAML is enabled. This lets you add your first certificate before you turn SAML on, and correct a mistake before your first login.
  • A certificate that you add while SAML is disabled is inert until you enable SAML.
  • Enabling SAML requires at least one trusted certificate.
  • While SAML is enabled, Terraform Enterprise refuses to delete the last trusted certificate so that you cannot lock yourself out. Disable SAML or add another certificate first.

Rotate a certificate

  1. Add the new certificate from your IdP. Terraform Enterprise trusts it immediately, alongside the certificates it already trusts.
  2. Confirm that users can log in after your IdP begins signing with the new certificate.
  3. Delete the old certificate.

Because both certificates are trusted during the overlap, rotation causes no downtime.

Certificate expiration

Every X.509 certificate has a fixed expiration date that Terraform Enterprise cannot extend. Terraform Enterprise refuses to verify a SAML response against an expired certificate, so if every trusted certificate expires, all SAML logins fail until a site admin adds a current certificate. Terraform Enterprise displays the expiration date for each certificate and warns you as a certificate approaches expiration. Add the replacement certificate before the current one expires.

Legacy certificate slots

Before multiple certificate support, Terraform Enterprise stored a single active certificate and one temporary certificate that was used only during a rotation window. Terraform Enterprise migrates those certificates into the certificate collection automatically, and labels them legacy_primary and legacy_old so that the existing API continues to behave the same way.

You can rename or delete a legacy certificate, but you cannot replace its body from the certificate resource. Rotate it through the deprecated idp-cert attribute on Update SAML settings, or add a new certificate and delete the legacy one.

Note

The idp-cert and old-idp-cert attributes and the Revoke previous SAML IdP certificate endpoint are deprecated and will be removed in a future release. Manage certificates with the SAML IdP certificates API instead.

Site Auditor provisioning

Terraform Enterprise can automatically grant and revoke the Site Auditor role based on your SAML assertions. The Site Auditor role is available in Terraform Enterprise only. It is not available in HCP Terraform.

You can manage the role through either of the following paths:

  • Site Auditor Attribute Name (default: SiteAuditor): a literal boolean attribute in the assertion.
  • Site Auditor Role (default: site-auditors): a role value in the Team Attribute Name attribute.

When both paths are configured, the literal Site Auditor Attribute Name value takes precedence. Terraform Enterprise falls back to the Site Auditor Role value only when the literal attribute is absent from the assertion.

On each login, Terraform Enterprise evaluates the assertion and reconciles the role:

  • When the assertion grants the Site Auditor role, Terraform Enterprise grants the user read-only, cross-organization access.
  • When the assertion does not grant the role and the user is currently a Site Auditor, Terraform Enterprise revokes the role.

The following assertion grants the Site Auditor role through the literal Site Auditor Attribute Name attribute:

<saml:AttributeStatement>
  <saml:Attribute Name="SiteAuditor">
    <saml:AttributeValue xsi:type="xs:boolean">true</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

The following assertion grants the Site Auditor role through the site-auditors role in the Team Attribute Name attribute:

<saml:AttributeStatement>
  <saml:Attribute Name="MemberOf" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">site-auditors</saml:AttributeValue>
    <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">devs</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

For more information about these attributes, refer to SAML User Attributes Reference. To configure the assertions on your IdP, refer to Identity Provider Configuration for Okta, Microsoft Entra ID, and ADFS.

When SCIM is enabled, Terraform Enterprise skips SAML Site Auditor provisioning. Manage the role through the SCIM site auditor group instead.

User Session

  • API Token Session Timeout: (default: 1209600 seconds, or 14 days) The duration in seconds that Terraform Enterprise accepts a user's API token before requiring the user to log in again. For more details about this behavior, refer to API Token Expiration.
Edit this page on GitHub