Enable Single Sign On (SSO) in Terraform Enterprise

Terraform Enterprise (TFE) is a self-hosted, private instance of the HCP Terraform application with additional enterprise-grade architectural features like audit logging, SAML single sign-on, and unlimited resource management.

By integrating Terraform Enterprise with an identity provider (IdP), like Entra ID or Okta, you can add new users to teams in the IdP and SSO will automatically propagate the user and team membership to Terraform Enterprise. Terraform Enterprise uses SAML 2.0, an XML-based standard for authentication and authorization, to act as a service provider (SP) with your existing identity providers.

In this tutorial, you will configure SAML settings in both Terraform Enterprise and Okta (an identity provider) to set up SSO. To do this, you will:

1. create a SAML application in Okta, populating it with your Terraform Enterprise SAML configuration, and
2. complete the SAML integration in Terraform Enterprise, populating it with the Okta SAML values in the previous step.

You will only need to complete these steps once to configure SAML settings between Terraform Enterprise and Okta.

To verify that SAML is configured correctly, first, you will create two teams with different permissions in Terraform Enterprise, and Okta groups and users that map to the Terraform Enterprise teams. Then, you will sign into Terraform Enterprise through Okta and directly through SSO.

Prerequisites

To perform the steps in this tutorial, you need a Terraform Enterprise application (Standalone or Active/Active deployment) and a user with administrative rights.

In addition, you must have an Okta account. Create an Okta trial organization if you don’t have one.

In this tutorial, you will configure Okta as an identity provider for Terraform Enterprise and create test users and groups. Create or use a non-production Terraform Enterprise organization while completing this tutorial.

You must also be familiar with creating Terraform Enterprise teams. Complete the Manage Permissions in HCP Terraform tutorial to learn how to create and manage Terraform Enterprise teams and their respective permissions.

Enable Terraform Enterprise SAML SSO

In your Terraform Enterprise dashboard, click the user icon on the top right corner, then select Admin to go to the Admin page.

Click SAML on the left navigation menu to go to the SAML settings page. You will find the identity provider (IdP) configuration that you use later to configure single sign on with Okta.

Enable SAML by clicking the Enable SAML single single-on checkbox.

Save your changes by clicking Save SAML settings at the bottom of the page.

Create SAML application in Okta

Select the Applications dropdown from the left navigation, then click Applications to go to the Applications page.

Next, click Create App Integration.

Select SAML 2.0 then click Next.

In the General Settings page, enter Terraform Enterprise for the App name, and upload the Terraform Enterprise icon for the App logo. Click Next.

Under the SAML Settings section, specify your Terraform Enterprise SAML configuration information, which you can find on your Terraform Enterprise SAML page.

Okta uses the Attribute Statement and Group Attribute Statements sections to map its user its respective Terraform Enterprise role and team membership.

​​Under the Attribute Statements section in the same page, configure a site admin permissions attribute statement. This statement defines which users is a Terraform Enterprise administrator. In this tutorial, if the user’s Okta TFEAdmin attribute is true, this integration will assign that user administrator rights in Terraform Enterprise.

​​Under the Group Attribute Statements section in the same page, configure a group attribute statement to report which teams a user belongs to. The group attribute statement’s filter field specifies which Okta groups you want to expose to Terraform Enterprise. In this tutorial, Okta groups that contain -team (security-team and services-team) will have access to Terraform Enterprise.

Click Preview the SAMLAssertion to view the SAML response. It should be similar to the following.

