Configure Microsoft Entra ID as the SCIM identity provider

This topic describes how to configure Microsoft Entra ID (formerly Azure Active Directory) as the SCIM identity provider (Id) for HCP Terraform. After completing this configuration, HCP Terraform can accept SCIM provisioning requests from Microsoft Entra ID for users and groups.

Background

Microsoft Entra ID provisions users and groups to HCP Terraform using the SCIM protocol. Entra ID acts as the source of truth for user identities and group membership. When you assign a user or group to your custom HCP Terraform application in Entra ID, Entra ID pushes those changes to HCP Terraform automatically.

HCP Terraform matches incoming SCIM users to existing accounts by email address. When a match is found, the existing account becomes SCIM-managed. When no match is found, HCP Terraform creates a new organization-owned account. IdP group names become team names in HCP Terraform directly. There is no separate name mapping.

You cannot use the Terraform Cloud gallery application from the Entra ID gallery for SCIM. You must create a custom, non-gallery enterprise application to complete this configuration.

To configure Microsoft Entra ID as the SCIM identity provider for HCP Terraform:

Create a custom enterprise application in Entra ID and configure SAML SSO on it.
Review and confirm attribute mappings for users and groups.
Enable provisioning and configure the SCIM base URL and token.
Assign users and groups to provision.
Start provisioning and verify the setup.

Requirements

Before you configure Microsoft Entra ID as the SCIM identity provider, you must enable SCIM in HCP Terraform and generate a SCIM token. Refer to Configure SCIM provisioning for instructions.

Create a custom application

You must create a custom, non-gallery enterprise application. You cannot use the existing Terraform Cloud application from the Entra ID gallery. Refer to the Microsoft Entra ID documentation for more information about creating enterprise applications.

Sign in to the Entra portal and choose Microsoft Entra ID.
Navigate to Enterprise Applications and select All Applications.
Select New application and then Create your own application.
Specify a name for the application, such as HCP Terraform, and click Next.
Enable Integrate any other application you don't find in the gallery (Non-gallery).
On the application integration page, find the Manage section and select Single sign-on.
On the Select a single sign-on method page, select SAML.
In the SAML Signing Certificate section, copy the App Federation Metadata URL.
Configure SAML SSO in HCP Terraform for this new custom application by providing the App Federation Metadata URL you copied in the previous step. Follow the instructions in Configure single sign-on with Microsoft Entra ID to complete this step.
In Entra ID, edit Attributes and Claims in the Single sign-on settings and set Unique User Identifier to user.userprincipalname.
In Entra ID attribute mapping, confirm the following mapping is present:
Source attribute Target attribute Mapping type Matching precedence
userPrincipalName username Direct 1

Source attribute	Target attribute	Mapping type	Matching precedence
`userPrincipalName`	`username`	Direct	1

Configure attribute mappings

Microsoft Entra ID uses attribute mappings to synchronize user data with HCP Terraform. Review and configure the default mappings in the Microsoft Entra admin center:

In the Provisioning settings, expand the Mappings section.
Click Provision Microsoft Entra ID Users to review user attribute mappings.

User attribute mappings

Verify the following user attribute mappings are configured in Entra ID:

Microsoft Entra ID attribute	SCIM attribute	Notes
`userPrincipalName`	`userName`	Primary identifier. Must match the SAML nameID.
`mail`	`emails[type eq "work"].value`	User's email address. Must match the email of any existing HCP Terraform user to avoid duplicate accounts.
`Switch([IsSoftDeleted], , "False", "True", "True", "False")`	`active`	User active status

If your SAML SSO nameID uses userPrincipalName but it does not match mail, SCIM creates duplicate user accounts. Ensure userPrincipalName matches the SAML nameID and the HCP Terraform account email before enabling SCIM.

Group attribute mappings

Microsoft Entra ID uses attribute mappings to synchronize group data with HCP Terraform. Review and configure the default mappings in the Microsoft Entra admin center:

Return to the Mappings section.
Click Provision Microsoft Entra ID Groups to review group attribute mappings.

Verify the following group attribute mappings are configured in Entra ID:

Microsoft Entra ID attribute	SCIM attribute	Notes
`displayName`	`displayName`	IdP group names become team names in HCP Terraform directly. There is no separate name mapping.
`members`	`members`	Group membership list

Nested group membership (groups within groups) is not supported. Use separate groups for SSO access control and SCIM team membership.

