Group management with SCIM

This topic explains how HCP Terraform manages SCIM groups from your identity provider (IdP) and how group membership synchronizes with teams.

Overview

SCIM groups represent groups from your IdP. When you provision a group through SCIM, HCP Terraform automatically creates a corresponding team with the same name. Group membership from your IdP synchronizes directly to team membership in HCP Terraform.

SCIM groups enable you to:

Automatically sync group membership from your IdP to HCP Terraform teams
Automatically create teams based on IdP group names
Maintain your IdP as the single source of truth for group membership

Groups and teams

When you provision a group through SCIM, HCP Terraform automatically creates a team with the same name as the IdP group. The IdP group name becomes the team name in HCP Terraform. Group membership from your IdP synchronizes directly to the corresponding team.

The following table provides more information about how SCIM groups relate to HCP Terraform teams.

	SCIM groups	HCP Terraform teams
Description	Representations of IdP groups that automatically create corresponding teams in HCP Terraform.	Organization-scoped entities that control access to workspaces, projects, and other resources. Teams have associated permissions and can contain members.
Management	Managed by your IdP through SCIM API calls.	Automatically created and managed by SCIM based on IdP groups.
Scope	Organization-scoped in HCP Terraform.	Scoped to a specific organization in HCP Terraform.
Permissions	No permissions.	Configurable permissions for workspaces, projects, and organization-level access.
Membership source	IdP.	Automatically synchronized from the corresponding IdP group.
Team creation	Provisioning a group automatically creates a team.	Created automatically when the corresponding SCIM group is provisioned.

When a group is provisioned, HCP Terraform performs the following actions:

Creates a team with the same name as the IdP group's displayName.
Synchronizes the group's membership to the team.

Existing HCP Terraform teams

When a team with the same name already exists, then HCP Terraform links the IdP group to the existing team and synchronizes the membership. If the lettercase doesn't match, HCP Terraform updates the existing team's name to match the case of the SCIM group.

Note that owners and sso are reserved names that you can't use as SCIM group names.

Group lifecycle

SCIM groups follow a standard create, update, and delete lifecycle managed by your identity provider.

Create stage

HCP Terraform performs the following actions when your IdP creates a group through SCIM:

Generates a unique SCIM id for the group.
Stores the group with its displayName and any externalId from the IdP.
Automatically creates a team with the same name as the group's displayName.
Synchronizes the group's membership to the newly created team.

When a team with the same name already exists, then HCP Terraform links the IdP group to the existing team and synchronizes the membership. Refer to Existing HCP Terraform teams.

SCIM group displayName values must be unique across HCP Terraform. Values aren't case-sensitive. As a result, HCP Terraform considers Engineering and engineering to be the same displayName. When you attempt to provision a new group with an existing displayName, HCP Terraform rejects the request with HTTP 409 Conflict.

When HCP Terraform adds groups, it preserves the original letter case of SCIM group display names when it stores them. API responses return the stored displayName with that preserved letter case.

To reference a group member in the members[].value object, you must include the user's public SCIM id value from /scim/v2/Users. Before you can perform group membership operations, the user must already be provisioned in HCP Terraform through SCIM.

Update stage

Your IdP can update the following group properties:

Group display name changes. HCP Terraform updates the corresponding team name to match the name provided by the IdP.
Membership changes. Adding or removing users from the group triggers membership synchronization to the corresponding HCP Terraform team.

You can fully replace or partially update groups from supported identity providers. Full replacement updates reconcile the group's membership to the roster provided by the IdP. Partial updates support the common group change patterns used by Okta and Microsoft Entra ID, including display name changes, full member replacement, and incremental member add or remove operations.

For the exact public SCIM endpoints, request shapes, supported PATCH request forms, and omitted-attribute behavior, refer to the SCIM Groups API.

Refer to Membership synchronization for details on how membership updates propagate.

Delete stage

HCP Terraform performs the following actions when your IdP deletes a group through SCIM:

Removes the SCIM group record.
Deletes the corresponding team.

When a team is deleted, all team memberships and team permissions are removed. Users remain in the organization unless they are also removed through SCIM user deprovisioning.

For delete semantics and status codes, refer to the SCIM Groups API reference.

Membership synchronization

When your IdP updates group membership, HCP Terraform synchronizes the changes to the corresponding team.

Synchronization process

When your IdP sends a membership update, HCP Terraform performs the following actions:

Updates the SCIM group's membership records.
For the corresponding team:
- Removes users who are no longer in the SCIM group.
- Adds users newly added to the SCIM group.
Applies all changes as discrete records in a single transaction.

Transaction behavior

To ensure data consistency, HCP Terraform synchronizes membership as discrete records in a transaction.

All changes either succeed or roll back depending on the success of the synchronization. HCP Terraform doesn't partially apply changes. If the transaction times out or fails, the team retains its previous membership state.

Group size limits

To ensure reliable synchronization within transaction timeouts, HCP Terraform enforces the following limits on group membership:

Limit	Value	Behavior
Maximum members per SCIM group request	1,000	Public SCIM group create or update requests that would create or project a group over this limit return HTTP `413 Payload Too Large`
Maximum IdP groups	3,000	Total number of groups that can be synchronized

There are also limits on the size of SCIM provisioning and PATCH API requests. Refer to the SCIM provisioning API and the SCIM Groups API for the exact request size, operation count, and response details.

Large groups

If your IdP groups exceed the limits, consider the implementing the following approaches:

Create multiple smaller IdP groups based on functional roles or departments.

Provision smaller groups that create separate teams with appropriate permissions.
Review whether all members need the same level of access.

Rate limits

SCIM group operations are subject to rate limiting to protect HCP Terraform performance.

Public SCIM provisioning uses shared rate limits across the public SCIM endpoints. For the exact rate limit values, refer to the Public SCIM API.

API reference

Refer to the following API references for SCIM group operations:

SCIM Groups API describes for the public /scim/v2/Groups provisioning endpoints, supported excludedAttributes behavior, and group create or update semantics.

SCIM provisioning API endpoints describes authentication, discovery endpoints, pagination, supported filters, and shared rate limits.

IdP-specific behavior

Although different identity providers send membership updates in different formats, HCP Terraform handles both formats and applies the appropriate membership changes.

For example, Microsoft Entra ID sends PATCH requests with lists of members to add and remove, whereas Okta can send either PUT requests with a complete list of all group members or a PATCH requests.