Add docs for sso-team-id to the Teams API

[xlgmokha]

Why?

The ability to manage team membership via SAML and the MemberOf attribute is
being expanded to allow mapping teams to a unique sso-team-id. This new
functionality is available to organizations with the SSO entitlement via the
Business tier.

What?

This PR attempts to update the API documentation to show that a new field called
sso-team-id will appear in responses for teams that belong to an organization
with the appropriate entitlement. It also updates examples to show how to
create/update teams with an sso-team-id.

Screen.Recording.2022-03-24.at.15.05.18.mov

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1201966179237923

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/hashicorp/terraform-website/CiHAsdK6YoEp1riZGT4GQQCTgctf
✅ Preview: https://terraform-website-git-xlgmokha-sso-team-id-hashicorp.vercel.app

[xlgmokha]

@laurapacilio would you be able to help me with some of the wording for this change. I'm having a bit of trouble expressing that this change is only available to organizations in the business tier.

[laurapacilio]

Some initial feedback for you! Let me know if you disagree or have other ideas :-) Otherwise, I'd love to see how this looks and take another editing pass once you've made the changes. Thank you for tagging me for review!

[laurapacilio]

Approved with a few final nits :-) If you add those in, you have my support to merge! 🚀

[laurapacilio]

thank you! a little correction for flow and then I approve :-)

[JarrettSpiker]

Unfortunately, when making the TFE docs side changes for this, I noticed that the exiting TFC docs (what this review modifies) are a bit misleading. Even before the SSO Team ID changes, they say that the SAML attribute which get's mapped to team names has to be MemberOf.

In fact, the TFE docs describe the actual behaviour, which is that it is configurable https://www.terraform.io/enterprise/user-management/saml/team-membership#configuring-team-membership-mapping

So I am going to update this review (again, sorry) to be closer aligned with the TFE docs.

I hate continuing to modify a PR which has already been reviewed and approved, but unfortunately we dont want to release these website changes until we GA this feature, so there isnt much opportunity to make iterative changes :/

[laurapacilio]

no worries - will you just let me know when its ready again?

[JarrettSpiker]

no worries - will you just let me know when its ready again?

@laurapacilio Updated! I mostly just pulled text from the TFE page, and tweaked it to be Cloud specific

[xlgmokha]

@laurapacilio, @JarrettSpiker do you think it's safe to merge this change?

[laurapacilio]

A couple of suggested nits for flow :) A lot of it is changing things to be active voice, but please push back on me if I've materially changed the meaning!