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

Troubleshoot SCIM provisioning

This topic provides troubleshooting guidance for common issues with SCIM (System for Cross-domain Identity Management) provisioning on HashiCorp Cloud Platform (HCP). For more information about SCIM provisioning, refer to SCIM provisioning.

Sync failures

SCIM sync failures can occur for several reasons. The following sections describe common causes and resolution steps.

Common causes

  • Invalid SCIM token - The SCIM token may have expired or been regenerated
  • Network connectivity issues - Your identity provider cannot reach the HCP SCIM endpoint
  • Quota exceeded - Your organization has reached the maximum number of users, groups, or group members
  • Attribute mapping errors - Required attributes are missing or incorrectly mapped

How to diagnose

  1. Check the SCIM provisioning status in HCP:
    • Log in to HCP and go to your organization
    • Click Organization settings and then SCIM provisioning
    • Review the sync status and any error messages
  2. Check your identity provider's provisioning logs for error messages
  3. Verify that the SCIM token is valid and has not been regenerated
  4. Verify that your identity provider can reach the HCP SCIM endpoint

Resolution steps

  1. If the SCIM token is invalid, generate a new token in HCP and update it in your identity provider
  2. If you have reached a quota limit, contact HashiCorp support to request a limit increase
  3. If attribute mappings are incorrect, update them in your identity provider according to the SCIM provisioning documentation
  4. If network connectivity is an issue, verify that your identity provider can reach https://api.cloud.hashicorp.com

Attribute mapping errors

Attribute mapping errors occur when required user or group attributes are missing or incorrectly configured in your identity provider.

Common attribute issues

  • Missing required attributes - The userName, emails, name.givenName, or name.familyName attributes are not mapped
  • Incorrect attribute format - Attributes are mapped to the wrong SCIM field
  • Unsupported attributes - Your identity provider is sending attributes that HCP does not support

Provider-specific considerations

Microsoft Entra ID:

  • Ensure you have removed unsupported default attribute mappings
  • Verify that the email identifier is derived from the Email field under Contact information, not the User principal name field
  • HCP generates a base URL specific to Entra ID. Confirm that you have copied the correct base URL to your IdP. Refer to Enable SCIM provisioning on HCP for more information.

Okta:

  • Verify that the API token includes the Bearer prefix
  • Ensure that Create users, Update User Attributes, and Deactivate Users are enabled

How to verify correct mappings

  1. Review the attribute mappings in your identity provider
  2. Compare them to the attribute mapping tables in the SCIM provisioning documentation
  3. Ensure that all required attributes are mapped
  4. Remove any unsupported attribute mappings

Quota exceeded errors

HCP enforces quotas to ensure optimal performance. If you exceed a quota, SCIM sync fails for the affected resource type.

Understanding quota limits

For current quota limits, refer to the HCP support page.

How to check current usage

  1. Log in to HCP and go to your organization
  2. Click Access control (IAM).
  3. Click Users to review the current count of users and Groups to review the current count of groups.

Contact support for limit increases

If your organization requires higher limits, contact HashiCorp support with the following information:

  • Your organization ID
  • The current quota limit
  • The requested quota limit
  • Business justification for the increase

User or group not syncing

If a specific user or group is not syncing from your identity provider to HCP, complete the following troubleshooting steps.

Verify SCIM is enabled

  1. Log in to HCP and go to your organization
  2. Click Organization settings and then SCIM provisioning
  3. Verify that SCIM provisioning is enabled and the status is active.

Check identity provider assignment

  1. Sign in to your identity provider
  2. Navigate to the HCP application
  3. Verify that the user or group is assigned to the application
  4. If the user or group is not assigned, assign them and wait for the next sync cycle

Verify attribute mappings

  1. Review the attribute mappings for the user or group in your identity provider
  2. Ensure that all required attributes are present and correctly formatted
  3. For users, verify that the email address is valid and unique

Check SCIM provisioning status

  1. In HCP, navigate to Users or Groups
  2. Locate the user or group in the list
  3. Check the SCIM provisioning column for the status
  4. The status is Synced when the IdP manages the user or group using SCIM. Any other status indicates that the user or group is managed in HCP, even if access to HCP is managed through the IdP.

Duplicate users or groups

Duplicate users or groups can occur when SCIM provisioning is enabled and conflicts with existing HCP resources.

Understanding conflict handling

