Terraform Cloud single sign-on provides centralized identity management for organizations using HashiCorp's SaaS offering. The feature replaces traditional username and password management with SAML 2.0 federation, allowing organizations to control access from their existing identity provider. SSO is a paid capability, available as part of the Business upgrade package. Terraform Enterprise single sign-on is configured differently and is not covered here.
Introduction
Organization owners enable SSO for their organization and configure an identity provider to connect to. Once SSO is enabled for an organization, all non-owner members must sign in through SSO in order to access the organization. Owners of an SSO-enabled organization can still access the organization through username and password, to enable fixing problems with SSO.
Current users of Terraform Cloud can link their SSO identity to their existing account, providing a smooth transition when an organization enables SSO. By using SSO, your organization can centralize management of users for Terraform Cloud and other Software-as-a-Service vendors, providing greater accountability and security for an organization's identity and user management.
How SSO Works in Terraform Cloud
Terraform Cloud allows organizations to configure support for SAML 2.0 single sign-on, an alternative to traditional user management.
Organization owners can enable SSO for their organization and configure an identity provider to connect to.
Once SSO is enabled for an organization, all non-owner members must sign in through SSO in order to access the organization.
SSO identities and Terraform Cloud user accounts
SSO does not automatically provision Terraform Cloud user accounts. A user signing in for the first time with SSO must either provide a password to create a new Terraform Cloud user account using their SSO email address as their username, or must link their SSO identity to an existing Terraform Cloud user account.
The accounts of SSO users are normal Terraform Cloud user accounts. If logged in with username and password, these accounts can create, join, and interact with other Terraform Cloud organizations. However, they cannot interact with the SSO-enabled organization without signing in via SSO unless they belong to its owners team.
If an organization's owners disable SSO, or downgrade the organization's account from the Business tier, all members can continue to access the organization using their Terraform Cloud usernames and passwords.
Signing in with SSO
Visit https://app.terraform.io and sign out if you're signed in.
Click "Sign in via SSO".
Provide your organization name and click "Next".
If you've signed in to Terraform Cloud with SSO before, proceed to the next step.
If you're signing in for the first time under this account or for the first time accessing this organization, you'll be required to create a new account or link to an existing account.
Using SSO
You can log on to Terraform Cloud by navigating to your Terraform Cloud SSO page e.g., https://app.terraform.io/session. Click Sign in with SSO
Supported Identity Providers
Select your preferred provider to learn more about what is supported for that provider and how to configure SSO for it.
Supported configurations documented in reference material include Microsoft Active Directory Federation Services, Duo Single Sign-On, and Microsoft Entra ID.
| Identity Provider | Protocol | Notes |
|---|---|---|
| Active Directory Federation Services | SAML 2.0 | Configuration steps specific to AD FS. Reference guide provides a default AD FS setup. |
| Duo Single Sign-On | SAML 2.0 | Acts as an IdP layering Duo authentication and policy engine on top of Terraform Cloud logins. |
| Microsoft Entra ID | SAML | Configure via Enterprise apps in Entra admin center. |
Terraform Cloud SSO Setup with AD FS
HCP Terraform allows organizations to configure single sign-on using the SAML 2.0 protocol as an alternative to traditional user management. You can use any Identity Provider 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 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.
Gather Information from AD FS
First, you need to collect the token-signing certificate and the metadata URL from your AD FS server.
Export the token-signing certificate.
In the AD FS console, expand the Service object and navigate to the Certificates section.
Right-click the Token-signing certificate and select View Certificate.
Go to the Details tab and click Copy to File....
Follow the export wizard instructions, choosing the Base-64 encoded X.509 (.CER) format when prompted.
Locate the Federation Metadata URL.
In the AD FS console, expand the Service object and go to the Endpoints section.
Find the URL in the Metadata section for Federation Metadata
Duo Single Sign-On for Terraform Cloud
As business applications move from on-premises to cloud hosted solutions, users experience password fatigue due to disparate logons for different applications. Single sign-on technologies seek to unify identities across systems and reduce the number of different credentials a user has to remember or input to gain access to resources.
While SSO is convenient for users, it presents new security challenges. If a user's primary password is compromised, attackers may be able to gain access to multiple resources. In addition, as sensitive information makes its way to cloud-hosted services it is even more important to secure access by implementing two-factor authentication and zero-trust policies.
About Duo Single Sign-On
Duo Single Sign-On is our cloud-hosted SSO product which layers Duo's strong authentication and flexible policy engine on top of Terraform Cloud logins. Duo Single Sign-On acts as an identity provider, authenticating your users using existing on-premises Active Directory or another SSO IdP. Duo SSO prompts users for two-factor authentication and performs endpoint assessment and verification before permitting access to Terraform Cloud.
Duo Single Sign-On is available in Duo Premier, Duo Advantage, and Duo Essentials plans, which also include the ability to define policies that enforce unique controls for each individual SSO application
Enable Terraform Cloud for SSO with Duo
Log into your Terraform Cloud account as an administrative user.
In the left menu sidebar, click Settings.
In the left menu sidebar, scroll down to "Security" and click SSO.
Click Setup SSO.
Click the SAML radio button and then click Next.
Return to the Duo Admin Panel. Copy the Metadata URL and paste it into the Terraform Cloud Metadata URL required field under "SAML configuration".
In your Terraform Cloud account page under "Management settings", type Email into the Username Attribute field.
Click Save settings.
In the "SSO" page, scroll down to the "Terraform Cloud" section. Copy the Entity ID Audience and paste it in the Duo Admin Panel Entity ID Audience field.
In the Duo Admin Panel, scroll to the bottom of the page and click Save.
Return to your Terraform Cloud account page. Under "SAML", click Test to test your connection. You will be redirected to Duo Single Sign-On to begin authentication.
After the test is complete, under "SAML", click Enable. Click Enable SAML in the pop-up window.
Group Mapping with Duo
You have the option to map Duo groups to different roles in Terraform Cloud
Log into your Terraform Cloud account as an administrative user.
In the left menu sidebar, click Settings.
In the left menu sidebar, scroll down to "Security" and click SSO.
At the top of the "SSO" page, copy the team name and paste it into the Duo Admin Panel Terraform Cloud Groups field.
Select the applicable Duo group from the Duo groups drop-down menu.
Scroll to the bottom of the page and click Save.
Microsoft Entra SSO Configuration
Configure and test Microsoft Entra SSO with Terraform Cloud using a test user called B.Simon. For SSO to work, you need to establish a link relationship between a Microsoft Entra user and the related user in Terraform Cloud.
To configure and test Microsoft Entra SSO with Terraform Cloud, perform the following steps:
Configure Microsoft Entra SSO - to enable your users to use this feature.
Create a Microsoft Entra test user - to test Microsoft Entra single sign-on with B.Simon.
Assign the Microsoft Entra test user - to enable B.Simon to use Microsoft Entra single sign-on.
Configure Terraform Cloud SSO - to configure the single sign-on settings on application side.
Create Terraform Cloud test user - to have a counterpart of B.Simon in Terraform Cloud that's linked to the Microsoft Entra representation of user.
Test SSO - to verify whether the configuration works.
Follow these steps to enable Microsoft Entra SSO.
Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.
Browse to Entra ID > Enterprise apps > Terraform Cloud > Single sign-on.
On the Select a single sign-on method page, select SAML.
On the Set up single sign-on with SAML page, select the pencil icon for Basic SAML Configuration to edit the settings.
On the Basic SAML Configuration section, if you wish to configure the application in IDP initiated mode, perform the following steps:
SSO Account Behavior Summary
| Scenario | Behavior |
|---|---|
| First SSO sign-in | User must create new Terraform Cloud account with SSO email as username or link to existing account |
| Non-owner member access | Must sign in via SSO to access SSO-enabled organization |
| Owner member access | Can access via username and password for troubleshooting |
| Disable SSO or downgrade tier | Members can continue to access organization using Terraform Cloud usernames and passwords |
| Cross organization access | SSO user accounts remain normal Terraform Cloud user accounts and can be used with other organizations via username and password |
Conclusion
Terraform Cloud single sign-on centralizes identity management through SAML 2.0 federation while preserving normal user account behavior outside the SSO-enabled organization. The architecture requires explicit linking of an SSO identity to a Terraform Cloud user account on first use, and enforces SSO sign-in for all non-owner members once enabled. Owners retain username and password access for operational recovery.
Implementation varies by identity provider. AD FS requires collection of the token-signing certificate in Base-64 encoded X.509 format and the Federation Metadata URL from the Service object endpoints. Duo Single Sign-On adds layered two-factor authentication and endpoint verification, with configuration steps involving Metadata URL exchange, Username Attribute set to Email, Entity ID Audience mapping, testing the connection, and optional group mapping to Terraform Cloud teams. Microsoft Entra SSO follows a standard Enterprise Apps SAML workflow with a test user such as B.Simon, assignment, and a link between the Entra user and the Terraform Cloud counterpart.
All configurations share the core SAML 2.0 exchange and the requirement that organizations operate on the Business tier for SSO. Disabling SSO or downgrading the tier restores username and password access for all members, providing a reversible control plane for identity management.