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

Manage SCIM provisioning

This page explains how to maintain the site-level SCIM configuration after initial setup.

Overview

Use this page for the following operational tasks:

  1. Pause or resume SCIM provisioning for the Terraform Enterprise instance.
  2. Configure or update the site admin group.
  3. Configure or update the site auditor group.
  4. Rotate SCIM tokens.
  5. Disable SCIM when necessary.

For the initial setup workflow, refer to Configure SCIM provisioning.

Pause and resume SCIM provisioning

Pausing SCIM is different from disabling it. When SCIM is paused, Terraform Enterprise keeps the existing SCIM data and tokens, but stops processing provisioning requests from your identity provider.

Pause SCIM provisioning

  1. Open Site Admin > SCIM.
  2. Open Manage.
  3. Click Pause SCIM provisioning.
  4. Confirm the action.

While SCIM is paused:

  • Existing SCIM users, groups, team links, and tokens stay in place.
  • Public provisioning requests to /scim/v2/Users and /scim/v2/Groups return 403 Forbidden.
  • Linked teams stop receiving SCIM updates.
  • Users can still sign in with SAML.

Resume SCIM provisioning

  1. Open Site Admin > SCIM.
  2. Open Manage and click Resume SCIM provisioning.

When you resume SCIM:

  • Terraform Enterprise starts processing provisioning requests again.
  • SCIM-linked teams can receive updates again.
  • Team links that were paused individually stay paused until you resume them.

For team-level pause and resume behavior, refer to Link SCIM groups to teams.

Configure site admin group

Use a SCIM group to grant site administrator access automatically.

  1. Open Site Admin > SCIM.
  2. In Site Admin IdP Group, select the SCIM group to use for site admins.
  3. Click Update site admin provisioning.

Site admin group behavior

  • Setting or changing the selected SCIM group updates site admin access immediately for the current members of the mapped group.
  • Members added to the selected SCIM group through later SCIM group updates also gain site admin access.
  • Suspended users in the selected SCIM group do not receive site admin access until they are reactivated.
  • When you change the site admin group, Terraform Enterprise revokes site admin access from users in the previous mapped group who currently have the SITE_ADMIN role, then grants site admin access to the current members of the new mapped group.
  • Clearing the site admin group removes the mapping. Existing site administrator grants are not automatically revoked.
  • A SCIM group used for site admin access cannot also be linked to a Terraform Enterprise team.
  • When SCIM is enabled, use this setting to manage site admin access. Terraform Enterprise does not use SAML site admin attributes for site admin provisioning.

We still recommend keeping at least one non-SSO admin account for recovery.

Configure site auditor group

Use a SCIM group to grant the Site Auditor role automatically. The Site Auditor role provides read-only, cross-organization visibility into all resources in the instance. The Site Auditor role is available in Terraform Enterprise only. It is not available in HCP Terraform.

  1. Open Site Admin > SCIM.
  2. In Site Auditor IdP Group, select the SCIM group to use for site auditors.
  3. Click Update site auditor provisioning.

Site auditor group behavior

  • Setting or changing the selected SCIM group updates Site Auditor access immediately for the current members of the mapped group.
  • Members added to the selected SCIM group through later SCIM group updates also gain the Site Auditor role.
  • Suspended users in the selected SCIM group do not receive the Site Auditor role until they are reactivated. When a suspended user is reactivated, Terraform Enterprise re-grants the role if the user is still a member of the configured site auditor group.
  • When you change the site auditor group, Terraform Enterprise revokes the Site Auditor role from members of the previous mapped group, then grants the role to the current members of the new mapped group.
  • Clearing the site auditor group removes the mapping. Existing Site Auditor grants are not automatically revoked.
  • Service accounts cannot be granted the Site Auditor role.
  • A SCIM group used for the site auditor mapping cannot also be the site admin group or be linked to a Terraform Enterprise team. Terraform Enterprise rejects a mapping that conflicts with either.
  • When SCIM is enabled, use this setting to manage Site Auditor access. Terraform Enterprise does not use SAML site auditor attributes for Site Auditor provisioning.

Rotate SCIM tokens

To rotate a SCIM token:

  1. Generate a new token.
  2. Update your identity provider to use the new token.
  3. Verify that provisioning still works.
  4. Delete the old token.

Deleting a token revokes it immediately. SCIM requests that still use that token fail until your identity provider starts using another valid token.

For detailed token lifecycle guidance, refer to Tokens.

Disable SCIM provisioning

Disabling SCIM is different from pausing it. Disabling removes the SCIM configuration from Terraform Enterprise.

When you disable SCIM, Terraform Enterprise:

  • deletes all SCIM groups
  • deletes all SCIM group memberships
  • deletes all team-to-SCIM-group links
  • deletes all SCIM identities
  • revokes all SCIM tokens

Terraform Enterprise keeps:

  • existing users
  • existing teams and their permissions
  • organization memberships
  • existing site administrator grants

Users can still sign in with SAML after SCIM is disabled.

  1. Open Site Admin > SCIM.
  2. Open Manage and click Disable SCIM provisioning.
  3. Review the warning.
  4. Confirm the action.
  5. Remove or disable the SCIM connection in your identity provider.

If you enable SCIM again later, you must generate new tokens and reconnect your identity provider.

If you disable SCIM through the admin settings API, use DELETE /api/v2/admin/scim-settings. Do not use PATCH with enabled=false; Terraform Enterprise rejects that request.

After the delete completes, Terraform Enterprise resets the SCIM settings to enabled=false, paused=false, and clears the configured site admin group without revoking existing site administrator grants. Repeating the delete while SCIM is already disabled is safe and leaves SCIM in the same disabled state.

Related docs

Edit this page on GitHub