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 perform management tasks for your organization's SCIM configuration after initial setup.

Overview

Use this page for the following operational tasks:

  • Disable or re-enable SCIM provisioning
  • Delete SCIM configuration
  • Rotate SCIM tokens
  • Manage user accounts

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

Disable and re-enable SCIM

You can disable SCIM to make changes or to troubleshoot potential misconfigurations. Disabling SCIM pauses all provisioning requests for your organization while presrving existing users, existing teams and their permissions, and organization memberships. Users can also continue logging in through SSO after SCIM is disabled.

  1. Log in to your HCP Terraform.
  2. Click Organization settings and then SCIM provisioning.
  3. Click the Manage drop-down menu and choose Disable SCIM.
  4. Complete the verification when prompted.

Complete the following steps to re-enable SCIM:

  1. Navigate to your organization settings in HCP Terraform, then SCIM provisioning.
  2. Click Enable SCIM. You must generate a new token and reconnect your identity provider.

Re-enabling SCIM does not automatically re-apply changes that your identity provider made while SCIM was disabled. You must restart provisioning in Entra ID or remove and re-add group assignments in Okta to synchronize any missed changes.

Delete SCIM configuration

You can delete your SCIM configuration to permanently remove your SCIM integration from HCP Terraform. The following activities take place when you delete your SCIM configuration:

  • HCP Terraform preserves existing provisioned users and teams.
  • The IdP no longer synchronizes with HCP Terraform.
  • Users that were managed through SCIM can still log in through SSO. HCP Terraform updates their team membership based on SAML membership information.

Deleting the SCIM configuration and removing the SSO configuration from your organization completely locks SCIM-managed users out of HCP Terraform. Because SCIM requires SSO for authentication, SCIM-managed users don't have their own password credentials. Manually-managed users can still log in with their username and password.

You must disable SCIM first before you can delete it.

  1. Log in to your HCP Terraform.
  2. Click Organization settings and then SCIM provisioning.
  3. Click the Manage drop-down menu and choose Disable SCIM.
  4. Confirm that you want to disable SCIM when prompted.
  5. Click Manage and then Delete SCIM.
  6. Confirm that you want to delete the configuration when prompted.

After deleting the SCIM configuration in HCP Terraform, remove or disable the SCIM connection in your identity provider.

Rotate SCIM tokens

Complete the following steps 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.

Manage user accounts

When SCIM is enabled, the IdP creates user accounts owned by the organization. In some cases, you may need to change organization-owned users managed through SCIM into user-owned accounts that you can manually manage. Conversely, you may need to change manually-managed users to SCIM-managed accounts owned by the organization.

The following use cases are examples of when you may need to convert user accounts:

  • You need a non-SCIM user to create additional organizations
  • You need an account for emergency access
  • You need to access multiple organizations in a single login session

Refer to SCIM user lifecycle for more information about users.

Change from user-owned to organization-owned

Complete the following steps to convert a manually-managed user account to a SCIM-managed account owned by the organization:

  1. Remove the user-owned account from your HCP Terraform organization.
  2. In your IdP, confirm the user is assigned to the HCP Terraform application.

When SCIM next provisions the user, it creates a new organization-owned account for them.

Change from organization-owned to user-owned

Because user accounts created through SCIM provisioning are scoped to a single organization and require SSO to authenticate, you can't directly convert an organization-owned account to a SCIM-managed account. Instead, the user and a member of the organization owners team must complete the following steps in order.

Warning

This process deletes the organization-owned account. The user loses access to the organization until the organization owner completes the invitation steps.

The user must complete the following steps first:

  1. Create a new HCP Terraform account using the same email address as their organization-owned account.
  2. Set a password on the new account.
  3. Verify the email address.

After the user completes account creation, the organization owner must complete the following steps:

  1. In your IdP, remove the user from the SSO access group so that SCIM deprovisions the organization-owned account.
  2. Invite the user-owned account to the organization.
  3. After the user accepts the invitation, add the user back to the SSO access group in your IdP.

To verify the change in HCP Terraform, navigate to Organization settings, then Users. An organization-owned user shows a SCIM provisioning status of Synced – Provisioned. A user-owned user shows a status of Synced – Claimed or no status.

Reactivate a user

When you deactivate a user in your IdP, HCP Terraform removes the user's access but does not automatically remove the user from their teams. When you reactivate the user, you may need to re-trigger provisioning to restore their team memberships.

Reactivate a user in Microsoft Entra ID

First, reactivate the user in Entra ID. If the user was previously removed from groups, trigger on-demand provisioning for the user in the Entra ID provisioning settings for your HCP Terraform application. Refer to the Entra ID documentation for more information.

Reactivate a user in Okta

First, reactivate the user in Okta. If the user was previously removed from groups, perform a group push in Okta to restore group memberships. Refer to the Okta documentation for more information.

If reactivation does not restore access as expected, refer to Troubleshoot SCIM provisioning for diagnostic steps.

Next steps

Refer to the following topics for more information about SCIM provisioning:

Edit this page on GitHub