Terraform Cloud SSO Setup with AD FS – HashiCorp Help Center

Introduction

Terraform Cloud allows organizations to configure single sign-on (SSO) via the SAML 2.0 protocol as an alternative to traditional user management. Potentially, any Identity Provider (IdP) that supports the SAML 2.0 protocol can be used and the configuration required on the IdP's side would be specific to the IdP itself.

Use Case

This article shows the steps needed to set up SSO on Terraform Cloud using Microsoft AD FS as an IdP.

Note: The article assumes a default AD FS setup and no special requirements and it is intended as a reference and not a definitive guide. The exact AD FS configuration that needs to be performed may differ depending on the specific use case and should be determined by the AD FS administrator.

Procedure

Gather information on AD FS side

Export the "Token-signing" certificate to a file in a Base64 encoded PEM format. To do this:
- In the AD FS console expand the "Service" object and go to the "Certificates" section.
- Click on "View Certificate".
- Go to the "Details" tab.
- Click on "Copy to File...".
- Follow the export wizard instructions, choosing the "Base-64 encoded X.509 (.CER)" format when asked to do so.

Note the MetaData Endpoint URL
- In the AD FS console expand the "Service" object and go to the "Endpoints" section.
- Note the URL of the "Federation Metadata". By default, it would be /FederationMetadata/2007-06/FederationMetadata.xml.

Configure Terraform Cloud

Go to the Terraform Cloud organizations settings, SSO section, and click on "Setup SSO".
Select the SAML provider and click on "Next".
Enter the full AD FS "Federation Metadata" URL in the "Metadata URL" field and click "Save Settings".
On the next screen click "Edit Settings".
Paste the contents of the AD FS token-signing certificate in the "X.509 Certificate" field and click "Save Settings".
The resulting SSO settings should look similar to the screenshot below. Note the "Entity ID (Audience)" and "Assertion Consumer URL" values in the "Terraform Cloud" section. They will be needed for the AD FS configuration.

Configure AD FS

Add Relying Party Trust
- Right-click on the "Relying Party Trusts" to open the setup wizard.
- Select "Claims aware" and click on "Next" to advance.
- Select "Enter data about the relying party manually" and click on "Next".
- Enter a display name of your choice and click on "Next".
- On the "Configure Certificate" window click on "Next".
- Tick the "Enable support for the SAML 2.0 WebSSO protocol" checkbox, paste Terraform Cloud's "Assertion Consumer URL" shown in the Terraform Cloud's SSO settings in the "Relying party SAML 2.0 SSO service URL" field, and click on "Next".
- Paste Terraform Cloud's "Entity ID (Audience)" shown in the Terraform Cloud's SSO setting in the "Relying party trust identifier" field, click on "Add" and then click on "Next".
- Choose the appropriate access control policy e.g. "Permit Everyone" and click on "Next".
- Complete the remaining steps - "Ready to add trust" and "Finish" by clicking the "Next" button.
Configure Claim Issuance
- Open the "Edit Claim Issuance Policy" window by right-clicking on the created relying party trust for Terraform Cloud.
- Set up LDAP Attributes as Claims.
  - Click "Add Rule", and then select "Send LDAP Attributes as Claims" from the Claim rule template dropdown. Click "Next".
  - Set a name used to identify the claim rule.
  - Set the attribute store to "Active Directory".
  - Click on "Finish".
- Transform Incoming Claims
  - Click "Add Rule", and then select "Transform an Incoming Claim" from the Claim rule template dropdown. Click "Next".
  - Configure the claim transform rule.
    - Set a name used to identify the claim rule.
    - Select "E-mail Address" as the Incoming Claim Type.
    - Select "Name ID" as the Outgoing Claim Type.
    - Select "Email" for Outgoing Name ID Format.
    - Click "Finish".