When you enable SCIM provisioning, HCP checks your identity provider directory to determine if users or groups already exist in HCP:

  • For users - If a user with the same email address exists in both HCP and your identity provider, SCIM will only manage SSO-based users in HCP.
  • For groups - If a group with the same name exists in both HCP and your identity provider, the identity provider group takes precedence and replaces the existing HCP group.

How duplicates occur

Duplicates can occur in the following scenarios:

  • A user or group exists in HCP before SCIM is enabled, but the email address or name does not match exactly
  • A user or group is manually created in HCP after SCIM is enabled
  • Multiple identity provider users have the same email address

Resolution steps

  1. Identify the duplicate users or groups in HCP
  2. Determine which user or group should be the source of truth
  3. If the identity provider should be the source of truth, remove the duplicate from HCP
  4. If HCP should be the source of truth, remove the duplicate from your identity provider
  5. Wait for the next sync cycle to complete

Token authentication failures

Token authentication failures occur when the SCIM token is invalid, expired, or incorrectly configured in your identity provider.

Token expiration

SCIM tokens do not expire automatically, but they can be regenerated in HCP. If you regenerate a token, you must update it in your identity provider.

Token regeneration steps

  1. Log in to HCP and go to your organization
  2. Click Organization settings and then SCIM provisioning
  3. Click Generate SCIM token
  4. Copy the new token value
  5. Update the token in your identity provider

Updating token in identity provider

Microsoft Entra ID:

  1. Sign in to the Microsoft Entra admin center
  2. Navigate to your HCP application
  3. Click Provisioning and then Admin credentials
  4. Update the Secret token field with the new token
  5. Click Test Connection to verify
  6. Click Save

Okta:

  1. Sign in to Okta
  2. Navigate to your HCP application
  3. Click the Provisioning tab
  4. Click Edit in the API Integration section
  5. Update the API Token field with Bearer followed by the new token
  6. Click Test API Credentials to verify
  7. Click Save

Provider-specific issues

The following sections describe common issues specific to each supported identity provider.

Microsoft Entra ID

Feature flag requirement:

Microsoft Entra ID requires a feature flag to be appended to the Base URL. If you do not include this flag, SCIM provisioning fails.

Resolution: Ensure that you have appended ?aadOptscim062020 to the Base URL in the Tenant URL field. For example: https://api.cloud.hashicorp.com/scim/v2/organizations/YOUR_ORG_ID?aadOptscim062020

Unsupported attribute fields:

Microsoft Entra ID includes default attribute mappings that are not supported by HCP. If you do not remove these mappings, SCIM provisioning may fail or produce unexpected results.

Resolution: Remove any attribute mappings that are not listed in the SCIM provisioning documentation. Only include the supported attributes for users and groups.

Email field configuration:

The email identifier for each user must be derived from the Email field under Contact information in Microsoft Entra ID. Updates to the User principal name field are not reflected in HCP.

Resolution: Verify that the mail attribute is mapped to emails[type eq 'work'].value in your attribute mappings.

Okta

API integration requirements:

Okta requires the SCIM token to be prefixed with Bearer in the API Token field. If you do not include this prefix, authentication fails.

Resolution: Ensure that the API Token field contains Bearer followed by your SCIM token. For example: Bearer your-scim-token-here

Provisioning option configuration:

Okta requires specific provisioning options to be enabled for SCIM to function correctly. If these options are not enabled, users and groups are not synced.

Resolution: Verify that the following options are enabled in the Provisioning tab:

  • Create users
  • Update User Attributes
  • Deactivate Users

Ping ID

Common configuration issues:

Ping ID configuration issues typically relate to incorrect Base URL or SCIM token values.

Resolution: Verify that you have correctly entered the Base URL and SCIM token from HCP into your Ping ID configuration. Refer to the Ping ID documentation for detailed configuration steps.

IBM Verify

Common configuration issues:

IBM Verify configuration issues typically relate to incorrect Base URL or SCIM token values.

Resolution: Verify that you have correctly entered the Base URL and SCIM token from HCP into your IBM Verify configuration. Contact IBM Verify support or refer to the IBM Verify documentation for detailed configuration steps.

Get support

If you continue to experience issues with SCIM provisioning after following the troubleshooting steps in this topic, contact HashiCorp support.

When contacting support, provide the following information:

  • Your HCP organization ID
  • The identity provider you are using
  • A description of the issue
  • Any error messages from HCP or your identity provider
  • Steps you have already taken to troubleshoot the issue
  • Screenshots of your SCIM configuration (with sensitive information redacted)

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

Edit this page on GitHub