Map SCIM groups to teams

This topic describes how to link SCIM groups from your identity provider (IdP) to teams in Terraform Enterprise for automated team membership management.

Overview

Linking connects SCIM groups provisioned from your identity provider to teams in Terraform Enterprise. When you create a link, team membership is automatically synchronized from the IdP group, eliminating the need for manual team membership management.

Linking enables you to:

• Automate team membership based on IdP group assignments
• Maintain your identity provider as the single source of truth for team membership
• Link a single IdP group to multiple Terraform Enterprise teams across different organizations
• Pause and resume synchronization for troubleshooting without losing configuration

For the conceptual relationship between SCIM groups, Terraform Enterprise teams, synchronization, and group size guidance, refer to Group management with SCIM.

Linking relationships

Terraform Enterprise uses a flexible linking model that supports enterprise-scale deployments while maintaining clear boundaries for team management.

You can link SCIM groups to Terraform Enterprise teams according to the following rules:

Group-to-team links

• You can link a single SCIM group to up to 10,000 Terraform Enterprise teams across different organizations.
• This supports organizations that need the same IdP group mapped consistently across many Terraform Enterprise organizations.

Team-to-group links

• You can link each Terraform Enterprise team to only one SCIM group at a time.
• This ensures clear ownership of team membership.

Restrictions

The following restrictions apply to linking:

• Site admin group cannot be linked: If a SCIM group is configured as the site admin group in SCIM settings, you cannot link it to a Terraform Enterprise team. The site admin group is used exclusively for site administrator provisioning.
• Owners team cannot be linked: The owners team in each organization cannot be linked to a SCIM group. This ensures that administrators always have a way to access Terraform Enterprise for troubleshooting, even if there are issues with SCIM synchronization.

Prerequisites

Before creating a link, ensure that:

• SCIM is enabled at the site level
• The SCIM group exists in Terraform Enterprise (provisioned from your IdP)
• You are a site administrator
• The SCIM group has 1,000 or fewer members

Create a link

Creating a link connects a SCIM group to a Terraform Enterprise team and synchronizes membership.

Complete the following steps to link a SCIM group to a Terraform Enterprise team:

1. Navigate to your organization's Settings > Teams.
2. Click on the team you want to link to a SCIM group.
3. Go to the Team Settings tab.
4. In the SCIM Group section, click the dropdown to display available SCIM groups.
5. Select the SCIM group you want to link to this team.
6. Review the warning message about membership replacement.
7. Click Save to create the link.

What happens after you create a link

After creating a link, Terraform Enterprise performs the following actions:

1. Existing team membership is reconciled to the SCIM group: Terraform Enterprise updates the team's human user membership to match the current members of the SCIM group. Existing service account memberships, including team API token access, are preserved.

2. Organization membership is created: Users in the SCIM group who are not already members of the organization are automatically added to the organization.

3. SCIM metadata is updated: The team's scim-updated-at timestamp is set to reflect the synchronization.

4. Team becomes SCIM-managed: The team's membership can no longer be modified directly in Terraform Enterprise. All membership changes must go through the IdP.

Transaction timeout behavior

The linking operation uses a transaction with a 30-second timeout to ensure data consistency:

If linking consistently fails due to timeout, the SCIM group may be too large. Refer to Group management with SCIM for group size guidance.

For detailed synchronization behavior, linked-team metadata, and endpoint-specific behavior, refer to Group management with SCIM, the Teams API reference, the Team Membership API, and the Team SCIM Group Mapping API.

Pause synchronization

You can pause SCIM synchronization for individual teams without removing the link. This is useful for troubleshooting or temporarily preventing membership updates. Refer to Resume synchronization for instructions on unpausing.

Pausing synchronization stops the team from receiving membership updates from the SCIM group:

1. Navigate to the team's Team Settings tab.
2. In the SCIM Sync section, click Pause Sync.
3. Confirm the action.

When synchronization is paused:

• The team retains its current membership
• SCIM updates to the linked group do not affect the team
• The link between the team and SCIM group is preserved
• Direct membership changes in Terraform Enterprise remain blocked while the link exists

If you need the exact request and response behavior for repeated pause requests, refer to the Team SCIM Group Mapping API.

Resume synchronization

Resuming synchronization reconciles the team with the current SCIM group state and resumes membership updates:

1. Navigate to the team's Team Settings tab.
2. In the SCIM Sync section, click Resume Sync.
3. Review the warning about membership reconciliation.
4. Confirm the action.

When synchronization is unpaused:

• Terraform Enterprise compares the team's current membership with the SCIM group
• Any differences are reconciled to match the current SCIM group membership
• Terraform Enterprise adds users who joined the SCIM group while paused to the team
• Terraform Enterprise removes users who left the SCIM group while paused from the team
• If the linked SCIM group no longer exists, Terraform Enterprise stops applying updates from that group. Verify the resulting link state and team membership before making manual changes.

If you need the exact request and response behavior for repeated unpause requests, refer to the Team SCIM Group Mapping API.

Resuming synchronization can result in significant membership changes if the SCIM group changed while synchronization was paused.

Unlink a SCIM group

Deleting a link removes the link between a Terraform Enterprise team and a SCIM group, converting the team back to manual management.

Unlink a SCIM group in the UI

1. Navigate to the team's Team Settings tab.
2. In the SCIM Group section, click Unlink.
3. Review the confirmation message.
4. Click Confirm to remove the link.

What happens after you unlink a group

Unlinking a SCIM group from a team results in the following:

• You can add and remove members directly in Terraform Enterprise.
• All team members at the time of unlinking remain on the team.
• The SCIM group remains in Terraform Enterprise, and you can link it to other teams.
• Membership changes in the IdP group no longer propagate to this team.

Best practices

Follow these recommendations for effective SCIM team linking:

Start with small groups

Test your SCIM team linking configuration with groups of 50 members or fewer before rolling out to larger groups. This helps you:

• Verify that links work as expected
• Identify any issues with group membership before they affect many users
• Build confidence in the synchronization behavior

Use meaningful team names

When linking SCIM groups to Terraform Enterprise teams, use team names that clearly indicate the purpose and source:

• Include the IdP group name or identifier for easy correlation
• Document the linked SCIM group in your team description
• Consider a naming convention that distinguishes SCIM-linked teams from manually managed teams

Plan for IdP changes

Before making changes to IdP groups that are linked to Terraform Enterprise teams:

• Review which Terraform Enterprise teams are linked to the group
• Communicate expected changes to affected team members
• Consider pausing synchronization during large group restructuring

When using the admin API for large batches of team changes, stagger requests to avoid team-mapping rate limits. Refer to the Team SCIM Group Mapping API for the exact limits and response behavior.

Maintain recovery access

Always ensure you have access to Terraform Enterprise independent of SCIM:

• Keep at least one non-SSO admin account for emergency access
• Do not link the owners team to a SCIM group
• Document your recovery procedures

API reference

Use the following API references to manage team links programmatically:

• Refer to the Team SCIM Group Mapping API to create, unlink, pause, and resume team links.
• Refer to the Admin SCIM Groups API to list the SCIM groups available for linking.

These API references contain the request bodies, response codes, and example payloads for the admin endpoints.