terraform page title Microsoft Entra ID Single Sign on Terraform Cloud The Microsoft Entra ID previously Azure Active Directory SSO integration currently supports the following SAML features Single Sign on Microsoft Entra ID Learn how to configure single sign on with Microsoft Entra ID previously Entra active directory tfc only true

Answer:
---
page_title: Microsoft Entra ID - Single Sign-on - Terraform Cloud
tfc_only: true
description: >-
  Learn how to configure single sign-on with Microsoft Entra ID (previously Entra active directory).
---

# Single Sign-on: Microsoft Entra ID

The Microsoft Entra ID (previously Azure Active Directory) SSO integration currently supports the following SAML features:

- Service Provider (SP) initiated SSO
- Identity Provider (IdP) initiated SSO
- Just-in-Time Provisioning

For more information on the listed features, visit the [Microsoft Entra ID SAML Protocol Documentation](https://learn.microsoft.com/en-us/entra/identity-platform/single-sign-on-saml-protocol).

## Configuration (Microsoft Entra ID)

1. Sign in to the Entra portal.
1. On the left navigation pane, select the **Microsoft Entra ID** service.
1. Navigate to **Enterprise Applications** and then select **All Applications**.
1. To add new application, select **New application**.
1. In the **Add from the gallery** section, type **Terraform Cloud** in the search box.
1. Select **Terraform Cloud** from results panel and then add the app. Wait a few seconds while the app is added to your tenant.
1. On the **Terraform Cloud** application integration page, find the **Manage** section and select **single sign-on**.
1. On the **Select a single sign-on method** page, select **SAML**.
1. In the SAML Signing Certificate section (you may need to refresh the page) copy the **App Federation Metadata Url**.

## Configuration (HCP Terraform)

1. Visit your organization settings page and click "SSO".

1. Click "Setup SSO".

   ![sso-setup](/img/docs/setup.png)

1. Select "Microsoft Entra ID" and click "Next".

   ![sso-wizard-choose-provider-entra](/img/docs/wizard-choose-provider-entra.png)

1. Provide your App Federation Metadata URL.

   ![sso-wizard-configure-settings-entra](/img/docs/wizard-configure-settings-entra.png)

1. Save, and you should see a completed Terraform Cloud SAML configuration.

1. Copy Entity ID and Reply URL.

## Configuration (Microsoft Entra ID)

1. In the Entra portal, on the **Terraform Cloud** application integration page, find the **Manage** section and select **single sign-on**.
1. On the **Select a single sign-on method** page, select **SAML**.
1. On the **Set up single sign-on with SAML** page, click the edit/pen icon for **Basic SAML Configuration** to edit the settings.
   1. In the **Identifier** text box, paste the **Entity ID**.
   1. In the **Reply URL** text box, paste the **Reply URL**.
   1. For Service Provider initiated SSO, type `https://app.terraform.io/session` in the **Sign-On URL** text box. Otherwise, leave the box blank.
   1. Select **Save**.
1. On the **Single sign-on** page, download the `Certificate (Base64)` file from under **SAML Signing Certificate**.
1. In the app's overview page, find the **Manage** section and select **Users and groups**.
1. Select **Add user**, then select **Users and groups** in the **Add Assignment** dialog.
1. In the **Users and groups** dialog, select your user from the Users list, then click the **Select** button at the bottom of the screen.
1. If you are expecting a role to be assigned to the users, you can select it from the **Select a role** dropdown. If no role has been set up for this app, you see "Default Access" role selected.
1. In the **Add Assignment** dialog, click the **Assign** button.

## Configuration (HCP Terraform)
To edit your Entra SSO configuration settings:

   1. Go to **Public Certificate**.
   1. Paste the contents of the SAML Signing Certificate you downloaded from Microsoft Entra ID.
   1. Save Settings.
1. [Verify](/terraform/cloud-docs/users-teams-organizations/single-sign-on/testing) your settings and click "Enable".

1. Your Entra SSO configuration is complete and ready to [use](/terraform/cloud-docs/users-teams-organizations/single-sign-on#signing-in-with-sso).

   ![sso-settings](/img/docs/settings-entra.png)

## Team and Username Attributes

To configure team management in your Microsoft Entra ID application:

1. Navigate to the single sign-on page.
1. Edit step 2, **User Attributes & Claims**.
1. Add a new group claim.
1. In **Group Claims**, select **Security Groups**.
1. In the **Source Attribute** field, select either **sAMAccountName** to use account names or **Group ID** to use group UUIDs.
1. Check **Customize the name of the group claim**.
1. Set **Name (required)** to "MemberOf" and leave the namespace field blank.

-> **Note:** When you configure Microsoft Entra ID to use Group Claims, it provides Group UUIDs instead of human readable names in its SAML assertions. We recommend [configuring SSO Team IDs](/terraform/cloud-docs/users-teams-organizations/single-sign-on#team-names-and-sso-team-ids) for your HCP Terraform teams to match these Entra Group UUIDs.

If you plan to use SAML to set usernames in your Microsoft Entra ID application:

1. Navigate to the single sign-on page.
1. Edit step 2, **User Attributes & Claims.**
   We recommend naming the claim "username", leaving the namespace blank, and sourcing `user.displayname` or `user.mailnickname` as a starting point. If you have a Terraform Enterprise account, you can source `user.mail` or `user.userprincipalname`. Note that HCP Terraform usernames only allow lowercase letters, numbers, and dashes.

If you namespaced any of your claims, then Microsoft Entra ID passes the attribute name using the format `<claim_namespace/claim_name>`. Consider this format when setting team and username attribute names.

## Troubleshooting the SAML assertion
[Use this guide](https://support.hashicorp.com/hc/en-us/articles/1500005371682-Capturing-a-SAML-Assertion) to verify and validate the claims being sent in the SAML response.

page title  Microsoft Entra ID   Single Sign on   Terraform Cloud tfc only  true description       Learn how to configure single sign on with Microsoft Entra ID  previously Entra active directory          Single Sign on  Microsoft Entra ID  The Microsoft Entra ID  previously Azure Active Directory  SSO integration currently supports the following SAML features     Service Provider  SP  initiated SSO   Identity Provider  IdP  initiated SSO   Just in Time Provisioning  For more information on the listed features  visit the  Microsoft Entra ID SAML Protocol Documentation  https   learn microsoft com en us entra identity platform single sign on saml protocol       Configuration  Microsoft Entra ID   1  Sign in to the Entra portal  1  On the left navigation pane  select the   Microsoft Entra ID   service  1  Navigate to   Enterprise Applications   and then select   All Applications    1  To add new application  select   New application    1  In the   Add from the gallery   section  type   Terraform Cloud   in the search box  1  Select   Terraform Cloud   from results panel and then add the app  Wait a few seconds while the app is added to your tenant  1  On the   Terraform Cloud   application integration page  find the   Manage   section and select   single sign on    1  On the   Select a single sign on method   page  select   SAML    1  In the SAML Signing Certificate section  you may need to refresh the page  copy the   App Federation Metadata Url        Configuration  HCP Terraform   1  Visit your organization settings page and click  SSO    1  Click  Setup SSO         sso setup   img docs setup png   1  Select  Microsoft Entra ID  and click  Next         sso wizard choose provider entra   img docs wizard choose provider entra png   1  Provide your App Federation Metadata URL        sso wizard configure settings entra   img docs wizard configure settings entra png   1  Save  and you should see a completed Terraform Cloud SAML configuration   1  Copy Entity ID and Reply URL      Configuration  Microsoft Entra ID   1  In the Entra portal  on the   Terraform Cloud   application integration page  find the   Manage   section and select   single sign on    1  On the   Select a single sign on method   page  select   SAML    1  On the   Set up single sign on with SAML   page  click the edit pen icon for   Basic SAML Configuration   to edit the settings     1  In the   Identifier   text box  paste the   Entity ID       1  In the   Reply URL   text box  paste the   Reply URL       1  For Service Provider initiated SSO  type  https   app terraform io session  in the   Sign On URL   text box  Otherwise  leave the box blank     1  Select   Save    1  On the   Single sign on   page  download the  Certificate  Base64   file from under   SAML Signing Certificate    1  In the app s overview page  find the   Manage   section and select   Users and groups    1  Select   Add user    then select   Users and groups   in the   Add Assignment   dialog  1  In the   Users and groups   dialog  select your user from the Users list  then click the   Select   button at the bottom of the screen  1  If you are expecting a role to be assigned to the users  you can select it from the   Select a role   dropdown  If no role has been set up for this app  you see  Default Access  role selected  1  In the   Add Assignment   dialog  click the   Assign   button      Configuration  HCP Terraform  To edit your Entra SSO configuration settings      1  Go to   Public Certificate       1  Paste the contents of the SAML Signing Certificate you downloaded from Microsoft Entra ID     1  Save Settings  1   Verify   terraform cloud docs users teams organizations single sign on testing  your settings and click  Enable    1  Your Entra SSO configuration is complete and ready to  use   terraform cloud docs users teams organizations single sign on signing in with sso         sso settings   img docs settings entra png      Team and Username Attributes  To configure team management in your Microsoft Entra ID application   1  Navigate to the single sign on page  1  Edit step 2    User Attributes   Claims     1  Add a new group claim  1  In   Group Claims    select   Security Groups      1  In the   Source Attribute   field  select either   sAMAccountName   to use account names or   Group ID   to use group UUIDs   1  Check   Customize the name of the group claim     1  Set   Name  required    to  MemberOf  and leave the namespace field blank        Note    When you configure Microsoft Entra ID to use Group Claims  it provides Group UUIDs instead of human readable names in its SAML assertions  We recommend  configuring SSO Team IDs   terraform cloud docs users teams organizations single sign on team names and sso team ids  for your HCP Terraform teams to match these Entra Group UUIDs   If you plan to use SAML to set usernames in your Microsoft Entra ID application   1  Navigate to the single sign on page  1  Edit step 2    User Attributes   Claims         We recommend naming the claim  username   leaving the namespace blank  and sourcing  user displayname  or  user mailnickname  as a starting point  If you have a Terraform Enterprise account  you can source  user mail  or  user userprincipalname   Note that HCP Terraform usernames only allow lowercase letters  numbers  and dashes   If you namespaced any of your claims  then Microsoft Entra ID passes the attribute name using the format   claim namespace claim name    Consider this format when setting team and username attribute names      Troubleshooting the SAML assertion  Use this guide  https   support hashicorp com hc en us articles 1500005371682 Capturing a SAML Assertion  to verify and validate the claims being sent in the SAML response


terraform Single Sign on SSO and more page title Single Sign on HCP Terraform Learn how single sign on SSO works in HCP Terraform how to sign in with tfc only true

Answer:
---
page_title: Single Sign-on - HCP Terraform
description: >-
  Learn how single sign-on (SSO) works in HCP Terraform, how to sign in with
  SSO, and more.
tfc_only: true
---

# Single Sign-on

~> **Important:** This page is about configuring single sign-on in HCP Terraform. Terraform Enterprise's single sign-on is configured differently. If you administer a Terraform Enterprise instance, see [Terraform Enterprise: SAML Configuration](/terraform/enterprise/saml/configuration).

HCP Terraform allows organizations to configure SAML single sign-on (SSO), an alternative to traditional user management.  SSO gives owners more control to secure accessibility to your organization’s [Projects](/terraform/cloud-docs/projects/manage), [Workspaces](/terraform/cloud-docs/workspaces), and [Managed Resources](/terraform/cloud-docs/users-teams-organizations/organizations#managed-resources). By using SSO, your organization can centralize management of users for HCP Terraform and other Software-as-a-Service (SaaS) vendors, providing greater accountability and security for an organization's identity and user management.

## Supported Identity Providers (IdPs)

Select your preferred provider to learn more about what is supported for that provider and how to configure SSO for it.

* [Microsoft Entra ID](/terraform/cloud-docs/users-teams-organizations/single-sign-on/entra-id)
* [Okta](/terraform/cloud-docs/users-teams-organizations/single-sign-on/okta)
* [SAML](/terraform/cloud-docs/users-teams-organizations/single-sign-on/saml)

## How SSO Works

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. (Owners of an SSO-enabled organization can still access the organization through username and password, to enable fixing problems with SSO.)

### SSO Identities and HCP Terraform User Accounts

SSO does not automatically provision HCP Terraform user accounts. The first time you sign in with SSO, you must either provide a password to create a new HCP Terraform user account (using your SSO email address as the username), or link your SSO identity to an existing HCP Terraform user account. Once the SSO identity is linked, you can only log in to that organization using the linked account. You must [remove the SSO link](/terraform/cloud-docs/users-teams-organizations/single-sign-on/linking-user-account#remove-sso-identity-link) if you want to access the organization with a different user account.

If an organization's owners disable SSO, all members can continue to access the organization using their HCP Terraform or HashiCorp Cloud Platform credentials.

### Enforced Access Policy for HCP Terraform Resources

As a non-owner, when you attempt to access an organization that has SSO configured, you will be redirected to the organization's SAML IdP to authenticate and authorize access using your SAML IdP credentials before you can access the organization's [Projects](/terraform/cloud-docs/projects/manage), [Workspaces](/terraform/cloud-docs/workspaces), and [Managed Resources](/terraform/cloud-docs/users-teams-organizations/organizations#managed-resources).

Owners of an SSO-enabled organization can still access the organization's resources through their HCP Terraform credentials or their HCP credentials (if linked to their HCP Terraform account). This is to enable a workaround to problems such as your IdP becoming unavailable, lost access to your MFA or IdP credentials, or other authentication issues.

<Note>

HCP Terraform users are able to use their single HCP Terraform account to access resources in different organizations, however, SAML SSO does not authorize access to:
- Account Settings (such as to manage 2FA or generate/revoke User API tokens)
- Other organizations with SSO configured with a different SAML IdP.  You will need to authenticate to each configured IdP separately.
- Other organizations where SSO is not configured.

</Note>

In order to access these resources, you may be asked to “step-up” authentication using your HCP Terraform or HCP credentials. In most situations, a step-up HCP Terraform or HCP authentication login prompt will be required immediately after SSO authentication so that HCP Terraform can establish a broad user [session](/terraform/cloud-docs/users-teams-organizations/users#sessions) and to check access and authorization to different resources in HCP Terraform.

The below diagram explains the the access enforcement policy and the authentication required for an HCP Terraform user account to access different resources in HCP Terraform:

![Screenshot: a diagram of resource access in HCP Terraform with both SSO and non-SSO authentication](/img/docs/tfc-sso-auth.png)

## Signing in with SSO

1. Visit <https://app.terraform.io> and sign out if you're signed in.

1. Click "Sign in via SSO".

1. Provide your organization name and click **Next"**.

1. If you've signed in to HCP Terraform 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. Use the links below the account creation form if you want to link your SSO identity to an existing account, then fill out and submit the relevant form.

1. You will be redirected to your SSO identity provider. Authenticate your account as necessary.

1. You are now signed in to HCP Terraform.

## Configuring SSO in HCP Terraform Free Edition

SSO is available to all HCP Terraform organizations, but is configured and managed differently in HCP Terraform Free Edition because Team Management is only available in HCP Terraform Standard and Plus Editions.

In HCP Terraform Free Edition organizations, after you successfully configure SSO, HCP Terraform automatically creates a team named `sso` and adds all current members of the `owners` team into it. In the Free Edition, you cannot modify the organization-level permissions for both the `owners` and `sso` teams. These teams grant every member full administrative access to the organization, projects, workspaces, and managed resources.

After configuring SSO access, review the `owners` team membership. Members of the `owners` team have permission to bypass SSO in the event that your Identity Provider (IDP) is unavailable to service authentication requests, for example due to an IDP service outage, an administrator forgot their SSO credentials, or lost access to their software authenticator. An owner can use their HCP Terraform or HashiCorp Cloud Platform credentials (if linked) to bypass HCP Terraform SSO authentication at any time.

To encourage least privilege practices, HCP Terraform prompts the user who successfully configures SSO to optionally remove other users from the owners group.

## Managing Owners and SSO Team Membership in the Free Edition

The Team Management feature set is available in HCP Terraform Standard and Plus Editions only. Inviting users to any Free Edition organization will add them to the `owners` team but not the `sso` team. Review the following to assign the proper team membership between the two teams.

For new users new to HCP Terraform
- **Assign new users to the `owners` team** by inviting the user to the organization.
- **Assign new users to the `sso` team** by asking the user to login directly to the HCP Terraform organization via the SSO authentication login.

For managing existing users permissions:
- **Assign existing users from the `sso` team to the `owners` team:** Remove the user from the organization. Re-invite the user.
- **Assign existing users from the `owners` team to the `sso` team:** Remove the user from the organization.  Ask the user to sign in via SSO authentication login directly.

## Managing Team Membership Through SSO

HCP Terraform can automatically add users to teams based on their SAML assertion, so you can manage team membership in your directory service.

To enable team membership mapping:

1. Click **Settings** in the navigation bar and then click **SSO** in the sidebar. The SSO configuration page appears.
1. Toggle the **Enable team management to customize your team attribute**.

When team management is enabled, you can configure which SAML attribute in the SAMLResponse will control team membership. This defaults to the `MemberOf` attribute. The expected format of the corresponding `AttributeValue` in the SAMLResponse is a either a string containing a comma-separated list of teams, or separate `AttributeValue` items specifying teams.

When users log in through SAML, Terraform automatically adds them to the teams included in their assertion and automatically removes them from teams that are not included in their assertion. This automatic mapping overrides any manually set team memberships. Each time the user logs in, their team membership is adjusted to match their SAML assertion.

HCP Terraform ignores team names that do not exactly match existing teams and will not create new teams from those listed in the assertion. If the chosen SAML attribute is not provided in the SAMLResponse, Terraform assigns users to a default team named `sso` and does not remove them from any existing teams.

It is not possible to assign users to the `owners` team through this attribute.

## Team Names and SSO Team IDs

HCP Terraform expects the team names in the team membership SAML attribute to exactly match team names or configured SSO team IDs stored in HCP Terraform. Values are case sensitive and literal. HCP Terraform does not process the value passed by the IdP. As a result, you cannot use values such as the full distinguished name (DN).

You can configure SSO Team IDs in the organization's **Teams** page. If an SSO Team ID is configured, HCP Terraform will attempt to match the chosen SAML attribute against both the team name and the SSO Team ID when mapping users to teams. You may want to create an SSO Team ID if the team membership SAML attribute is not human readable and is not used as the team's name in HCP Terraform.

SSO Team IDs are particularly helpful if your SSO or Microsoft Entra ID provider restricts the `MemberOf` attribute in its SAML responses to Group UUIDs, rather than human readable group names. Setting the SSO Team ID allows you to maintain human readable team names in HCP Terraform, while still managing team membership through SSO or Microsoft Entra ID.

## NameID Format

HCP Terraform requires that the NameID format in the SAML response be set to `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` with a valid email address being provided as the value for this attribute.

page title  Single Sign on   HCP Terraform description       Learn how single sign on  SSO  works in HCP Terraform  how to sign in with   SSO  and more  tfc only  true        Single Sign on       Important    This page is about configuring single sign on in HCP Terraform  Terraform Enterprise s single sign on is configured differently  If you administer a Terraform Enterprise instance  see  Terraform Enterprise  SAML Configuration   terraform enterprise saml configuration    HCP Terraform allows organizations to configure SAML single sign on  SSO   an alternative to traditional user management   SSO gives owners more control to secure accessibility to your organization s  Projects   terraform cloud docs projects manage    Workspaces   terraform cloud docs workspaces   and  Managed Resources   terraform cloud docs users teams organizations organizations managed resources   By using SSO  your organization can centralize management of users for HCP Terraform and other Software as a Service  SaaS  vendors  providing greater accountability and security for an organization s identity and user management      Supported Identity Providers  IdPs   Select your preferred provider to learn more about what is supported for that provider and how to configure SSO for it      Microsoft Entra ID   terraform cloud docs users teams organizations single sign on entra id     Okta   terraform cloud docs users teams organizations single sign on okta     SAML   terraform cloud docs users teams organizations single sign on saml      How SSO Works  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   Owners of an SSO enabled organization can still access the organization through username and password  to enable fixing problems with SSO        SSO Identities and HCP Terraform User Accounts  SSO does not automatically provision HCP Terraform user accounts  The first time you sign in with SSO  you must either provide a password to create a new HCP Terraform user account  using your SSO email address as the username   or link your SSO identity to an existing HCP Terraform user account  Once the SSO identity is linked  you can only log in to that organization using the linked account  You must  remove the SSO link   terraform cloud docs users teams organizations single sign on linking user account remove sso identity link  if you want to access the organization with a different user account   If an organization s owners disable SSO  all members can continue to access the organization using their HCP Terraform or HashiCorp Cloud Platform credentials       Enforced Access Policy for HCP Terraform Resources  As a non owner  when you attempt to access an organization that has SSO configured  you will be redirected to the organization s SAML IdP to authenticate and authorize access using your SAML IdP credentials before you can access the organization s  Projects   terraform cloud docs projects manage    Workspaces   terraform cloud docs workspaces   and  Managed Resources   terraform cloud docs users teams organizations organizations managed resources    Owners of an SSO enabled organization can still access the organization s resources through their HCP Terraform credentials or their HCP credentials  if linked to their HCP Terraform account   This is to enable a workaround to problems such as your IdP becoming unavailable  lost access to your MFA or IdP credentials  or other authentication issues    Note   HCP Terraform users are able to use their single HCP Terraform account to access resources in different organizations  however  SAML SSO does not authorize access to    Account Settings  such as to manage 2FA or generate revoke User API tokens    Other organizations with SSO configured with a different SAML IdP   You will need to authenticate to each configured IdP separately    Other organizations where SSO is not configured     Note   In order to access these resources  you may be asked to  step up  authentication using your HCP Terraform or HCP credentials  In most situations  a step up HCP Terraform or HCP authentication login prompt will be required immediately after SSO authentication so that HCP Terraform can establish a broad user  session   terraform cloud docs users teams organizations users sessions  and to check access and authorization to different resources in HCP Terraform   The below diagram explains the the access enforcement policy and the authentication required for an HCP Terraform user account to access different resources in HCP Terraform     Screenshot  a diagram of resource access in HCP Terraform with both SSO and non SSO authentication   img docs tfc sso auth png      Signing in with SSO  1  Visit  https   app terraform io  and sign out if you re signed in   1  Click  Sign in via SSO    1  Provide your organization name and click   Next      1  If you ve signed in to HCP Terraform 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  Use the links below the account creation form if you want to link your SSO identity to an existing account  then fill out and submit the relevant form   1  You will be redirected to your SSO identity provider  Authenticate your account as necessary   1  You are now signed in to HCP Terraform      Configuring SSO in HCP Terraform Free Edition   SSO is available to all HCP Terraform organizations  but is configured and managed differently in HCP Terraform Free Edition because Team Management is only available in HCP Terraform Standard and Plus Editions   In HCP Terraform Free Edition organizations  after you successfully configure SSO  HCP Terraform automatically creates a team named  sso  and adds all current members of the  owners  team into it  In the Free Edition  you cannot modify the organization level permissions for both the  owners  and  sso  teams  These teams grant every member full administrative access to the organization  projects  workspaces  and managed resources     After configuring SSO access  review the  owners  team membership  Members of the  owners  team have permission to bypass SSO in the event that your Identity Provider  IDP  is unavailable to service authentication requests  for example due to an IDP service outage  an administrator forgot their SSO credentials  or lost access to their software authenticator  An owner can use their HCP Terraform or HashiCorp Cloud Platform credentials  if linked  to bypass HCP Terraform SSO authentication at any time   To encourage least privilege practices  HCP Terraform prompts the user who successfully configures SSO to optionally remove other users from the owners group      Managing Owners and SSO Team Membership in the Free Edition  The Team Management feature set is available in HCP Terraform Standard and Plus Editions only  Inviting users to any Free Edition organization will add them to the  owners  team but not the  sso  team  Review the following to assign the proper team membership between the two teams   For new users new to HCP Terraform     Assign new users to the  owners  team   by inviting the user to the organization      Assign new users to the  sso  team   by asking the user to login directly to the HCP Terraform organization via the SSO authentication login   For managing existing users permissions      Assign existing users from the  sso  team to the  owners  team    Remove the user from the organization  Re invite the user      Assign existing users from the  owners  team to the  sso  team    Remove the user from the organization   Ask the user to sign in via SSO authentication login directly      Managing Team Membership Through SSO  HCP Terraform can automatically add users to teams based on their SAML assertion  so you can manage team membership in your directory service   To enable team membership mapping   1  Click   Settings   in the navigation bar and then click   SSO   in the sidebar  The SSO configuration page appears  1  Toggle the   Enable team management to customize your team attribute     When team management is enabled  you can configure which SAML attribute in the SAMLResponse will control team membership  This defaults to the  MemberOf  attribute  The expected format of the corresponding  AttributeValue  in the SAMLResponse is a either a string containing a comma separated list of teams  or separate  AttributeValue  items specifying teams   When users log in through SAML  Terraform automatically adds them to the teams included in their assertion and automatically removes them from teams that are not included in their assertion  This automatic mapping overrides any manually set team memberships  Each time the user logs in  their team membership is adjusted to match their SAML assertion   HCP Terraform ignores team names that do not exactly match existing teams and will not create new teams from those listed in the assertion  If the chosen SAML attribute is not provided in the SAMLResponse  Terraform assigns users to a default team named  sso  and does not remove them from any existing teams   It is not possible to assign users to the  owners  team through this attribute      Team Names and SSO Team IDs  HCP Terraform expects the team names in the team membership SAML attribute to exactly match team names or configured SSO team IDs stored in HCP Terraform  Values are case sensitive and literal  HCP Terraform does not process the value passed by the IdP  As a result  you cannot use values such as the full distinguished name  DN    You can configure SSO Team IDs in the organization s   Teams   page  If an SSO Team ID is configured  HCP Terraform will attempt to match the chosen SAML attribute against both the team name and the SSO Team ID when mapping users to teams  You may want to create an SSO Team ID if the team membership SAML attribute is not human readable and is not used as the team s name in HCP Terraform   SSO Team IDs are particularly helpful if your SSO or Microsoft Entra ID provider restricts the  MemberOf  attribute in its SAML responses to Group UUIDs  rather than human readable group names  Setting the SSO Team ID allows you to maintain human readable team names in HCP Terraform  while still managing team membership through SSO or Microsoft Entra ID      NameID Format  HCP Terraform requires that the NameID format in the SAML response be set to  urn oasis names tc SAML 1 1 nameid format emailAddress  with a valid email address being provided as the value for this attribute


terraform include tfc package callouts notifications mdx page title Manage team notifications Learn how to set up team notifications to notify team members on external systems whenever a particular action takes place Manage team notifications HCP Terraform can use webhooks to notify external systems about run progress change requests and other events Team notifications allow you to configure relevant alerts that notify teams you specify whenever a certain event occurs

Answer:
---
page_title: Manage team notifications
description: Learn how to set up team notifications to notify team members on external systems whenever a particular action takes place.
---

# Manage team notifications

HCP Terraform can use webhooks to notify external systems about run progress, change requests, and other events. Team notifications allow you to configure relevant alerts that notify teams you specify whenever a certain event occurs.

@include 'tfc-package-callouts/notifications.mdx'

You can configure an individual team notification to notify up to twenty teams. To set up notifications for teams using the API, refer to the [Notification API](/terraform/cloud-docs/api-docs/notification-configurations#team-notification-configuration).

## Requirements

-> **Note**: Team notifications are in public beta. All APIs and workflows are subject to change.

To configure team notifications, you need the [**Manage teams**](/terraform/cloud-docs/users-teams-organizations/permissions#manage-teams) permissions for the team for which you want to configure notifications.

## View notification configuration settings

To view your current team notifications, perform the following steps:

1. Navigate to your organization’s **Settings** page.
1. Select **Teams** in the sidebar navigation.
1. Select the team for which you want to view the notifications from your list of teams.
1. Select **Notifications** in the sidebar navigation.

HCP Terraform displays a list of any notification configurations you have set up. A notification configuration defines how and when you want to send notifications, and once you enable that configuration, it can send notifications.

### Update and enable notification configurations

Each notification configuration includes a brief overview of each configuration’s name, type, the events that can trigger the notification, and the last time the notification was triggered. Clicking on a notification configuration opens a page where you can perform the following actions:

* Enable your configuration to send notifications by toggling the switch.
* Delete a configuration by clicking **Delete notification**, then **Yes, delete notification configuration**.
* Test your notification’s configuration by clicking **Send test**.
* Click **Edit notification** to edit your notification configuration.

After creating a notification configuration, you can only edit the following aspects of that configuration:

1. The configuration’s name.
1. Whether this configuration notifies everyone on a team or specific members.
1. The workspace events that trigger notifications. You can choose from:
    * **All events** triggers a notification for every event in your workspace.
    * **No events** means that no workspace events trigger a notification.
    * **Only certain events** lets you specify which events trigger a notification.

After making any changes, click **Update notification** to save your changes.

## Create and configure a notification

To configure a new notification for a team or a user, perform the following steps:

1. Navigate to your organization’s **Settings** page.
1. Select **Teams** in the sidebar navigation.
1. Select the team you want to view the notifications for from your list of teams.
1. Select **Notifications** in the sidebar navigation.
1. Click **Create a notification**.

You must complete the following fields for all new notification configurations:

1. The **Destination** where HCP Terraform should deliver either a generic or a specifically formatted payload. Refer to [Notification payloads](#notification-payloads) for details.
1. The display **Name** for this notification configuration.
1. If you configure an email notification, you can optionally specify which **Email Recipients** will receive this notification.
1. If you choose to configure a webhook, you must also specify:
    * A **Webhook URL** for the destination of your webhook payload. Your URL must accept HTTP or HTTPS `POST` requests and be able to use the chosen payload type.
    * You can optionally configure a **Token** as an arbitrary secret string that HCP Terraform will use to sign its notification webhooks. Refer to [Notification authenticity](#notification-authenticity) for details. You cannot view the token after you save the notification configuration.
1. If you choose to specify either a **Slack** or **Microsoft Teams** notification, you must also configure your webhook URL for either service. For details, refer to Slack's documentation on [creating an incoming webhook](https://api.slack.com/messaging/webhooks#create_a_webhook) and Microsoft's documentation on [creating a workflow from a channel in teams](https://support.microsoft.com/en-us/office/creating-a-workflow-from-a-channel-in-teams-242eb8f2-f328-45be-b81f-9817b51a5f0e).
1. Specify which [**Workspace events**](#workspace-events) should trigger this notification.
1. After you finish configuring your notification, click **Create a notification**.

Note that if you are create an email notification, you must have [**Manage membership**](/terraform/cloud-docs/users-teams-organizations/permissions#manage-membership) permissions on a team to select users from that team as email recipients.

### Workspace events

HCP Terraform can send notifications for all workspace events, no workspace events, or specific events. The following events are available for you to specify:

| Event | Description |
| :---- | :---- |
| Change Requests | HCP Terraform will notify this team whenever someone creates a change request on a workspace to which this team has access. |

## Enable and verify a notification

To configure HCP Terraform to stop sending notifications for a notification configuration, disable the **Enabled** setting on a configuration's detail page .

HCP Terraform enables notifications for email configurations by default. Before enabling any webhook notifications, HCP Terraform attempts to verify the notification’s configuration by sending a test message. If the test succeeds, HCP Terraform enables the notification.

To verify a notification configuration, the destination must respond with a `2xx` HTTP code. If verification fails, HCP Terraform does not enable the configuration and displays an error message.

For successful and unsuccessful verifications, click the **Last Response** box to view more information about the verification results. You can also send additional test messages by clicking **Send a Test**.

## Notification Payloads

Notification payloads contain different attributes depending on the integration you specified when configuring that notification.

### Slack

Notifications to Slack contain the following information:

* Information about the change request, including the username and avatar of the person who created the change request.
* The event that triggered the notification and the time that event occurred.

### Microsoft Teams

Notifications to Microsoft Teams contain the following information:
* Information about the change request, including the username and avatar of the person who created the change request.
* The event that triggered the notification and the time that event occurred.

### Email

Email notifications contain the following information:
* Information about the change request, including the username and avatar of the person who created the change request.
* The event that triggered the notification and the time that event occurred.

### Generic

A generic notification contains information about the event that triggered it and the time that the event occurred. You can refer to the complete generic notification payload in the [API documentation](/terraform/cloud-docs/api-docs/notification-configurations#notification-payload).

You can use some of the values in the payload to retrieve additional information through the API, such as:
* The [workspace ID](/terraform/cloud-docs/api-docs/workspaces#list-workspaces)
* The [organization name](/terraform/cloud-docs/api-docs/organizations#show-an-organization)

## Notification Authenticity

Slack notifications use Slack's own protocols to verify HCP Terraform's webhook requests.

Generic notifications can include a signature to verify the request. For notification configurations that include a secret token, HCP Terraform's webhook requests include an `X-TFE-Notification-Signature` header containing an HMAC signature computed from the token using the SHA-512 digest algorithm. The notification’s receiving service is responsible for validating the signature. For more information and an example of how to validate the signature, refer to the [API documentation](/terraform/cloud-docs/api-docs/notification-configurations#notification-payload)

page title  Manage team notifications description  Learn how to set up team notifications to notify team members on external systems whenever a particular action takes place         Manage team notifications  HCP Terraform can use webhooks to notify external systems about run progress  change requests  and other events  Team notifications allow you to configure relevant alerts that notify teams you specify whenever a certain event occurs     include  tfc package callouts notifications mdx   You can configure an individual team notification to notify up to twenty teams  To set up notifications for teams using the API  refer to the  Notification API   terraform cloud docs api docs notification configurations team notification configuration       Requirements       Note    Team notifications are in public beta  All APIs and workflows are subject to change   To configure team notifications  you need the    Manage teams     terraform cloud docs users teams organizations permissions manage teams  permissions for the team for which you want to configure notifications      View notification configuration settings  To view your current team notifications  perform the following steps   1  Navigate to your organization s   Settings   page    1  Select   Teams   in the sidebar navigation    1  Select the team for which you want to view the notifications from your list of teams  1  Select   Notifications   in the sidebar navigation   HCP Terraform displays a list of any notification configurations you have set up  A notification configuration defines how and when you want to send notifications  and once you enable that configuration  it can send notifications        Update and enable notification configurations  Each notification configuration includes a brief overview of each configuration s name  type  the events that can trigger the notification  and the last time the notification was triggered  Clicking on a notification configuration opens a page where you can perform the following actions     Enable your configuration to send notifications by toggling the switch      Delete a configuration by clicking   Delete notification    then   Yes  delete notification configuration        Test your notification s configuration by clicking   Send test         Click   Edit notification   to edit your notification configuration   After creating a notification configuration  you can only edit the following aspects of that configuration   1  The configuration s name    1  Whether this configuration notifies everyone on a team or specific members    1  The workspace events that trigger notifications  You can choose from            All events   triggers a notification for every event in your workspace            No events   means that no workspace events trigger a notification            Only certain events   lets you specify which events trigger a notification   After making any changes  click   Update notification   to save your changes      Create and configure a notification   To configure a new notification for a team or a user  perform the following steps   1  Navigate to your organization s   Settings   page    1  Select   Teams   in the sidebar navigation    1  Select the team you want to view the notifications for from your list of teams    1  Select   Notifications   in the sidebar navigation    1  Click   Create a notification     You must complete the following fields for all new notification configurations   1  The   Destination   where HCP Terraform should deliver either a generic or a specifically formatted payload  Refer to  Notification payloads   notification payloads  for details    1  The display   Name   for this notification configuration    1  If you configure an email notification  you can optionally specify which   Email Recipients   will receive this notification    1  If you choose to configure a webhook  you must also specify           A   Webhook URL   for the destination of your webhook payload  Your URL must accept HTTP or HTTPS  POST  requests and be able to use the chosen payload type           You can optionally configure a   Token   as an arbitrary secret string that HCP Terraform will use to sign its notification webhooks  Refer to  Notification authenticity   notification authenticity  for details  You cannot view the token after you save the notification configuration    1  If you choose to specify either a   Slack   or   Microsoft Teams   notification  you must also configure your webhook URL for either service  For details  refer to Slack s documentation on  creating an incoming webhook  https   api slack com messaging webhooks create a webhook  and Microsoft s documentation on  creating a workflow from a channel in teams  https   support microsoft com en us office creating a workflow from a channel in teams 242eb8f2 f328 45be b81f 9817b51a5f0e     1  Specify which    Workspace events     workspace events  should trigger this notification    1  After you finish configuring your notification  click   Create a notification     Note that if you are create an email notification  you must have    Manage membership     terraform cloud docs users teams organizations permissions manage membership  permissions on a team to select users from that team as email recipients       Workspace events  HCP Terraform can send notifications for all workspace events  no workspace events  or specific events  The following events are available for you to specify     Event   Description                       Change Requests   HCP Terraform will notify this team whenever someone creates a change request on a workspace to which this team has access        Enable and verify a notification  To configure HCP Terraform to stop sending notifications for a notification configuration  disable the   Enabled   setting on a configuration s detail page     HCP Terraform enables notifications for email configurations by default  Before enabling any webhook notifications  HCP Terraform attempts to verify the notification s configuration by sending a test message  If the test succeeds  HCP Terraform enables the notification    To verify a notification configuration  the destination must respond with a  2xx  HTTP code  If verification fails  HCP Terraform does not enable the configuration and displays an error message   For successful and unsuccessful verifications  click the   Last Response   box to view more information about the verification results  You can also send additional test messages by clicking   Send a Test        Notification Payloads  Notification payloads contain different attributes depending on the integration you specified when configuring that notification       Slack  Notifications to Slack contain the following information     Information about the change request  including the username and avatar of the person who created the change request    The event that triggered the notification and the time that event occurred       Microsoft Teams  Notifications to Microsoft Teams contain the following information    Information about the change request  including the username and avatar of the person who created the change request    The event that triggered the notification and the time that event occurred       Email  Email notifications contain the following information    Information about the change request  including the username and avatar of the person who created the change request    The event that triggered the notification and the time that event occurred       Generic  A generic notification contains information about the event that triggered it and the time that the event occurred  You can refer to the complete generic notification payload in the  API documentation   terraform cloud docs api docs notification configurations notification payload    You can use some of the values in the payload to retrieve additional information through the API  such as    The  workspace ID   terraform cloud docs api docs workspaces list workspaces      The  organization name   terraform cloud docs api docs organizations show an organization      Notification Authenticity  Slack notifications use Slack s own protocols to verify HCP Terraform s webhook requests   Generic notifications can include a signature to verify the request  For notification configurations that include a secret token  HCP Terraform s webhook requests include an  X TFE Notification Signature  header containing an HMAC signature computed from the token using the SHA 512 digest algorithm  The notification s receiving service is responsible for validating the signature  For more information and an example of how to validate the signature  refer to the  API documentation   terraform cloud docs api docs notification configurations notification payload


terraform Manage teams You can grant team management abilities to members of teams with either one of the manage teams or manage organization access permissions Refer to Team Permissions terraform cloud docs users teams organizations permissions team permissions for details Learn how to manage team creation team deletion team membership and team access to workspaces projects and organizations page title Manage teams

Answer:
---
page_title: Manage teams
description: |-
 Learn how to manage team creation, team deletion, team membership, and team access to workspaces, projects, and organizations.
---

# Manage teams

You can grant team management abilities to members of teams with either one of the manage teams or manage organization access permissions. Refer to [Team Permissions](/terraform/cloud-docs/users-teams-organizations/permissions#team-permissions) for details.

[Organization owners](/terraform/cloud-docs/users-teams-organizations/teams#the-owners-team) can also create teams, assign team permissions, or view the full list of teams. Other users can view any teams marked as visible within the organization, plus any secret teams they are members of. Refer to [Team Visibility](#team-visibility) for details.

To manage teams, perform the following steps:

1. Click **Settings** and then click **Teams**. The **Team Management** page appears, containing a list of all teams within the organization.
1. Click a team to go to its settings page, which lists the team's settings and current members. Members that have [two-factor authentication](/terraform/cloud-docs/users-teams-organizations/2fa) enabled have a **2FA** badge.

You can manage a team on its settings page by adding or removing members, changing its visibility, and controlling access to workspaces, projects, and the organization.

## Create teams

To create a new team, perform the following steps:

1. Click **Settings** and then click **Teams**. The **Team Management** page appears, containing a list of all teams within the organization.
1. Enter a unique team **Name** and click **Create Team**. Team names can include numbers, letters, underscores (`_`), and hyphens (`-`).

The new team's settings page appears, where you can add new members and grant permissions.

## Delete teams

~> **Important:** Team deletion is permanent, and you cannot undo it.

To delete a team, perform the following steps:

1. Click **Settings**, then click **Teams**. The **Team Management** page appears, containing a list of all teams within the organization.
1. Click the team you want to delete to go to its settings page.
1. Click **Delete [team name]** at the bottom of the page. The **Deleting team "[team name]"** box appears.
1. Click **Yes, delete team** to permanently delete the team and all of its data from HCP Terraform.

## Manage team membership

Team structure often resembles your company's organizational structure.

### Add users

If the user is not yet in the organization, [invite them to join the organization](/terraform/cloud-docs/users-teams-organizations/organizations#users) and include a list of teams they should belong to in the invitation. Once the user accepts the invitation, HCP Terraform automatically adds them to those teams.

To add a user that is already in the organization:

1. Click **Settings** and then click **Teams**. The **Team Management** page appears, containing a list of all teams within the organization.
1. Click the team to go to its settings page.
1. Choose a user under **Add a New Team Member**. Use the text field to filter the list by username or email.
1. Click the user to add them to the team. HCP Terraform now displays the user under **Members**.

### Remove users

To remove a user from a team:

1. Click **Settings** and then click **Teams**. The **Team Management** page appears, containing a list of all teams within the organization.
1. Click the team to go to its settings page.
1. Click **...** next to the user's name and choose **Remove from team** from the menu. HCP Terraform removes the user from the list of team members.

## Team visibility

The settings under **Visibility** allow you to  control who can see a team within the organization. To edit a team's visibility:

1. Click **Settings** and then click **Teams**. The **Team Management** page appears, containing a list of all teams within the organization.
1. Click the team to go to its settings page.
1. Enable one of the following settings:
   - **Visible:** Every user in the organization can see the team and its membership. Non-members have read-only access.
   - **Secret:** The default setting is that only team members and organization owners can view a team and its membership.

We recommend making the majority of teams visible to simplify workspace administration. Secret teams should only have
[organization-level permissions](/terraform/cloud-docs/users-teams-organizations/permissions#organization-permissions) since workspace admins cannot manage permissions for teams they cannot view.

## Manage workspace access

You can grant teams various permissions on workspaces. Refer to [Workspace Permissions](/terraform/cloud-docs/users-teams-organizations/permissions#workspace-permissions) for details.

HCP Terraform uses the most permissive permission level from your teams to determine what actions you can take on a particular resource. For example, if you belong to a team that only has permission to read runs for a workspace and another team with admin access to that workspace, HCP Terraform grants you admin access.

HCP Terraform grants the most permissive permissions regardless of whether an organization, project, team, or workspace set those permissions. For example, if a team has permission to read runs for a given workspace and has permission to manage that workspace through the organization, then members of that team can manage that workspace. Refer to [organization permissions](/terraform/cloud-docs/users-teams-organizations/permissions#organization-permissions) and [project permissions](/terraform/cloud-docs/users-teams-organizations/permissions#project-permissions) for additional information.

Another example is when a team has permission at the organization-level to read runs for all workspaces and admin access to a specific workspace. HCP Terraform grants the more permissive admin permissions to that workspace.

To manage team permissions on a workspace:

1. Go to the workspace and click **Settings > Team Access**. The **Team Access** page appears.
1. Click **Add team and permissions** to select a team and assign a pre-built or custom permission set.

## Manage project access

You can grant teams permissions to manage a project and the workspaces that belong to it. Refer to [Project Permissions](/terraform/cloud-docs/users-teams-organizations/permissions#project-permissions) for details.

## Manage organization access

Organization owners can grant teams permissions to manage policies, projects and workspaces, team and organization membership, VCS settings, private registry providers and modules, and policy overrides across an organization. Refer to [Organization Permissions](/terraform/cloud-docs/users-teams-organizations/permissions#organization-permissions) for details.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

page title  Manage teams description      Learn how to manage team creation  team deletion  team membership  and team access to workspaces  projects  and organizations          Manage teams  You can grant team management abilities to members of teams with either one of the manage teams or manage organization access permissions  Refer to  Team Permissions   terraform cloud docs users teams organizations permissions team permissions  for details    Organization owners   terraform cloud docs users teams organizations teams the owners team  can also create teams  assign team permissions  or view the full list of teams  Other users can view any teams marked as visible within the organization  plus any secret teams they are members of  Refer to  Team Visibility   team visibility  for details   To manage teams  perform the following steps   1  Click   Settings   and then click   Teams    The   Team Management   page appears  containing a list of all teams within the organization  1  Click a team to go to its settings page  which lists the team s settings and current members  Members that have  two factor authentication   terraform cloud docs users teams organizations 2fa  enabled have a   2FA   badge   You can manage a team on its settings page by adding or removing members  changing its visibility  and controlling access to workspaces  projects  and the organization      Create teams  To create a new team  perform the following steps   1  Click   Settings   and then click   Teams    The   Team Management   page appears  containing a list of all teams within the organization  1  Enter a unique team   Name   and click   Create Team    Team names can include numbers  letters  underscores        and hyphens         The new team s settings page appears  where you can add new members and grant permissions      Delete teams       Important    Team deletion is permanent  and you cannot undo it   To delete a team  perform the following steps   1  Click   Settings    then click   Teams    The   Team Management   page appears  containing a list of all teams within the organization  1  Click the team you want to delete to go to its settings page  1  Click   Delete  team name    at the bottom of the page  The   Deleting team   team name     box appears  1  Click   Yes  delete team   to permanently delete the team and all of its data from HCP Terraform      Manage team membership  Team structure often resembles your company s organizational structure       Add users  If the user is not yet in the organization   invite them to join the organization   terraform cloud docs users teams organizations organizations users  and include a list of teams they should belong to in the invitation  Once the user accepts the invitation  HCP Terraform automatically adds them to those teams   To add a user that is already in the organization   1  Click   Settings   and then click   Teams    The   Team Management   page appears  containing a list of all teams within the organization  1  Click the team to go to its settings page  1  Choose a user under   Add a New Team Member    Use the text field to filter the list by username or email  1  Click the user to add them to the team  HCP Terraform now displays the user under   Members         Remove users  To remove a user from a team   1  Click   Settings   and then click   Teams    The   Team Management   page appears  containing a list of all teams within the organization  1  Click the team to go to its settings page  1  Click         next to the user s name and choose   Remove from team   from the menu  HCP Terraform removes the user from the list of team members       Team visibility  The settings under   Visibility   allow you to  control who can see a team within the organization  To edit a team s visibility   1  Click   Settings   and then click   Teams    The   Team Management   page appears  containing a list of all teams within the organization  1  Click the team to go to its settings page  1  Enable one of the following settings         Visible    Every user in the organization can see the team and its membership  Non members have read only access         Secret    The default setting is that only team members and organization owners can view a team and its membership   We recommend making the majority of teams visible to simplify workspace administration  Secret teams should only have  organization level permissions   terraform cloud docs users teams organizations permissions organization permissions  since workspace admins cannot manage permissions for teams they cannot view      Manage workspace access  You can grant teams various permissions on workspaces  Refer to  Workspace Permissions   terraform cloud docs users teams organizations permissions workspace permissions  for details   HCP Terraform uses the most permissive permission level from your teams to determine what actions you can take on a particular resource  For example  if you belong to a team that only has permission to read runs for a workspace and another team with admin access to that workspace  HCP Terraform grants you admin access   HCP Terraform grants the most permissive permissions regardless of whether an organization  project  team  or workspace set those permissions  For example  if a team has permission to read runs for a given workspace and has permission to manage that workspace through the organization  then members of that team can manage that workspace  Refer to  organization permissions   terraform cloud docs users teams organizations permissions organization permissions  and  project permissions   terraform cloud docs users teams organizations permissions project permissions  for additional information    Another example is when a team has permission at the organization level to read runs for all workspaces and admin access to a specific workspace  HCP Terraform grants the more permissive admin permissions to that workspace   To manage team permissions on a workspace   1  Go to the workspace and click   Settings   Team Access    The   Team Access   page appears  1  Click   Add team and permissions   to select a team and assign a pre built or custom permission set      Manage project access  You can grant teams permissions to manage a project and the workspaces that belong to it  Refer to  Project Permissions   terraform cloud docs users teams organizations permissions project permissions  for details      Manage organization access  Organization owners can grant teams permissions to manage policies  projects and workspaces  team and organization membership  VCS settings  private registry providers and modules  and policy overrides across an organization  Refer to  Organization Permissions   terraform cloud docs users teams organizations permissions organization permissions  for details    permissions citation    intentionally unused   keep for maintainers


terraform Part 3 3 How to Move from Infrastructure as Code to Collaborative Infrastructure as Code Move to collaborative infrastructure as code workflows Learn about HCP Terraform s run environment create workspaces plan and create teams assign permissions and restrict non Terraform access page title Terraform Recommended Practices tfc only true Part 3 3 From Infrastructure as Code to Collaborative Infrastructure as Code

Answer:
---
page_title: >-
  Part 3.3: From Infrastructure as Code to Collaborative Infrastructure as Code
  - Terraform Recommended Practices
tfc_only: true
description: >-
  Move to collaborative infrastructure-as-code workflows. Learn about HCP Terraform's run environment, create workspaces, plan and create teams, assign permissions, and restrict non-Terraform access.
---

# Part 3.3: How to Move from Infrastructure as Code to Collaborative Infrastructure as Code

Using version-controlled Terraform configurations to manage key infrastructure eliminates a great deal of technical complexity and inconsistency. Now that you have the basics under control, you’re ready to focus on other problems.

Your next goals are to:

- Adopt consistent workflows for Terraform usage across teams
- Expand the benefits of Terraform beyond the core of engineers who directly edit Terraform code.
- Manage infrastructure provisioning permissions for users and teams.

[HCP Terraform](https://www.hashicorp.com/products/terraform/) is the product we’ve built to help you address these next-level problems. The following section describes how to start using it most effectively.

Note: If you aren’t already using mature Terraform code to manage a significant portion of your infrastructure, make sure you follow the steps in the previous section first.

## 1. Install or Sign Up for HCP Terraform

You have two options for using HCP Terraform: the SaaS hosted by HashiCorp, or a private instance you manage with Terraform Enterprise. If you have chosen the SaaS version then you can skip this step; otherwise visit the [Terraform Enterprise documentation](/terraform/enterprise) to get started.

## 2. Learn HCP Terraform's Run Environment

Get familiar with how Terraform runs work in HCP Terraform. With Terraform Community Edition, you generally use external VCS tools to get code onto the filesystem, then execute runs from the command line or from a general purpose CI system.

HCP Terraform does things differently: a workspace is associated directly with a VCS repo, and you use HCP Terraform’s UI or API to start and monitor runs. To get familiar with this operating model:

- Read the documentation on how to [perform and configure Terraform runs](/terraform/cloud-docs/run/remote-operations) in HCP Terraform.
- Create a proof-of-concept workspace, associate it with Terraform code in a VCS repo, set variables as needed, and use HCP Terraform to perform some Terraform runs with that code.

## 3. Design Your Organization’s Workspace Structure

In HCP Terraform, each Terraform configuration should manage a specific infrastructure component, and each environment of a given configuration should be a separate workspace — in other words, Terraform configurations \* environments = workspaces. A workspace name should be something like “networking-dev,” so you can tell at a glance which infrastructure and environment it manages.

The definition of an “infrastructure component” depends on your organization’s structure. A given workspace might manage an application, a service, or a group of related services; it might provision infrastructure used by a single engineering team, or it might provision shared, foundational infrastructure used by the entire business.

You should structure your workspaces to match the divisions of responsibility in your infrastructure. You will probably end up with a mixture: some components, like networking, are foundational infrastructure controlled by central IT staff; others are application-specific and should be controlled by the engineering teams that rely on them.

Also, keep in mind:

- Some workspaces publish output data to be used by other workspaces.
- The workspaces that make up a configuration’s environments (app1-dev, app1-stage, app1-prod) should be run in order, to ensure code is properly verified.

The first relationship, a relationship between workspaces for different components but the same environment, creates a graph of dependencies between workspaces, and you should stay aware of it. The second relationship, a relationship between workspaces for the same component but different environments, creates a pipeline between workspaces. HCP Terraform doesn’t currently have the ability to act on these dependencies, but features like cascading updates and promotion are coming soon, and you’ll be able to use them more easily if you already understand how your workspaces relate.

## 4. Create Workspaces

Create workspaces in HCP Terraform, and map VCS repositories to them. Each workspace reads its Terraform code from your version control system. You’ll need to assign a repository and branch to each workspace.

We recommend using the same repository and branch for every environment of a given app or service — write your Terraform code such that you can differentiate the environments via variables, and set those variables appropriately per workspace. This might not be practical for your existing code yet, in which case you can use different branches per workspace and handle promotion through your merge strategy, but we believe a model of one canonical branch works best.

![Changes in VCS branches can be merged to master and then promoted between workspaces representing a staging environment, a UAT environment, and finally a production environment.](/img/docs/image1.png)

## 5. Plan and Create Teams

HCP Terraform manages workspace access with teams, which are groups of user accounts.

Your HCP Terraform teams should match your understanding of who's responsible for which infrastructure. That isn't always an exact match for your org chart, so make sure you spend some time thinking about this and talking to people across the organization. Keep in mind:

- Some teams need to administer many workspaces, and others only need permissions on one or two.
- A team might not have the same permissions on every workspace they use; for example, application developers might have read/write access to their app’s dev and stage environments, but read-only access to prod.

Managing an accurate and complete map of how responsibilities are delegated is one of the most difficult parts of practicing collaborative infrastructure as code.

When managing team membership, you have two options:

- Manage user accounts with [SAML single sign-on](/terraform/enterprise/saml/configuration). SAML support is exclusive to Terraform Enterprise, and lets users log into HCP Terraform via your organization's existing identity provider. If your organization is at a scale where you use a SAML-compatible identity provider, we recommend this option.

  If your identity provider already has information about your colleagues' teams or groups, you can [manage team membership via your identity provider](/terraform/enterprise/saml/team-membership). Otherwise, you can add users to teams with the UI or with [the team membership API](/terraform/cloud-docs/api-docs/team-members).

- Manage user accounts in HCP Terraform. Your colleagues must create their own HCP Terraform user accounts, and you can add them to your organization by adding their username to at least one team. You can manage team membership with the UI or with [the team membership API](/terraform/cloud-docs/api-docs/team-members).

## 6. Assign Permissions

Assign workspace ownership and permissions to teams.

HCP Terraform supports granular team permissions for each workspace. For complete information about the available permissions, see [the HCP Terraform permissions documentation.](/terraform/cloud-docs/users-teams-organizations/permissions)

[permissions-citation]: #intentionally-unused---keep-for-maintainers

Most workspaces will give access to multiple teams with different permissions.

| Workspace       | Team Permissions                                                                                |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| app1-dev        | Team-eng-app1: Apply runs, read and write variables
 Team-owners-app1: Admin
 Team-central-IT: Admin                                   |
| app1-prod       | Team-eng-app1: Queue plans, read variables
 Team-owners-app1: Apply runs, read and write variables
 Team-central-IT: Admin             |
| networking-dev  | Team-eng-networking: Apply runs, read and write variables
 Team-owners-networking: Admin
 Team-central-IT: Admin                       |
| networking-prod | Team-eng-networking: Queue plans, read variables
 Team-owners-networking: Apply runs, read and write variables
 Team-central-IT: Admin |

## 7. Restrict Non-Terraform Access

Restrict access to cloud provider UIs and APIs. Since HCP Terraform is now your organization’s primary interface for infrastructure provisioning, you should restrict access to any alternate interface that bypasses HCP Terraform. For almost all users, it should be impossible to manually modify infrastructure without using the organization’s agreed-upon Terraform workflow.

As long as no one can bypass Terraform, your code review processes and your HCP Terraform workspace permissions are the definitive record of who can modify which infrastructure. This makes everything about your infrastructure more knowable and controllable. HCP Terraform is one workflow to learn, one workflow to secure, and one workflow to audit for provisioning any infrastructure in your organization.

## Next

At this point, you have successfully adopted a collaborative infrastructure as code workflow with HCP Terraform. You can provision infrastructure across multiple providers using a single workflow, and you have a shared interface that helps manage your organization’s standards around access control and code promotion.

Next, you can make additional improvements to your workflows and practices. Continue on to [Part 3.4: Advanced Improvements to Collaborative Infrastructure as Code](/terraform/cloud-docs/recommended-practices/part3.4).

page title       Part 3 3  From Infrastructure as Code to Collaborative Infrastructure as Code     Terraform Recommended Practices tfc only  true description       Move to collaborative infrastructure as code workflows  Learn about HCP Terraform s run environment  create workspaces  plan and create teams  assign permissions  and restrict non Terraform access         Part 3 3  How to Move from Infrastructure as Code to Collaborative Infrastructure as Code  Using version controlled Terraform configurations to manage key infrastructure eliminates a great deal of technical complexity and inconsistency  Now that you have the basics under control  you re ready to focus on other problems   Your next goals are to     Adopt consistent workflows for Terraform usage across teams   Expand the benefits of Terraform beyond the core of engineers who directly edit Terraform code    Manage infrastructure provisioning permissions for users and teams    HCP Terraform  https   www hashicorp com products terraform   is the product we ve built to help you address these next level problems  The following section describes how to start using it most effectively   Note  If you aren t already using mature Terraform code to manage a significant portion of your infrastructure  make sure you follow the steps in the previous section first      1  Install or Sign Up for HCP Terraform  You have two options for using HCP Terraform  the SaaS hosted by HashiCorp  or a private instance you manage with Terraform Enterprise  If you have chosen the SaaS version then you can skip this step  otherwise visit the  Terraform Enterprise documentation   terraform enterprise  to get started      2  Learn HCP Terraform s Run Environment  Get familiar with how Terraform runs work in HCP Terraform  With Terraform Community Edition  you generally use external VCS tools to get code onto the filesystem  then execute runs from the command line or from a general purpose CI system   HCP Terraform does things differently  a workspace is associated directly with a VCS repo  and you use HCP Terraform s UI or API to start and monitor runs  To get familiar with this operating model     Read the documentation on how to  perform and configure Terraform runs   terraform cloud docs run remote operations  in HCP Terraform    Create a proof of concept workspace  associate it with Terraform code in a VCS repo  set variables as needed  and use HCP Terraform to perform some Terraform runs with that code      3  Design Your Organization s Workspace Structure  In HCP Terraform  each Terraform configuration should manage a specific infrastructure component  and each environment of a given configuration should be a separate workspace   in other words  Terraform configurations    environments   workspaces  A workspace name should be something like  networking dev   so you can tell at a glance which infrastructure and environment it manages   The definition of an  infrastructure component  depends on your organization s structure  A given workspace might manage an application  a service  or a group of related services  it might provision infrastructure used by a single engineering team  or it might provision shared  foundational infrastructure used by the entire business   You should structure your workspaces to match the divisions of responsibility in your infrastructure  You will probably end up with a mixture  some components  like networking  are foundational infrastructure controlled by central IT staff  others are application specific and should be controlled by the engineering teams that rely on them   Also  keep in mind     Some workspaces publish output data to be used by other workspaces    The workspaces that make up a configuration s environments  app1 dev  app1 stage  app1 prod  should be run in order  to ensure code is properly verified   The first relationship  a relationship between workspaces for different components but the same environment  creates a graph of dependencies between workspaces  and you should stay aware of it  The second relationship  a relationship between workspaces for the same component but different environments  creates a pipeline between workspaces  HCP Terraform doesn t currently have the ability to act on these dependencies  but features like cascading updates and promotion are coming soon  and you ll be able to use them more easily if you already understand how your workspaces relate      4  Create Workspaces  Create workspaces in HCP Terraform  and map VCS repositories to them  Each workspace reads its Terraform code from your version control system  You ll need to assign a repository and branch to each workspace   We recommend using the same repository and branch for every environment of a given app or service   write your Terraform code such that you can differentiate the environments via variables  and set those variables appropriately per workspace  This might not be practical for your existing code yet  in which case you can use different branches per workspace and handle promotion through your merge strategy  but we believe a model of one canonical branch works best     Changes in VCS branches can be merged to master and then promoted between workspaces representing a staging environment  a UAT environment  and finally a production environment    img docs image1 png      5  Plan and Create Teams  HCP Terraform manages workspace access with teams  which are groups of user accounts   Your HCP Terraform teams should match your understanding of who s responsible for which infrastructure  That isn t always an exact match for your org chart  so make sure you spend some time thinking about this and talking to people across the organization  Keep in mind     Some teams need to administer many workspaces  and others only need permissions on one or two    A team might not have the same permissions on every workspace they use  for example  application developers might have read write access to their app s dev and stage environments  but read only access to prod   Managing an accurate and complete map of how responsibilities are delegated is one of the most difficult parts of practicing collaborative infrastructure as code   When managing team membership  you have two options     Manage user accounts with  SAML single sign on   terraform enterprise saml configuration   SAML support is exclusive to Terraform Enterprise  and lets users log into HCP Terraform via your organization s existing identity provider  If your organization is at a scale where you use a SAML compatible identity provider  we recommend this option     If your identity provider already has information about your colleagues  teams or groups  you can  manage team membership via your identity provider   terraform enterprise saml team membership   Otherwise  you can add users to teams with the UI or with  the team membership API   terraform cloud docs api docs team members      Manage user accounts in HCP Terraform  Your colleagues must create their own HCP Terraform user accounts  and you can add them to your organization by adding their username to at least one team  You can manage team membership with the UI or with  the team membership API   terraform cloud docs api docs team members       6  Assign Permissions  Assign workspace ownership and permissions to teams   HCP Terraform supports granular team permissions for each workspace  For complete information about the available permissions  see  the HCP Terraform permissions documentation    terraform cloud docs users teams organizations permissions    permissions citation    intentionally unused   keep for maintainers  Most workspaces will give access to multiple teams with different permissions     Workspace         Team Permissions                                                                                app1 dev          Team eng app1  Apply runs  read and write variables  br    Team owners app1  Admin  br    Team central IT  Admin                                       app1 prod         Team eng app1  Queue plans  read variables  br    Team owners app1  Apply runs  read and write variables  br    Team central IT  Admin                 networking dev    Team eng networking  Apply runs  read and write variables  br    Team owners networking  Admin  br    Team central IT  Admin                           networking prod   Team eng networking  Queue plans  read variables  br    Team owners networking  Apply runs  read and write variables  br    Team central IT  Admin       7  Restrict Non Terraform Access  Restrict access to cloud provider UIs and APIs  Since HCP Terraform is now your organization s primary interface for infrastructure provisioning  you should restrict access to any alternate interface that bypasses HCP Terraform  For almost all users  it should be impossible to manually modify infrastructure without using the organization s agreed upon Terraform workflow   As long as no one can bypass Terraform  your code review processes and your HCP Terraform workspace permissions are the definitive record of who can modify which infrastructure  This makes everything about your infrastructure more knowable and controllable  HCP Terraform is one workflow to learn  one workflow to secure  and one workflow to audit for provisioning any infrastructure in your organization      Next  At this point  you have successfully adopted a collaborative infrastructure as code workflow with HCP Terraform  You can provision infrastructure across multiple providers using a single workflow  and you have a shared interface that helps manage your organization s standards around access control and code promotion   Next  you can make additional improvements to your workflows and practices  Continue on to  Part 3 4  Advanced Improvements to Collaborative Infrastructure as Code   terraform cloud docs recommended practices part3 4