Enable provisioning

In Microsoft Entra ID, open your custom HCP Terraform application and configure SCIM provisioning:

Sign in to the Microsoft Entra admin center.
Navigate to Enterprise applications and select your custom HCP Terraform application.
Click Provisioning and select Get started or New configuration.
Complete the following fields in the Admin credentials section:
- In the Tenant URL field, enter the base URL you copied from HCP Terraform. Refer to Enable SCIM for more information.
- In the Secret token field, enter the SCIM token you copied from HCP Terraform. Refer to Enable SCIM for more information.
Click Test Connection to verify the configuration.
Click Create after the configuration is verified.
Click Start provisioning.
Click Manage on the left side and select Users and groups to assign users and groups.

Entra ID processes provisioning changes on a recurring cycle that typically runs every 40 minutes. You can reduce this delay by initiating on-demand provisioning in the Entra ID UI or via the Microsoft Graph API.

Configure users and groups to provision

Configure which users and groups Microsoft Entra ID synchronizes to HCP Terraform:

In Microsoft Entra ID, select Manage > Users and groups and assign users and groups to your custom HCP Terraform application.

When assigning groups, consider the following behaviors:

IdP group names become team names in HCP Terraform directly. There is no separate name mapping step.
Group names must be fewer than 90 characters.
Nested group membership is not supported.
HCP Terraform supports a maximum of 3,000 IdP groups and 1,000 members per group.

We also recommend using separate groups for SSO access, which controls who can sign in, and SCIM team membership, which controls team assignments within HCP Terraform.

Before enabling SCIM, review existing team memberships. When an IdP group name matches an existing HCP Terraform team name, SCIM takes over that team and replaces its membership with the IdP group membership.

Start provisioning

After you have configured SCIM provisioning, start the provisioning service:

In Microsoft Entra ID, in the Provisioning settings, expand the Settings section.
Set Provisioning Status to On.
Click Save to start provisioning.

Initial provisioning cycle

The first provisioning cycle is a complete synchronization of the users and groups currently in scope. Initial provisioning may take longer than later syncs, especially for large directories.

Monitor provisioning logs

In Microsoft Entra ID, monitor the provisioning status and logs to verify successful synchronization:

In your enterprise application, select Provisioning from the left navigation.
Click View provisioning logs to see detailed operation logs.
Review the logs for any errors or warnings.

Incremental cycles

After the initial cycle completes, later syncs only process subsequent changes.

Verify the setup

Test SCIM with a small rollout before using it more broadly.

Assign a test user in your identity provider.
Assign a group in your identity provider.
Wait for synchronization and confirm that the user appears in HCP Terraform with a status of Synced.
Navigate to Teams in HCP Terraform and verify groups are synchronized.
Test that the user can log in using SSO.
Unassign the test user in your identity provider and verify that HCP Terraform removes the user's access.

We recommend starting with a group of 5–10 users before rolling out more broadly.

Troubleshooting

This section describes common issues specific to Microsoft Entra ID SCIM integration and their solutions.

Duplicate users created

If SCIM creates new users instead of linking to existing HCP Terraform users:

Verify the primary email in Entra ID matches the HCP Terraform account email exactly.
Ensure userPrincipalName matches the SAML nameID. If your SAML nameID uses userPrincipalName and it does not match mail, SCIM creates duplicate accounts.
Delete duplicate users and re-sync.

Synchronization not working

If changes in Entra ID are not reflected in HCP Terraform:

Check the token expiration date in HCP Terraform.
Test the connection in the Entra ID provisioning configuration.
Check the Entra ID provisioning logs for errors.
Verify the base URL is correct.
Verify when the last provisioning cycle executed. Entra ID syncs every 40 minutes, so ensure that enough time has passed for synchronization.

Connection test fails

Verify the tenant URL matches the base URL from HCP Terraform.
Verify the SCIM token is valid and has not expired. Generate a new token if necessary.

Next steps

You can complete the following actions after completing your SCIM configuration:

Verify that groups are assigned to the enterprise application if groups are scoped by assignment.
Verify that groups have fewer than 1,000 members. Larger groups are rejected by the public SCIM group provisioning endpoints.
Review SCIM user management to understand how SCIM-managed users work in HCP Terraform.
Review SCIM group management to understand how SCIM groups integrate with HCP Terraform teams.