Add paragraph clarifying the use of SSO team IDs in TFC

hashicorp · Mar 30, 2022 · 0e6adac · 0e6adac
1 parent 75d51d1
commit 0e6adac
Show file tree

Hide file tree

Showing 2 changed files with 8 additions and 6 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 if this team's organization is in the Terraform Cloud Business tier.
 
 ```json
 {
@@ -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 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 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 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 if this team's organization is in the Terraform Cloud Business tier.
 
 ```json
 {

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
@@ -67,7 +67,9 @@ Terraform Cloud can automatically add users to teams based on their SAML asserti
 
 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.
 
-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 or SSO team IDs. This match is case sensitive. It is not possible to assign users to the `owners` team through this attribute.
+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.
+
+In some circumstances the `MemberOf` SAML attribute may not be human readable, due to restrictions in your SSO provider for example. In this case, in order to maintain human readalbe team names in Terraform Cloud, you may set an SSO Team ID for the team which matches the SAML attribute instead.
 
 If the `MemberOf` attribute is not provided, users are assigned to a default team named `sso` and are not removed from any existing teams.