<xml version="1.0" encoding="UTF-8">
  <saml2:Assertion ID="id53447262652528431355581993" IssueInstant="2021-11-08T20:23:06.895Z" Version="2.0"
    xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
    <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"/>
    <saml2:Subject>
      <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">userName</saml2:NameID>
      <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml2:SubjectConfirmationData NotOnOrAfter="2021-11-08T20:28:07.097Z" Recipient="https://REDACTED.com/users/saml/auth"/>
      </saml2:SubjectConfirmation>
    </saml2:Subject>
    <saml2:Conditions NotBefore="2021-11-08T20:18:07.097Z" NotOnOrAfter="2021-11-08T20:28:07.097Z">
      <saml2:AudienceRestriction>
        <saml2:Audience>https://REDACTED.com/users/saml/metadata</saml2:Audience>
      </saml2:AudienceRestriction>
    </saml2:Conditions>
    <saml2:AuthnStatement AuthnInstant="2021-11-08T19:09:56.495Z">
      <saml2:AuthnContext>
        <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
      </saml2:AuthnContext>
    </saml2:AuthnStatement>
    <saml2:AttributeStatement>
      <saml2:Attribute Name="SiteAdmin" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml2:AttributeValue
          xmlns:xs="http://www.w3.org/2001/XMLSchema"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">true
        </saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="MemberOf" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml2:AttributeValue
          xmlns:xs="http://www.w3.org/2001/XMLSchema"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">GroupName Match Contains "-team" (ignores case)
        </saml2:AttributeValue>
      </saml2:Attribute>
    </saml2:AttributeStatement>
  </saml2:Assertion>
</xml>

Click Next.

Finally, select I’m an Okta customer adding an internal app, then click Finish.

You will find the newly created Terraform Enterprise application integration in Okta.

Click on View Setup Instructions.

You will find the following values, which you need to complete the SAML integration in Terraform Enterprise.

Complete SAML integration in Terraform Enterprise

In your Terraform Enterprise SAML page, under SAML Settings, copy and paste the values from Okta to the following fields.

Under Team Membership Management, verify that the Use SAML to manage team memberships checkbox is selected. This ensures Okta is the source of truth for Terraform Enterprise teams and user management. You can still manually add users in Terraform Enterprise; however, when they sign in through SSO their team memberships will automatically be updated to reflect the ones defined by the identity provider.

If Terraform Enterprise team does not have an equivalent team in the identity provider (team names must exactly match), Terraform Enterprise will ignore that team membership and will not automatically create a new team with that name.

Save your changes by clicking Save SAML settings at the bottom of the page.

Create Terraform Enterprise teams

Now that you have configured SAML in both Terraform Enterprise and identity provider, you will now create sample Terraform Enterprise teams, Okta groups and users.

In your Terraform Enterprise dashboard, click Settings on the top navigation bar to go to the settings page. Now, click Teams on the left navigation menu to go to the Teams page.

Next, you will create a security and services team. Each team will have different permissions, scoped to their responsibilities. In this example, these teams’ responsibilities and permissions do not overlap to highlight the differences between the two teams. These teams’ responsibilities and permissions may be different for your organization.

Create the security-team, who manages the policies that check and validate workspace resources, and can override non-passing policy checks. Check the Manage Policies and Manage Policy Overrides boxes to give the security team the correct permissions.

Click the Update team organization access button to save your changes.

Now, create the services-team, who manages resources with Terraform Enterprise. Check the Manage Workspaces and Manage VCS Settings boxes to give the service team the right permissions.

Click the Update team organization access button to save your changes.

Create Okta groups and users

In this section, you will create Okta groups and users. The Okta groups correspond to the Terraform Enterprise teams you created. When you add users to the Okta groups they will automatically gain access to Terraform Enterprise, with permissions based on their group and its corresponding team.

In your Okta dashboard, select Directory from the left navigation, then click Groups to go to the Groups page.

Create two groups with the following information. First, click Add Group then enter the group name and description. Then, click Save to create the group.

Once done, the dashboard will show both Okta groups.

Create Okta users

In this section, you will create two users, John Doe and Jane Doe, one for each group.

Select Directory from the left navigation, then click People to go to the People page.

Click Add person, then fill out the form for your user named John Doe. Enter the same email address for both the user's username and email fields.

Assign this user to the security-team group and select the Send user activation email now checkbox. Click Save and Add Another.

Create another user named Jane Doe, assign them to the services-team, and select the Send user activation email now checkbox. Enter the same email address for both the user's username and email fields.

Click Save.

