Link a user account for single sign-on

You have an SSO identity for every SSO-enabled HCP Terraform organization. HCP Terraform links each SSO identity to a single HCP Terraform user account. This link determines which account you can use to access each organization.

You can add and remove SSO identity links for all providers, including Microsoft Entra ID, Okta, and SAML.

Add SSO Identity Link

The first time you sign in to an organization using single sign-on (SSO), HCP Terraform links your SSO identity to your user account. After HCP Terraform creates this link, you must use that account to access the organization through SSO. You may link your SSO identity from an active login session or from the organization SSO sign-in page.

Linking SSO identity from an active login session

To link your SSO identity to your HCP Terraform user account from an active login session, you must be invited to or an active member of the organization in HCP Terraform. When you have been invited or added to the organization, sign into HCP Terraform with an account that does not have an SSO identity. Next, select the SSO organization from the Choose an organization drop-down in the menu bar. Click the Authorize button, then complete SSO authentication.

Once you successfully authenticate with your SSO provider, HCP Terraform links your SSO identity to your HCP Terraform account.

Linking SSO identity from the Organization SSO sign-in page

To link your SSO identity to your HCP Terraform user account from the Organization sign-in page, if your SSO identity is not yet linked:

1. Enter your organization name and click the Continue button.
2. Authenticate with your identity provider (IdP). After you have authenticated with your IdP, HCP Terraform displays the Link SSO to HCP Terraform step.
3. Enter the email address or username of the HCP Terraform account you want to link to your SSO identity.

After you enter the email address or username of your HCP Terraform account, HCP Terraform prompts you based on the following conditions:

• If the email address or username belongs to an account that is already linked to a HashiCorp Cloud Platform (HCP) account, HCP Terraform prompts you to sign in through HCP to complete the link. Refer to Linked HCP and HCP Terraform Accounts for more details.
• If the email address or username belongs to an existing HCP Terraform account that is not linked to an HCP account, HCP Terraform prompts you to enter your HCP Terraform account password to complete the link to your SSO identity.
• If the email address or username is not associated with any HCP Terraform account, HCP Terraform prompts you to create a new account. After you have created a new account, HCP Terraform links that account to your SSO identity.

What happens next

If SSO linking succeeds, you’re signed in, granted access to the organization, and your SSO identity is permanently linked to your account. Future SSO sign-ins use this identity automatically.

If SSO linking fails, HCP Terraform will display an error message. Your HCP Terraform account will not have access to the organization.

Change SSO Identity Link

HCP Terraform shows an error if you try to log in to an SSO-enabled organization with a different user account than the one linked to your SSO identity. To change this SSO identity link:

1. Sign in to HCP Terraform using the linked account.
2. Remove the SSO identity link from the current account.
3. Sign out of HCP Terraform.
4. Log in and add an SSO identity link to the desired account.

Remove SSO Identity Link

To unlink an SSO identity from an HCP Terraform account:

1. Sign in with SSO to the linked account.
2. Click your user icon and select Account Settings. Your Profile page appears.
3. Click SSO in the left navigation bar. The SSO page appears, showing a list of all of the SSO identities associated with this account.
4. Click the ellipses (...) next to the association you want to unlink and select Unlink SSO identity. The Unlink SSO identity box appears.
5. Click Unlink SSO identity.

The SSO association is now unlinked and removed from the SSO list. The organization is still available in the Choose an organization menu, but HCP Terraform will prompt you to log into that organization through SSO before you can access it.