Troubleshoot SCIM provisioning

This topic describes troubleshooting steps for diagnosing and resolving issues with SCIM provisioning in Terraform Enterprise.

Use this page for Terraform Enterprise-side behavior, SCIM responses, team linking, and operational follow-up. If the failure occurs before Terraform Enterprise receives the request, check your identity provider provisioning logs first.

For provider-specific setup, assignment, scope, and attribute-mapping checks, use the configure guides after these Terraform Enterprise-side checks.

Escalation path

Complete the following steps in order to investigate issues:

1. Check your IdP provisioning logs first for connection, assignment, scope, and attribute-mapping failures.
2. Check Terraform Enterprise audit logs when requests are reaching Terraform Enterprise but the resulting state is unexpected.
3. Check Terraform Enterprise service logs and run diagnostics for repeated 500 errors, reconciliation timeouts, or suspected platform issues.
4. Generate a support bundle and contact HashiCorp support if the issue persists after these checks.

Emergency access

Terraform Enterprise can grant site administrator access through SCIM. To ensure you can always log in and troubleshoot issues even if SCIM provisioning is misconfigured or your identity provider (IdP) is unavailable, maintain at least one manually managed non-SSO admin account.

Create a non-SSO admin account

We strongly recommend creating and maintaining a non-SSO admin account before enabling SCIM. This account provides a recovery path if you encounter issues with your SCIM or SAML configuration.

Before troubleshooting SCIM issues, verify that you have a non-SSO admin account for emergency access. This account should use an email address not associated with your identity provider.

To create a non-SSO recovery admin account in the Terraform Enterprise UI, open https://<TFE HOSTNAME>/public/signup/account, create the account, and grant it site administrator access.

If you need the Rails console recovery procedure, refer to Create a non-SSO admin account for recovery in the SAML troubleshooting documentation.

Pause SCIM for debugging

You can pause SCIM synchronization for the entire site or for individual teams so that you can isolate issues without deleting your configuration.

Pause SCIM at the site level

Pausing SCIM at the site level stops all SCIM provisioning requests for the Terraform Enterprise instance.

Terraform Enterprise site admin steps:

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

For the underlying site-level pause behavior, refer to Manage SCIM provisioning.

While SCIM is paused at the site level:

• Provisioning requests from your IdP to /scim/v2/Users and /scim/v2/Groups return 403 Forbidden because SCIM is disabled or paused.
• Existing users, groups, and team links are preserved.
• SCIM tokens remain valid and are not deleted.
• Users can continue to log in using SAML.
• Teams retain their configured links and pause state, and team-level SCIM metadata remains visible.

To resume SCIM synchronization, open Manage and click Resume SCIM provisioning.

Resuming site-level SCIM does not replay or backfill changes that your identity provider did not send while SCIM was paused. Terraform Enterprise resumes processing only new SCIM requests after you resume SCIM provisioning.

Pause SCIM for an individual team

You can pause SCIM synchronization for a specific team without affecting other linked teams.

Terraform Enterprise site admin steps in the UI:

1. Navigate to the team's Team Settings tab.
2. In the SCIM Sync section, click Pause Sync.
3. Confirm the action.

You can also pause or resume SCIM synchronization with the Team SCIM Group Mapping API.

For the full procedure, refer to Link SCIM groups to teams.

While team-level synchronization is paused:

• The team retains its current membership.
• SCIM updates to the linked group do not affect the team.
• The team remains linked to the SCIM group.
• Other teams linked to the same SCIM group continue to receive updates.
• Direct membership changes in Terraform Enterprise remain blocked while the link exists. To manage membership manually, unlink the team instead. Refer to Link SCIM groups to teams.

When you resume synchronization, Terraform Enterprise immediately reconciles the team's membership with the current SCIM group state.

Check HTTP status codes

Use the table that matches the endpoint family you are troubleshooting.

Public SCIM provisioning endpoints

