Troubleshoot SCIM provisioning

This topic describes troubleshooting steps for diagnosing and resolving issues with SCIM provisioning in HCP Terraform. Use this page for HCP Terraform-side behavior, SCIM responses, and operational follow-up.

If a failure occurs before HCP Terraform receives the request, check your identity provider provisioning logs first.

For provider-specific setup, assignment, scope, and attribute-mapping checks, refer to the configure guides.

Emergency access

The identity provider (IdP) doesn't manage members of the owners team when SCIM is enabled. This to preserve emergency access even when SCIM is misconfigured or your IdP is unavailable.

We strongly recommend maintaining at least two accounts that aren't provisioned and managed through SCIM so that you can access the system in an emergency. Add your emergency access accounts, also called break-glass accounts, to the owners team before enabling SCIM. These accounts provide a recovery path if you encounter issues with your SCIM or SAML configuration.

Before troubleshooting SCIM issues, verify that your organization has an account for emergency access in the owners team. Use an email address for this account that is not associated with an organization-owned user.

Organization-owned users cannot serve as emergency access accounts because they lack password authentication and require SSO to log in.

Refer to Owners team and emergency access for more information.

Pause SCIM for debugging

You can disable SCIM synchronization for your organization so that you can isolate issues without deleting your configuration.

Disabling SCIM at the organization level stops all SCIM provisioning requests for your HCP Terraform organization:

1. Navigate to Organization settings > SCIM provisioning.
2. Click Manage.
3. Click Disable SCIM.
4. Confirm the action.

For more information about disabling SCIM, refer to Manage SCIM provisioning.

While SCIM is disabled:

• Changes to users and groups in your IdP are not synchronized to HCP Terraform.
• Existing provisioned users and teams do not change.
• Users can continue to log in using SSO, including SCIM-managed users.

To re-enable SCIM provisioning, navigate to Organization settings > SCIM provisioning and click Enable SCIM.

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

Check HTTP status codes

You can troubleshoot issues by cross-referencing error code information with your SCIM implementation. For status codes, validation rules, and request details for each endpoint family, refer to the corresponding API reference:

• SCIM API
• SCIM Users API
• SCIM Groups API

The following table provides an overview of error codes and links to more details and resolution steps.

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.

SCIM tokens have a mandatory expiration date between 30 days and one year from creation. Check the token expiration date in Organization settings > SCIM provisioning to confirm the token has not expired.

The HCP Terraform organization owner and IdP administrator each have steps to complete to resolve this issue.

HCP Terraform organization owner:

1. Navigate to Organization settings > SCIM provisioning > Tokens.
2. Verify that an active token exists and has not expired.
3. If necessary, generate a new token. Set an expiration date between 30 days and 1 year. SCIM token values are displayed only once when generated. If you lose the token value, generate a new token and update the IdP to use it.

IdP administrator:

After the HCP Terraform organization owner 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 SCIM provisioning endpoints, /scim/v2/Users or /scim/v2/Groups, usually mean HCP Terraform is not currently accepting SCIM provisioning requests.

Check if SCIM is disabled:

1. Navigate to Organization settings > SCIM provisioning.
2. Verify that SCIM is enabled.

After checking the SCIM integration status, the IdP administrator should retry provisioning from your IdP.

Users not syncing

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

Verify that the user is assigned or otherwise in scope for provisioning in your identity provider.

Duplicate users

If SCIM creates a new account instead of linking to an existing account, the primary email address sent by SCIM does not match the email address of the existing HCP Terraform account. Complete the following steps to resolve this issue:

1. Verify that the primary email address in your IdP matches the email address of the existing HCP Terraform account exactly, including letter case.
2. Remove the duplicate account and re-sync.

If the organization has two accounts for the same person where one is SCIM-managed and one is manually managed, the SAML nameID and the SCIM userName are using different IdP attributes. When the stored scim_username does not match the nameID sent at login, HCP Terraform cannot find the SCIM-managed user and triggers the SSO account-linking flow, which creates a second manually managed account. Refer to User lifecycle for more information.

Complete the following steps to resolve this issue:

1. Confirm that the SAML nameID and the SCIM userName mapping use the same IdP attribute. For Entra ID, both the Unique User Identifier in the SAML configuration and the userName attribute mapping must be userPrincipalName.
2. Remove the manually managed account created through the SSO link flow.
3. Re-provision the user through SCIM.

User deactivation or deletion does not behave as expected

HCP Terraform handles between SCIM deactivation and deletion differently. The exact behavior depends on your IdP:

• When your IdP deactivates a user, HCP Terraform sets the user status to inactive and removes their ability to log in. Okta typically sends an inactive update immediately. Entra ID initially sets the user to inactive, then may send a delete request after 30 days.
• When your IdP sends a DELETE request, HCP Terraform either removes the user from the organization or deletes the user from the system depending on the type of account. Users that own and manually manage their accounts are removed from the organization, whereas users provisioned and managed in the IdP are deleted.
• Deactivating or deleting a user does not automatically remove the user from teams in HCP Terraform. Remove the user from all group memberships in your IdP before deactivating or deleting them.

If the user remains active in HCP Terraform, confirm that your IdP is sending a deactivation or delete event, not only removing the user from a group.

Deprovision triggers and timing are IdP-specific. If the IdP doesn't send the change you expect, 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 HCP Terraform. If not, check your IdP provisioning logs, then check the configuration 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 HCP Terraform.
• Group membership updates reference HCP Terraform 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, rename or remove the conflicting SCIM group in the identity provider, then re-trigger synchronization.

HCP Terraform team names have a maximum length of 90 characters. If an IdP group name exceeds 90 characters, HCP Terraform cannot create the corresponding team. Rename the IdP group to 90 characters or fewer before retrying.

400 Bad Request error

HCP Terraform 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 SCIM provisioning endpoints return 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 details about sending requests to the SCIM provisioning endpoints, such as request-size and per-endpoint request limits, refer to SCIM provisioning API endpoints and SCIM Groups API.

429 Too Many Requests errors

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

All SCIM provisioning endpoints have a rate limit of 30 requests per second. Refer to the SCIM provisioning API endpoints for rate limit values, response codes, and details.

For SCIM /scim/v2/*, add the Retry-After header to determine how long to wait before retrying. If you frequently encounter rate limits, ask your IdP administrator to reduce provisioning frequency and avoid repeated full syncs during troubleshooting.

500 Internal Server Error errors

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

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

If 500 errors continue after a retry, contact HashiCorp support. Refer to Get support for HCP Terraform for instructions on opening a ticket.

Check sync status

HCP Terraform tracks synchronization timestamps for SCIM-managed users and linked teams. These sync-status fields are visible in the HCP Terraform UI and 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 when SCIM is enabled.

In the HCP Terraform UI, navigate to Organization settings > Users to view the Last SCIM Sync (UTC) timestamp and the SCIM provisioning status for each user.

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.

The following table describes the team statuses that indicate the SCIM provisioning state:

Audit events

For compliance and troubleshooting purposes, HCP Terraform logs SCIM operations. SCIM-related audit events include:

• User provisioning, replacement, update, and deprovisioning.
• Group creation, update, membership changes, and deletion.

• SCIM configuration changes.

• Token creation and revocation.

Use audit events 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 events, refer to the audit trails API documentation.

Delete SCIM configuration

Refer to Delete 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. Visit the IBM support page for support articles and to open a case.