Add docs for sso-team-id to the Teams API (#2210)

Update TFC docs to specify that the SSO Team membership SAML attribute can be configured. Fix typos in README. Add sso-team-id to API examples. Call out that sso-team-ids are only applicable to business tier orgs
hashicorp · Apr 11, 2022 · fe1b27e · fe1b27e · vercel · Apr 11, 2022
1 parent 27d633a
commit fe1b27e
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -48,20 +48,20 @@ Docs live in a couple different repos. (**To find a page the easy way:** view it
 
   **Notable branches:** `master` is the "live" content that gets deployed to [terraform.io](https://terraform.io). The site gets redeployed for new commits to master.
 
-- [hashicorp/terraform][https://github.com/hashicorp/terraform], under `website/docs`:
+- [hashicorp/terraform](https://github.com/hashicorp/terraform), under `website/docs`:
 
   - Terraform CLI docs
   - Terraform Language docs
 
   **Notable branches:** `stable-website` is the "live" content that gets deployed to [terraform.io](https://terraform.io), but docs changes should get merged to `main` (and/or one of the long-lived version branches) first. See [More About `stable-website`][#more-about-stable-website] below for more details.
 
-- [hashicorp/terraform-cdk][https://github.com/hashicorp/terraform-cdk], under `website/docs`:
+- [hashicorp/terraform-cdk](https://github.com/hashicorp/terraform-cdk), under `website/docs`:
 
   - Terraform CDK docs
 
   **Notable branches:** `stable-website` is the "live" content that gets deployed to [terraform.io](https://terraform.io), but docs changes should get merged to `main` first. See [More About `stable-website`][#more-about-stable-website] below for more details.
 
-## Deploying Changes to [terraform.io][https://terraform.io]
+## Deploying Changes to [terraform.io](https://terraform.io)
 
 ### For changes in this repo
 

diff --git a/content/cloud-docs/api-docs/teams.mdx b/content/cloud-docs/api-docs/teams.mdx
@@ -36,7 +36,7 @@ page_title: Teams - API Docs - Terraform Cloud and Terraform Enterprise
 
 # Teams API
 
--> **Note:** Team management is a paid feature, available as part of the **Team** upgrade package. [Learn more about Terraform Cloud pricing here](https://www.hashicorp.com/products/terraform/pricing).
+-> **Note:** Team management is a paid feature, available as part of the **Team** upgrade package. Single sign-on is also a paid feature, available as part of the **Business** upgrade package. Refer to [Terraform Cloud pricing](https://www.hashicorp.com/products/terraform/pricing) for details.
 
 The Teams API is used to create, edit, and destroy teams as well as manage a team's organization-level permissions. The [Team Membership API](/cloud-docs/api-docs/team-members) is used to add or remove users from a team. Use the [Team Access API](/cloud-docs/api-docs/team-access) to associate a team with privileges on an individual workspace.
 
@@ -77,6 +77,8 @@ $ curl \
 
 ### Sample Response
 
+The `sso-team-id` attribute is only returned if this team's organization is in the Terraform Cloud Business tier.
+
 ```json
 {
   "data": [
@@ -85,6 +87,7 @@ $ curl \
       "type": "teams",
       "attributes": {
         "name": "team-creation-test",
+        "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
         "users-count": 0,
         "visibility": "organization",
         "permissions": {
@@ -143,6 +146,7 @@ Properties without a default value are required.
 | --------------------------------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `data.type`                             | string |            | Must be `"teams"`.                                                                                                                                                                                                                   |
 | `data.attributes.name`                  | string |            | The name of the team, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization.                                                                              |
+| `data.attributes.sso-team-id`           | string | (nothing)  | The unique identifier of the team from the SAML `MemberOf` attribute. Only available if the team belongs to an organization in the paid Terraform Cloud Business tier.                                                                                                                                                     |
 | `data.attributes.organization-access`   | object | (nothing)  | Settings for the team's organization access. This object can include `manage-policies`, `manage-policy-overrides`, `manage-workspaces`, `manage-vcs-settings`, `manage-providers`, and `manage-modules` properties with boolean values. All properties default to `false`. |
 | `data.attributes.visibility` **(beta)** | string | `"secret"` | The team's visibility. Must be `"secret"` or `"organization"` (visible).                                                                                                                                                             |
 
@@ -154,6 +158,7 @@ Properties without a default value are required.
     "type": "teams",
     "attributes": {
       "name": "team-creation-test",
+      "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
       "organization-access": {
         "manage-workspaces": true
       }
@@ -175,11 +180,14 @@ $ curl \
 
 ### Sample Response
 
+The `sso-team-id` attribute is only returned if this team's organization is in the Terraform Cloud Business tier.
+
 ```json
 {
   "data": {
     "attributes": {
       "name": "team-creation-test",
+      "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
       "organization-access": {
         "manage-policies": false,
         "manage-policy-overrides": false,
@@ -235,13 +243,16 @@ $ curl \
 
 ### Sample Response
 
+The `sso-team-id` attribute is only returned if this team's organization is in the Terraform Cloud Business tier.
+
 ```json
 {
   "data": {
     "id": "team-6p5jTwJQXwqZBncC",
     "type": "teams",
     "attributes": {
       "name": "team-creation-test",
+      "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
       "users-count": 0,
       "visibility": "organization",
       "permissions": {
@@ -301,6 +312,7 @@ Properties without a default value are required.
 | --------------------------------------- | ------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `data.type`                             | string |                  | Must be `"teams"`.                                                                                                                                                                                                                   |
 | `data.attributes.name`                  | string | (previous value) | The name of the team, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization.                                                                              |
+| `data.attributes.sso-team-id`           | string | (previous value) | The unique identifier of the team from the SAML `MemberOf` attribute. Only available if the team belongs to an organization in the paid Terraform Cloud Business tier.                                                                                                                                                   |
 | `data.attributes.organization-access`   | object | (previous value) | Settings for the team's organization access. This object can include `manage-policies`, `manage-policy-overrides`, `manage-workspaces`, `manage-vcs-settings`, `manage-providers`, and `manage-modules` properties with boolean values. All properties default to `false`. |
 | `data.attributes.visibility` **(beta)** | string | (previous value) | The team's visibility. Must be `"secret"` or `"organization"` (visible).                                                                                                                                                             |
 
@@ -333,11 +345,14 @@ $ curl \
 
 ### Sample Response
 
+The `sso-team-id` attribute is only returned if this team's organization is in the Terraform Cloud Business tier.
+
 ```json
 {
   "data": {
     "attributes": {
       "name": "team-creation-test",
+      "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
       "organization-access": {
         "manage-policies": false,
         "manage-policy-overrides": false,

diff --git a/content/cloud-docs/users-teams-organizations/single-sign-on/index.mdx b/content/cloud-docs/users-teams-organizations/single-sign-on/index.mdx
@@ -63,13 +63,29 @@ If an organization's owners disable SSO (or downgrade the organization's account
 
 ## Managing Team Membership Through SSO
 
-Terraform Cloud can automatically add users to teams based on their SAML assertion, so you can manage team membership in your directory service. To do this, you must specify the `MemberOf` SAML attribute, and make sure the AttributeStatement in the SAMLResponse contains a list of AttributeValue items in the correct format (i.e., comma-separated list of team names).
+Terraform Cloud can automatically add users to teams based on their SAML assertion, so you can manage team membership in your directory service.
 
-If the SAML assertion includes a `MemberOf` attribute, users logging in via SSO are automatically added to the teams included in their assertion and removed from any teams that _aren't_ included in their assertion. This overrides any manually set team memberships; whenever the user logs in, their team membership is adjusted to match their SAML assertion.
+To enable team membership mapping:
 
-Any team names that don't match existing teams are ignored; Terraform Cloud will not automatically create new teams. Terraform Cloud expects the team names in the `MemberOf` SAML attribute to exactly match its own team names. This match is case sensitive. It is not possible to assign users to the `owners` team through this attribute.
+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**.
 
-If the `MemberOf` attribute is not provided, users are assigned to a default team named `sso` and are not removed from any existing teams.
+![Screenshot: the Terraform Cloud SAML team membership toggle](/img/docs/saml-team-membership-cloud.png)
+
+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. 
+
+Terraform Cloud 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
+
+Terraform Cloud expects the team names in the team membership SAML attribute to exactly match its own team names or its configured SSO Team IDs. This match is case sensitive.
+
+You can configure SSO Team IDs in the organization's **Teams** page. If an SSO Team ID is configured, Terraform Cloud 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 Terraform Cloud.
 
 ## NameID Format
 

diff --git a/public/img/docs/saml-team-membership-cloud.png b/public/img/docs/saml-team-membership-cloud.png