The public SCIM endpoints /scim/v2/Users and /scim/v2/Groups are called by your IdP and authenticated with a SCIM token.

For exact status codes, validation rules, discovery endpoints, and request details, refer to:

• Public SCIM API
• SCIM Users API
• SCIM Groups API

Admin SCIM settings and token endpoints

The admin endpoints /api/v2/admin/scim-settings and /api/v2/admin/scim-tokens use site admin API credentials, not SCIM tokens.

For exact status codes, validation rules, and request details, refer to:

• Admin SCIM Settings API
• Admin SCIM Tokens API

Admin team linking endpoints

The admin endpoints /api/v2/admin/teams/:external_id/scim-group-mapping and /api/v2/admin/scim-groups are used for site-level team-linking operations.

For exact status codes, validation rules, and request details, refer to:

• Team SCIM Group Mapping API
• Admin SCIM Groups API

Common issues

This section describes common SCIM provisioning issues and their solutions.

401 Unauthorized errors

HTTP 401 errors indicate authentication problems with your public SCIM token.

Check for the following conditions:

• The Authorization header is missing.
• The Authorization header is malformed.
• The token is invalid or expired.
• The token belongs to another token type and is not a SCIM token.

The Terraform Enterprise site admin and IdP administrator must complete tasks to resolve this issue:

Terraform Enterprise site admin:

1. Navigate to Site Admin > SCIM > Tokens.
2. Verify that an active token exists and has not expired.
3. Check the last-used-at timestamp to confirm the IdP is successfully authenticating.
4. If necessary, create a new token. SCIM token values are displayed only once when created. If you lose the token value, create a new token and rotate the IdP to use it.

IdP administrator:

After the Terraform Enterprise site admin provides a new token, update the IdP configuration to use the new token and rerun the provisioning test.

403 Forbidden error

HTTP 403 errors returned by the public SCIM provisioning endpoints, /scim/v2/Users or /scim/v2/Groups, usually mean Terraform Enterprise is not currently accepting SCIM provisioning requests.

Check the following:

• SCIM is disabled.
• SCIM is paused at the site level.
• The deployment is not Terraform Enterprise.

Terraform Enterprise site admin and IdP administrators must complete tasks to resolve this issue.

Terraform Enterprise site admin:

1. Navigate to Site Admin > SCIM.
2. Verify that SCIM is enabled.
3. Verify that SCIM provisioning is enabled and not paused.

IdP administrator:

Retry provisioning from your IdP after Terraform Enterprise is accepting SCIM requests again.

Users not syncing

If Terraform Enterprise does not provision or update users, verify that the request is reaching Terraform Enterprise. If not, check your IdP provisioning logs, then check the configure guides for provider-specific assignment, scope, and mapping steps.

Check for the following conditions:

• The user is assigned or otherwise in scope for provisioning in your identity provider.
• The IdP is not sending a userName that already exists for another SCIM identity. That condition returns 409 Conflict.
• The IdP request includes at least one email entry. A primary email is preferred, but Terraform Enterprise can also use the first email entry if none is marked primary. Missing email data returns 400 Bad Request.
• If Terraform Enterprise already has a manually created user with the same email address, verify that the IdP is sending the same email address for that user so linking can occur.

If the issue is a duplicate userName:

1. Terraform Enterprise site admin should identify the existing SCIM-managed user that already owns that userName.
2. IdP administrator should rename the user in the IdP or correct the conflicting SCIM identity before retrying.
3. Retry provisioning.

If the issue is a delete request for a missing SCIM user, verify that the IdP is using the current Terraform Enterprise SCIM user id. Terraform Enterprise returns HTTP 404 Not Found for DELETE /scim/v2/Users/:id when that SCIM user no longer exists.

User deactivation or deletion does not behave as expected

Terraform Enterprise treats SCIM deactivation and deletion differently:

