Terraform Cloud SSO Setup with AD FS

Steps

Introduction

HCP Terraform allows organizations to configure single sign-on (SSO) using the SAML 2.0 protocol as an alternative to traditional user management. You can use any Identity Provider (IdP) that supports the SAML 2.0 protocol, though the specific configuration on the IdP side will vary.

This guide details the steps to set up SSO for HCP Terraform using Microsoft Active Directory Federation Services (AD FS) as an IdP.

Note: This guide provides a reference for a default AD FS setup. Your specific AD FS configuration may differ depending on your organization's requirements and should be determined by your AD FS administrator.

Procedure

Step 1: Gather Information from AD FS

First, you need to collect the token-signing certificate and the metadata URL from your AD FS server.

1. Export the token-signing certificate.
   1. In the AD FS console, expand the Service object and navigate to the Certificates section.
   2. Right-click the Token-signing certificate and select View Certificate.
   3. Go to the Details tab and click Copy to File....
   4. Follow the export wizard instructions, choosing the Base-64 encoded X.509 (.CER) format when prompted.
2. Locate the Federation Metadata URL.
   1. In the AD FS console, expand the Service object and go to the Endpoints section.
   2. Find the URL in the Metadata section for Federation Metadata. The default path is /FederationMetadata/2007-06/FederationMetadata.xml.

Step 2: Configure SSO in HCP Terraform

Next, configure your HCP Terraform organization to use the information from AD FS.

1. Navigate to your HCP Terraform organization's settings, select the SSO section, and click Setup SSO.
2. Select the SAML provider option and click Next.
3. Enter the full AD FS Federation Metadata URL into the Metadata URL field and click Save Settings.
4. On the next screen, click Edit Settings.
5. Open the token-signing certificate file you exported from AD FS, copy its contents, and paste them into the X.509 Certificate field. Click Save Settings.
6. Take note of the Entity ID (Audience) and Assertion Consumer URL values. You will need these to configure the Relying Party Trust in AD FS.

Step 3: Configure AD FS Relying Party Trust

Return to the AD FS console to create and configure a Relying Party Trust for HCP Terraform.

1. Add a new Relying Party Trust.
   1. Right-click on Relying Party Trusts to open the setup wizard.
   2. Select Claims aware and click Start.
   3. Select Enter data about the relying party manually and click Next.
   4. Enter a display name (e.g., "HCP Terraform") and click Next.
   5. On the Configure Certificate window, click Next.
   6. Check the Enable support for the SAML 2.0 WebSSO protocol box. Paste the Assertion Consumer URL from HCP Terraform into the Relying party SAML 2.0 SSO service URL field and click Next.
   7. Paste the Entity ID (Audience) from HCP Terraform into the Relying party trust identifier field, click Add, and then click Next.
   8. Choose an appropriate access control policy, such as Permit everyone, and click Next.
   9. Complete the wizard by clicking Next and then Close.
2. Configure Claim Issuance Policy.
   1. Right-click the newly created relying party trust for HCP Terraform and select Edit Claim Issuance Policy....
   2. Create a rule to send LDAP Attributes as Claims.
      1. Click Add Rule... and select Send LDAP Attributes as Claims from the template dropdown. Click Next.
      2. Set a name for the rule (e.g., "Send Email").
      3. Set the Attribute store to Active Directory.
      4. Map the LDAP Attribute E-Mail-Addresses to the Outgoing Claim Type E-Mail Address.
      5. Click Finish.
   3. Create a rule to transform an incoming claim.
      1. Click Add Rule... and select Transform an Incoming Claim from the template dropdown. Click Next.
      2. Configure the transform rule:
         • Claim rule name: Transform Email to NameID
         • Incoming claim type: E-Mail Address
         • Outgoing claim type: Name ID
         • Outgoing name ID format: Email
      3. Click Finish.

Step 4: Test and Enable SSO in HCP Terraform

After completing the AD FS setup, return to HCP Terraform to test and enable the configuration.

1. Navigate to your HCP Terraform organization's Settings > SSO page.
2. Click Test to verify the connection.

Once the test is successful, click Enable to allow users to start logging in via SSO.

Additional Information

• Configuring SSO with SAML in HCP Terraform
• How SSO Works in HCP Terraform