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 for Terraform Enterprise. After completing this configuration, Terraform Enterprise can accept SCIM provisioning requests from Microsoft Entra ID for users and groups.

Overview

Complete the following steps to configure Entra ID as your SCIM IdP:

1. Create a SCIM token
2. Configure provisioning in Microsoft Entra ID
3. Configure attribute mappings
4. Configure users and groups to provision
5. Start provisioning

Prerequisites

Before configuring SCIM provisioning with Microsoft Entra ID, verify that you meet the following requirements:

• SAML SSO configured: You must have SAML single sign-on configured with Microsoft Entra ID for your Terraform Enterprise instance. Refer to Configure Azure Active Directory as the Identity Provider for instructions.
• SCIM enabled in Terraform Enterprise: SCIM must be enabled in your Terraform Enterprise instance. Refer to Configure SCIM provisioning for instructions.
• Entra ID admin access: You must have administrative access to Microsoft Entra ID with permissions to configure enterprise application provisioning.
• Non-SSO admin account: We strongly recommend creating a non-SSO admin account for recovery before enabling SCIM. This account allows you to log in and troubleshoot if there are issues with your SCIM or SAML configuration.

Create a SCIM token

Create a SCIM token that Entra ID uses to authenticate with Terraform Enterprise:

1. On the SCIM settings page in Terraform Enterprise, navigate to the SCIM Tokens section.
2. Click Create Token.
3. Enter a Description for the token, such as Microsoft Entra ID Provisioning.
4. Optionally, configure the token expiration.
5. Click Create Token.
6. Copy the token value and store it securely. You need this token when configuring Entra ID.

Terraform Enterprise only displays the token value once. You cannot retrieve the token value after you close the dialog. If you lose the token, you must create a new one.

For complete instructions on managing tokens, refer to Tokens.

Configure provisioning in Microsoft Entra ID

In Microsoft Entra ID, open your existing Terraform Enterprise enterprise application and configure SCIM provisioning:

1. Sign in to the Microsoft Entra admin center.

2. Navigate to Identity > Applications > Enterprise applications.

3. Select your existing Terraform Enterprise application that you configured for SAML SSO.

4. In the left navigation, select Provisioning.

5. Click Get started to begin the provisioning configuration.

6. Set Provisioning Mode to Automatic.

7. Expand the Admin Credentials section.

8. In the Tenant URL field, enter your Terraform Enterprise SCIM endpoint:

   https://<TFE_HOSTNAME>/scim/v2
   

   Replace <TFE_HOSTNAME> with your Terraform Enterprise hostname.

9. In the Secret Token field, paste the SCIM token you created in Terraform Enterprise.

10. Click Test Connection to verify that Microsoft Entra ID can connect to Terraform Enterprise.

11. If the connection test succeeds, click Save to save the provisioning configuration.

Configure attribute mappings

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

1. In the Provisioning settings, expand the Mappings section.
2. 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:

Group attribute mappings

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

1. Return to the Mappings section.
2. In the Provisioning settings, click Provision Microsoft Entra ID Groups to review group attribute mappings.

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

Configure users and groups to provision

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

1. In the Provisioning settings, expand the Settings section.
2. In the Scope dropdown, select one of the following options:
   • Sync only assigned users and groups: Entra ID provisions only users and groups assigned to the enterprise application. This is the recommended option.
   • Sync all users and groups: Entra ID provisions all users and groups in your Entra ID tenant.
3. Click Save to apply the scope setting.

Assign users and groups

Assigning groups to the application provisions all members of those groups. When you add or remove users from an assigned group in Entra ID, those changes automatically synchronize to Terraform Enterprise.

If you selected Sync only assigned users and groups, you must assign users and groups to the enterprise application:

1. In your enterprise application, select Users and groups from the left navigation.
2. Click Add user/group.
3. Select the users or groups you want to provision to Terraform Enterprise.
4. Click Assign.

Plan your group assignments

Consider the following when planning group assignments:

• Team mapping: After groups are provisioned to Terraform Enterprise, you can map them to Terraform Enterprise teams. Refer to Link SCIM groups to teams for instructions.
• Group size limits: Terraform Enterprise public SCIM group create and update requests support groups with up to 1,000 members. Larger groups are rejected by the public SCIM group provisioning endpoints. We recommend splitting larger groups into smaller functional teams.
• Site admin group: If you configure a site admin group in Terraform Enterprise, do not also link that group to a Terraform Enterprise team. Terraform Enterprise uses the site admin group exclusively for administrator provisioning.

Start provisioning

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

1. In Microsoft Entra ID, in the Provisioning settings, expand the Settings section.
2. Set Provisioning Status to On.
3. 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:

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

The provisioning logs show:

• Provision: Users and groups created in Terraform Enterprise.
• Update: Existing users or groups updated with new attribute values.
• Disable: Users deactivated in Terraform Enterprise.
• Delete: Groups removed from Terraform Enterprise.

Incremental cycles

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

Troubleshooting

This section describes common issues specific to Microsoft Entra ID SCIM integration and their solutions. For broader Terraform Enterprise-side diagnosis, refer to Troubleshoot SCIM provisioning.

Connection test fails

If the connection test fails when configuring provisioning:

• Verify that the tenant URL is correct and includes the /scim/v2 path.
• Verify that the SCIM token is valid and has not expired. Create a new token if necessary.
• Verify that Microsoft Entra ID can reach your Terraform Enterprise instance over HTTPS. Check firewall rules and network configurations.
• Verify that SCIM is enabled and not paused in Terraform Enterprise.

Users not provisioned

If users are not being provisioned to Terraform Enterprise:

• Verify the user is in scope for provisioning based on your scope configuration.
• If using assignment-based scoping, verify the user is assigned to the application directly or through a group.
• Check the provisioning logs for errors related to the specific user.
• Verify required attributes, such as externalId and userName, are correctly mapped.

Groups not synchronizing

If groups are not synchronizing to Terraform Enterprise:

• Verify group provisioning is enabled in the attribute mappings.
• Verify that the group is assigned to the enterprise application if using assignment-based scoping.
• Verify the group has fewer than 1,000 members. Larger groups are rejected by the public SCIM group provisioning endpoints.
• Verify the group attribute mappings for displayName, externalId, and members.

Rate limiting errors

HTTP 429 errors in the provisioning logs indicate that the IdP has reached the request rate limit.

Terraform Enterprise temporarily rate-limits SCIM requests when request volume is too high. These responses include a Retry-After header. Review the provisioning logs, wait for the sync to continue, and refer to Troubleshoot SCIM provisioning if the condition persists.

For additional troubleshooting information, refer to Troubleshoot SCIM provisioning.

Next steps

After configuring SCIM provisioning with Microsoft Entra ID:

• Verify group provisioning: Confirm group provisioning is enabled in the attribute mappings.
• Verify group assignment: Ensure the group is assigned to the enterprise application if using assignment-based scoping.
• Review group size: Verify the group has 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 Terraform Enterprise.
• Review SCIM group management to understand how SCIM groups integrate with Terraform Enterprise teams.