• When your IdP sends the active=false attribute, Terraform Enterprise suspends the user.
• When your IdP makes a DELETE request to the /scim/v2/Users/:id endpoint, Terraform Enterprise removes the SCIM identity and suspends the user.
• If the affected user is a SCIM-provisioned site administrator, Terraform Enterprise revokes site admin access.

If the user remains active in Terraform Enterprise, confirm that your IdP is sending either active=false or a SCIM delete request, not only removing the user from a group.

Deprovision triggers and timing are IdP-specific. If the expected change is not being sent, review your IdP provisioning logs and provider-specific deprovisioning guidance.

Groups not syncing

If SCIM groups are not being provisioned or membership changes are not reflected, verify that the request is reaching Terraform Enterprise. If not, check your IdP provisioning logs, then check the configure guides for provider-specific group-push, scope, and mapping steps.

Check for the following conditions:

• The group is configured for provisioning in your identity provider and is in scope for synchronization to Terraform Enterprise.
• Group membership updates reference Terraform Enterprise SCIM user IDs for users that were already provisioned through /scim/v2/Users.
• The IdP is not trying to create or rename a group to a displayName that already exists. That condition returns 409 Conflict.

If the issue is a duplicate group name, the IdP administrator should rename or remove the conflicting SCIM group in the identity provider before retrying.

Admin team linking fails

If linking a SCIM group to a team fails, check the following:

These are Terraform Enterprise site admin operations. For the full linking workflow, refer to Link SCIM groups to teams.

Check for the following conditions:

• The SCIM group has 1,000 or fewer members. Larger groups return 413 Payload Too Large.
• The team is not already linked to another SCIM group. Existing links return 409 Conflict.
• The SCIM group is not configured as the site admin group.
• The target team is not the owners team.

To resolve:

1. Split oversized IdP groups into smaller groups if needed.
2. Unlink any existing SCIM group before linking a different one to the same team.
3. Use a different SCIM group for team linking if the current group is the configured site admin group.
4. Leave the owners team manually managed.

Admin team sync pause or unpause fails

If pausing or unpausing a team link fails:

• Verify that the team is currently linked to a SCIM group.
• Verify that the request uses the admin endpoint /api/v2/admin/teams/:external_id/scim-group-mapping.
• Verify that scim-sync-paused is a boolean value.

If the team is not linked, the request fails. If the payload omits scim-sync-paused or uses a non-boolean value, the request is rejected.

For exact request and response behavior for link pause and resume, including repeated requests, refer to the Team SCIM Group Mapping API.

Only Terraform Enterprise site administrators can link, unlink, pause, or resume SCIM team links.

400 Bad Request error

Terraform Enterprise returns 400 when the SCIM request format is invalid. An invalid format includes unsupported filters or malformed payloads.

Common causes include:

• Unsupported SCIM filter expressions.
• Malformed JSON.
• Missing required attributes such as an email entry.
• Too many PATCH operations in a single request.

To resolve:

1. Compare the IdP request body with the SCIM Users API or SCIM Groups API requirements. Those references document supported PATCH forms, filter rules, and request limits.
2. Validate that the JSON is well formed.
3. Confirm that your IdP is only using supported equality filters. Users support userName eq and externalId eq. Groups support displayName eq and externalId eq.

413 Payload Too Large errors

The public SCIM endpoint returns an HTTP 413 error when one of the following events occur:

• The request body exceeds the maximum supported SCIM request size
• A request to create or update a SCIM group exceeds the maximum supported group membership.
• The linked SCIM group has more than 1,000 members.

If you receive 413 during public SCIM user or group provisioning calls, inspect both the IdP request payload size and the affected SCIM group membership count. Public group provisioning requests return 413 when they try to create or update a group with more than 1,000 members. Oversized public SCIM requests also return 413. If you receive 413 while linking a group to a team, reduce the group size before retrying the mapping.

For the exact public SCIM request-size and per-endpoint request limits, refer to the Public SCIM API and the SCIM Groups API.

429 Too Many Requests errors

