HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Terraform
Terraform Home

SCIM provisioning overview

This topic provides an overview of SCIM 2.0 provisioning in Terraform Enterprise. SCIM (System for Cross-domain Identity Management) enables automated user provisioning, deprovisioning, and group management from your identity provider (IdP) directly into Terraform Enterprise.

Introduction

SCIM 2.0 is an open standard protocol designed to simplify user identity management across cloud-based applications and services. For enterprise organizations, SCIM eliminates the manual processes required to onboard and offboard users, ensuring that identity changes in your corporate directory are automatically reflected in Terraform Enterprise.

When you integrate SCIM with Terraform Enterprise, your identity provider becomes the authoritative source for user lifecycle management. This means that when employees join, change roles, or leave your organization, their access to Terraform Enterprise is automatically updated without manual intervention.

Terraform Enterprise implements SCIM for Terraform Enterprise only. The SCIM configuration is instance-wide.

Terraform Enterprise exposes two SCIM-related API surfaces:

  • The public SCIM provisioning and discovery endpoints under /scim/v2, which your identity provider uses for user and group provisioning.
  • Terraform Enterprise admin endpoints under /api/v2/admin/*, which site administrators use to manage SCIM settings, SCIM tokens, provisioned SCIM groups for team mapping, and team-to-group links.

The Configure SCIM provisioning topic is the primary enablement page for this workflow.

Benefits

SCIM provisioning provides several key benefits for enterprise identity management:

Automated provisioning

When a new employee is added to your identity provider, SCIM automatically creates their account in Terraform Enterprise. Team membership is synchronized separately through SCIM group provisioning and team mapping. This eliminates manual account creation and reduces IT administrative overhead.

Reduced manual overhead

SCIM synchronizes user profile changes, such as email updates or group membership changes, automatically between your IdP and Terraform Enterprise. Administrators no longer need to manually update user information across multiple systems.

Enhanced security through instant deprovisioning

When an employee leaves your organization or loses Terraform Enterprise access in your IdP, SCIM immediately revokes their access to Terraform Enterprise. Unlike SAML authentication alone, which only updates access at login time, SCIM proactively removes access regardless of whether the user attempts to log in. This ensures that terminated employees cannot retain access to your infrastructure.

Centralized identity management

Your identity provider serves as the single source of truth for user identities. All user and group management happens in one place, reducing the risk of access inconsistencies and simplifying compliance auditing.

SCIM complements SAML

SCIM and SAML serve complementary but distinct purposes in Terraform Enterprise:

ProtocolPurposeWhen it runs
SAMLAuthenticationAt user login
SCIMProvisioningContinuously, as changes occur in IdP

You must enable SAML single sign-on (SSO) in Terraform Enterprise before configuring SCIM.

When SCIM is enabled, Terraform Enterprise ignores team membership information in SAML assertions. This prevents potential conflicts between the two systems and ensures that SCIM remains the authoritative source for provisioning.

When SCIM is enabled, Terraform Enterprise does not create users on login. You must provision users through SCIM before they can authenticate with SAML.

Key concepts

User types

Terraform Enterprise distinguishes between users provisioned in your IdP and users that you manually manage in the platform.

  • IdP-provisioned users: Users created and managed through SCIM. These users cannot be modified directly in Terraform Enterprise. Profile updates and deprovisioning must occur through the identity provider.
  • Manually-managed users: Users created directly in Terraform Enterprise, including site administrators created for recovery purposes. These users can be modified within Terraform Enterprise and are not affected by SCIM operations.

SCIM groups

SCIM groups represent groups from your identity provider. When your IdP syncs groups to Terraform Enterprise, Terraform Enterprise:

  • Stores them as SCIM groups.
  • Synchronizes group membership automatically.
  • Lets you link groups to Terraform Enterprise teams.

Automated team membership management

Link SCIM groups from your IdP to teams in Terraform Enterprise to enable automatic team membership management.

  • A single SCIM group can be linked to multiple Terraform Enterprise teams across different organizations, up to 10,000 teams per group.
  • Each Terraform Enterprise team can only be linked to one SCIM group.
  • When users are added or removed from a group in the IdP, Terraform Enterprise automatically updates their team memberships.
  • You cannot directly modify team membership in Terraform Enterprise when the team is linked to a SCIM group.
  • You cannot configure the owners team as a SCIM-managed team. This ensures administrators can always access Terraform Enterprise for troubleshooting.

Refer to Link SCIM groups to teams for detailed instructions.

Source of truth

Terraform Enterprise provides granular control over how user and team membership is managed:

  • Site-level control: Administrators can enable, pause, or disable SCIM provisioning for the entire Terraform Enterprise instance. Pausing SCIM preserves all existing configurations and mappings but stops processing updates from the IdP.
  • Team-level control: Administrators can pause SCIM synchronization for individual teams for debugging purposes. This lets administrators troubleshoot specific team mappings without affecting other teams.

Supported identity providers

Terraform Enterprise supports SCIM with the following identity providers and provider configurations:

  • Okta
  • Microsoft Entra ID
  • Supported generic SAML provider configurations

Terraform Enterprise implements SCIM as a custom application in each identity provider, not as a pre-built gallery application.

Terraform Enterprise does not claim broad interoperability with every SCIM client. The implementation is validated for Okta and Microsoft Entra ID request patterns.

SCIM interfaces

Terraform Enterprise implements SCIM User and Group resources, as well as the discovery endpoints required by common identity providers.

On the public /scim/v2 surface, Terraform Enterprise exposes:

  • Discovery endpoints under /scim/v2/ServiceProviderConfig, /scim/v2/Schemas, and /scim/v2/ResourceTypes.
  • User provisioning endpoints under /scim/v2/Users.
  • Group provisioning endpoints under /scim/v2/Groups.

Terraform Enterprise documents the separate admin JSON:API surface under /api/v2/admin/* in the admin API reference pages.

Terraform Enterprise partially implements the SCIM 2.0 specification. The following limitations apply:

  • Bulk operations are not supported.
  • Filtering is limited to equality (eq) lookups on the following set of attributes:
    • Users support userName eq and externalId eq.
    • Groups support displayName eq and externalId eq.
  • PATCH support is limited to the User and Group attributes described in the SCIM Users API and SCIM Groups API.
  • SCIM does not synchronize passwords or full profile data.

Related documentation

Edit this page on GitHub