Add SSO Team IDs to Terraform Enterprise documentation (#2221)

* Add SSO Team IDs to Terraform Enterprise documentation * Update API doc to indicate sso-team-id is returned in TFE
hashicorp · Apr 11, 2022 · 08dd558 · 08dd558 · vercel · Apr 11, 2022
1 parent fe1b27e
commit 08dd558
Show file tree

Hide file tree

Showing 2 changed files with 10 additions and 8 deletions.
diff --git a/content/cloud-docs/api-docs/teams.mdx b/content/cloud-docs/api-docs/teams.mdx
@@ -77,7 +77,7 @@ $ curl \
 
 ### Sample Response
 
-The `sso-team-id` attribute is only returned if this team's organization is in the Terraform Cloud Business tier.
+The `sso-team-id` attribute is only returned in Terraform Enterprise 202204-1 and later, or if this team's organization is in the Terraform Cloud Business tier.
 
 ```json
 {
@@ -146,7 +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.sso-team-id`           | string | (nothing)  | The unique identifier of the team from the SAML `MemberOf` attribute. Only available in Terraform Enterprise 202204-1 and later, or 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).                                                                                                                                                             |
 
@@ -180,7 +180,7 @@ $ curl \
 
 ### Sample Response
 
-The `sso-team-id` attribute is only returned if this team's organization is in the Terraform Cloud Business tier.
+The `sso-team-id` attribute is only returned in Terraform Enterprise 202204-1 and later, or if this team's organization is in the Terraform Cloud Business tier.
 
 ```json
 {
@@ -243,7 +243,7 @@ $ curl \
 
 ### Sample Response
 
-The `sso-team-id` attribute is only returned if this team's organization is in the Terraform Cloud Business tier.
+The `sso-team-id` attribute is only returned in Terraform Enterprise 202204-1 and later, or if this team's organization is in the Terraform Cloud Business tier.
 
 ```json
 {
@@ -312,7 +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.sso-team-id`           | string | (previous value) | The unique identifier of the team from the SAML `MemberOf` attribute. Only available in Terraform Enterprise 202204-1 and later, or 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).                                                                                                                                                             |
 
@@ -345,7 +345,7 @@ $ curl \
 
 ### Sample Response
 
-The `sso-team-id` attribute is only returned if this team's organization is in the Terraform Cloud Business tier.
+The `sso-team-id` attribute is only returned in Terraform Enterprise 202204-1 and later, or if this team's organization is in the Terraform Cloud Business tier.
 
 ```json
 {

diff --git a/content/enterprise/user-management/saml/team-membership.mdx b/content/enterprise/user-management/saml/team-membership.mdx
@@ -21,9 +21,11 @@ Any team names that don't match existing teams are ignored; Terraform Enterprise
 
 To disable team membership mapping, uncheck the "Use SAML to manage team memberships" checkbox in the SAML admin page. With mapping disabled, Terraform Enterprise won't automatically manage team membership on login, and you can manually add users to teams via the organization's Teams page.
 
-## Team Names
+## Team Names and SSO Team IDs
 
-Terraform Enterprise expects the team names in the team membership SAML attribute to exactly match its own team names. This match is case sensitive. You cannot specify aliases for teams.
+Terraform Enterprise 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.
+
+SSO Team IDs can be configured via the organization's Teams page. If one is configured, Terraform Enterprise will also attempt to match the chosen SAML attribute against the SSO Team ID (in addition to the team name) when mapping users to teams. This is useful if the chosen team membership SAML attribute is not human readable, and is not used as the team's name in Terraform Enterprise.
 
 Note that team names are unique across an organization but not necessarily unique across a whole Terraform Enterprise instance. If a user is a member of multiple organizations, their SAML assertion might add them to similarly-named teams in each organization. Keep this in mind when naming your teams.