Enable the SAML Identity Provider to Map Team Membership

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

Configure Team Membership Mapping

Enable the Use SAML to manage team memberships option on ths site administation page to allow the SAML identity provider to control team membership.

When you enable it, you must specify the name of a SAML attribute in the Team Attribute Name setting, and make sure the AttributeStatement in the SAMLResponse contains a list of AttributeValue items in the correct format.

When team membership management is enabled, users logging in via SAML are automatically added to the teams included in their assertion, and automatically 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 Enterprise will not automatically create new teams.

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 and SSO Team IDs

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.

Managing Membership of the Owners Team

Since the "owners" team is especially important, Terraform Enterprise defaults to NOT managing its membership via SAML. Unless you specifically enable it, Terraform Enterprise won't automatically add or remove any owners, and you can manually manage membership via the teams page.

You can enable automatic membership in the owners team (on a per-organization basis) by explicitly specifying an alias (role ID) for it. On your organization settings page, click "Teams" and then click the owners team. If SAML is enabled, there will be a "SAML Role ID" field. Enter a legal team name as an ID and click "Save." The ID can be "owners," but it cannot conflict with any other team name.

Before enabling membership mapping for owners, double-check that your chosen role ID appears in the SAML assertion for users who should be owners. It's worth some extra effort to avoid accidentally removing people from the owners team.

Site Admins

If the "Site Admin Role" setting (in the SAML settings) is enabled, the selected special team name (default: site-admins) will add a user as a site admin for the Terraform Enterprise instance.

Site admins can also always log in to Terraform Enterprise directly. If they are disabled on the identity provider but still enabled in Terraform Enterprise and bypass SSO, they will still be able to log in.