On the People page, you will find your newly created Okta users. Notice these users are pending user action.

Activate their accounts by following the instructions in the Okta account activation email.

Once you activate both accounts their statuses will change to "Active".

Assign Terraform Enterprise to groups

In this section, you will assign Terraform Enterprise to the security-team and services-team group in Okta. All users in these groups will have access to Terraform Enterprise.

Click Assignments in the top navigation bar to go to the Assignments page. Select Assign and click on Assign to Groups.

Click the Assign buttons near security-team and services-team to assign Terraform Enterprise to these Okta groups. Click Done to complete.

Log into TFE via Okta

Now you will verify that you have configured SAML in both Terraform Enterprise and identity provider by signing into Terraform Enterprise via single sign on. This is the workflow your organization’s users will go through to access Terraform Enterprise either through your Okta or directly through your Terraform Enterprise dashboard.

In a different browser (or incognito), go to your Okta page and sign in as John Doe, the first user you created. You will find Terraform Enterprise as an application.

Click on the Terraform Enterprise icon to create a new account and log into the Terraform Enterprise application.

Click on Settings, then Teams to go to the Teams page. Click on the security-team.

Under the Members section, you will find the user you signed in with. By setting up SAML to enable SSO, Terraform Enterprise creates a user and automatically assigns it to that user’s respective Terraform Enterprise team based on their Okta group assignment.

Sign out of both Terraform Enterprise and Okta.

Log into TFE with SSO

Go to the Terraform Enterprise application, then click on Log in via SAML.

It will redirect you to Okta and prompt you to enter your Okta credentials. Enter your credentials for Jane Doe, your second test user.

Terraform Enterprise will automatically create a new account and assign you to your respective team.

Click on Settings, then Teams to go to the Teams page. Click on the services-team.

Under the Members section, you will find the user you signed in with.

Clean up resources

Now that you have verified that your organization’s users can sign into Terraform Enterprise with SSO, clean up all the resources you have created in this tutorial.

Disable SSO in Terraform Enterprise

In your Terraform Enterprise dashboard, click the user icon on the top right corner, then select Admin to go to the Admin page.

Disable SAML by de-selecting the Enable SAML single sign-on checkbox.

Save your changes by clicking Save SAML settings at the bottom of the page.

Remove Terraform Enterprise users and teams

Sign into Terraform Enterprise as the administrator.

Click Settings in the top navigation bar, then select Users.

Remove the two user accounts you created in this tutorial by clicking ... then Remove from Organization.

Click Teams in the left navigation menu to go to the Teams page, then delete both the security-team and services-teams.

Select security-team, scroll down and click the Delete security-team button.

Do the same to delete the services-team.

Remove Okta users, groups, and application

Go to your Okta’s People page to deactivate and delete the users you created in this tutorial.

Select the first user. Click More actions, then Deactivate.

Click Delete, then confirm the action.

Deactivate and delete the second user you created in this tutorial.

Go to the Groups page.

Select security-team. Click Delete Group then confirm your action.

Do the same for the services-team group.

Finally, go to the Applications page. Select Terraform Enterprise.

Click the Active dropdown, and click Deactivate. Confirm this action by clicking Deactivate Application.

Click the Inactive dropdown, and click Delete. Confirm this action by clicking Delete Application.

Next steps

In this tutorial, you configured SAML settings in both Terraform Enterprise and Okta, then tested it by signing in via the Okta dashboard and through Terraform Enterprise. In the process, you have learned how Terraform Enterprise to create new users and assign them to their appropriate teams based on their Okta identities.

For more information on topics covered in this tutorial, review the documentation below:

• Visit the Terraform Enterprise SAML Configuration documentation to learn more about the identity provider settings and attributes referenced in this tutorial.

• Visit the Terraform Enterprise Identity Provider Configuration documentation to learn how to integrate Terraform Enterprise with other identity providers, including Active Directory Federated Services (ADFS), Azure Active Directory, Okta and OneLogin.

• Visit the Terraform Enterprise Troubleshooting Guide to review common issues and learn how to troubleshoot them.