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

Configure SCIM provisioning

This topic provides the setup workflow for configuring SCIM provisioning in Terraform Enterprise and then configuring your identity provider.

Overview

Complete the following steps to configure SCIM provisioning:

  1. Enable SAML SSO. SCIM handles provisioning, but SAML handles sign-in. Refer to Configure SAML.
  2. Enable SCIM provisioning in Terraform Enterprise.
  3. Create a SCIM token for your identity provider. Refer to Tokens.
  4. Configure your identity provider with the Terraform Enterprise SCIM base URL, token, and attribute mappings.
  5. Map IdP groups to Terraform Enterprise teams. Refer to Link SCIM groups to teams.
  6. Test and verify the setup before broader rollout.

SCIM states

StateWhat it means
DisabledDefault state. Terraform Enterprise does not process public SCIM provisioning requests to /scim/v2/Users or /scim/v2/Groups. You cannot pause SCIM until it is enabled.
EnabledTerraform Enterprise processes public SCIM provisioning requests to /scim/v2/Users and /scim/v2/Groups. Your identity provider can create and update users and groups. Team membership sync happens only for teams that are linked to a SCIM group.
PausedSCIM stays enabled, but Terraform Enterprise stops processing public SCIM provisioning requests to /scim/v2/Users and /scim/v2/Groups. Existing SCIM users, groups, team links, and tokens stay in place. Users can still sign in with SAML.

Requirements

Before you enable SCIM:

  • You must be a site administrator. For more information, refer to Site Administration Permissions.
  • SAML SSO must already be enabled. SCIM handles provisioning. SAML handles sign-in. For setup steps, refer to Configure SAML.
  • Configure SCIM on the same identity provider that you use for SAML SSO.
  • Terraform Enterprise supports SCIM with Microsoft Entra ID, Okta, and supported generic SAML provider configurations. We provide setup guides for Okta and Microsoft Entra ID.
  • Keep at least one non-SSO admin account for recovery.

Configure Terraform Enterprise for SCIM

  1. Open your user icon menu and click Site Admin, or go to https://<TFE_HOSTNAME>/app/admin/scim.
  2. Click Enable SCIM provisioning.
  3. Copy the SCIM base URL. Use https://<TFE_HOSTNAME>/scim/v2 when you configure your identity provider.

After you enable SCIM, generate a token and configure your identity provider.

For API-based configuration, refer to the Admin SCIM Settings API.

Create a SCIM token

Your identity provider uses a SCIM token to authenticate to Terraform Enterprise.

  1. In Site Admin > SCIM, click Create Token.
  2. Enter a description.
  3. Choose an expiration.
  4. Copy the token and store it securely.

Terraform Enterprise shows the token only once.

You can keep more than one active SCIM token at the same time. This lets you rotate tokens without downtime. For detailed token management steps, refer to Tokens.

Configure your identity provider

Use one of the following provider-specific setup guides:

You need the following information:

  • the SCIM base URL: https://<TFE_HOSTNAME>/scim/v2
  • a SCIM token generated in Terraform Enterprise
  • the attribute mappings required by your identity provider

When SCIM is enabled and not paused, Terraform Enterprise can create and update users and groups from incoming SCIM requests. Team membership does not change until you link a SCIM group to a Terraform Enterprise team.

Verify the setup

Test SCIM with a small rollout before using it more broadly.

  1. Provision a test user from your identity provider and confirm the user appears in Terraform Enterprise.
  2. Provision a test group and confirm the SCIM group appears in Terraform Enterprise.
  3. Link the SCIM group to a test team. Refer to Link SCIM groups to teams.
  4. Confirm that team membership updates as expected.
  5. Deactivate or unassign the test user in your identity provider and verify that Terraform Enterprise suspends the user.

Use this test pass to confirm token setup, attribute mappings, and linked-team behavior before wider rollout.

Next steps

After initial setup, use the following topics to manage and troubleshoot SCIM provisioning:

  • Maintain the site-level SCIM configuration, including pause and resume behavior, site admin group mapping, token rotation, and disabling SCIM. Refer to Manage SCIM.
  • Manage group-to-team links and team-level synchronization behavior. Refer to Link SCIM groups to teams.
  • Troubleshoot provisioning, synchronization, and token issues. Refer to Troubleshoot SCIM provisioning.

Refer to Integration settings for the admin interface reference for the Enable SCIM provisioning setting.

API reference

For endpoint-specific behavior, request and response details, limits, and rate limits, refer to:

Edit this page on GitHub