HTTP 429 errors indicate your IdP or administrator is sending requests faster than Terraform Enterprise allows.

Terraform Enterprise applies the following SCIM-related rate limits:

For public SCIM /scim/v2/*, use the Retry-After header to determine how long to wait before retrying.

Admin SCIM 429 responses use the standard admin API error format.

For exact rate-limit values and response details, refer to the Public SCIM API, the SCIM Settings API, and the Team SCIM Group Mapping API.

If you frequently encounter rate limits:

1. For public SCIM /scim/v2/*, ask your IdP administrator to reduce provisioning frequency and avoid repeated full syncs during troubleshooting.
2. For admin SCIM settings or tokens, slow down site-level automation or scripted retries.
3. For admin team linking operations, stagger link changes when working with many teams.

500 Internal Server Error errors

HTTP 500 errors indicate Terraform Enterprise failed while processing the request.

For public SCIM /scim/v2/*, retry one time after confirming the IdP request is valid. If the error repeats, inspect Terraform Enterprise logs and diagnostics.

For admin team linking or reconciliation, 500 errors usually indicate an internal failure such as a transaction timing out.

Large linking operations use a 30-second transaction timeout. When a timeout occurs:

• The transaction rolls back completely.
• No partial membership changes are applied.
• The team retains its previous membership state.
• Your IdP or administrator must retry the operation.

If linking repeatedly times out, reduce the size of the linked SCIM group.

If 500 errors continue after a retry, inspect Terraform Enterprise service logs and run diagnostics. Refer to Logs and Perform diagnostics.

Check sync status

Terraform Enterprise tracks synchronization timestamps for SCIM-managed users and linked teams.

These sync-status fields are exposed on Terraform Enterprise API responses outside the public /scim/v2/* provisioning surface.

User sync status

For SCIM-managed users, the scim-updated-at attribute indicates when the user was last synchronized. You can inspect this in GET /api/v2/account/details for the current user and in GET /api/v2/admin/users responses when SCIM is enabled.

Use this timestamp to:

• Verify that IdP changes are being applied.
• Identify users that have not been updated recently.
• Troubleshoot synchronization delays.

Team sync status

For teams linked to SCIM groups, the scim-updated-at attribute indicates when the team's membership was last synchronized from the SCIM group. You can inspect this in GET /api/v2/teams/:external_id responses.

Use this timestamp to:

• Confirm that membership changes are propagating.
• Identify teams that may have synchronization issues.
• Verify that unpausing synchronization applied updates correctly.

Also check scim-linked, scim-group-name, and scim-sync-paused to confirm the link state.

Site admin group issues

If site admin access is not changing as expected, verify that the correct site admin group is configured in Site Admin > SCIM and that the relevant group membership update or SCIM settings change completed successfully.

For the site admin group behavior, including grant, revoke, remap, and clear semantics, refer to Manage SCIM provisioning.

Deleting or disabling SCIM does not automatically revoke site admin access that was already granted.

Audit logs

Terraform Enterprise logs SCIM operations for compliance and troubleshooting purposes. SCIM-related audit log entries include:

• User provisioning, replacement, update, and deprovisioning.
• Group creation, update, membership changes, and deletion.
• Team-to-group link creation and removal.
• Team sync pause or resume actions.
• SCIM configuration changes.
• Token creation and revocation.

Use audit logs to:

• Track user access changes for compliance reporting.
• Investigate unexpected permission changes.
• Verify that IdP changes are being applied correctly.
• Debug issues by reviewing the sequence of operations.

To inspect audit logs and service logs, refer to Logs.

Disable SCIM

Refer to Disable SCIM provisioning for the full impact, UI steps, and API behavior.

Contact support

If you cannot resolve your SCIM issue using the troubleshooting steps in this topic, contact HashiCorp support. Refer to Get support for Terraform Enterprise for instructions on opening a ticket, creating diagnostic support bundles, and other information.