Configure SCIM 2.0 provisioning with Microsoft Entra ID
The Contrast SCIM 2.0 API supports user and group provisioning from Microsoft Entra ID (formerly Azure AD). This topic covers connecting Entra ID to Contrast, configuring attribute mappings, and understanding current limitations.
This topic is for organization administrators configuring identity provisioning on a Contrast SaaS organization, on either the Classic or Northstar platform. It doesn't cover Okta SCIM setup, which is documented in Configure SCIM 2.0 provisioning with Okta or general SSO/SAML configuration.
SCIM provisioning must be enabled for your organization before you begin. Contact your Contrast Customer Success representative or Support if you haven't set this up yet.
Supported operations
Resource | Supported operations |
|---|---|
Users | Create, search, get, update, deactivate/reactivate, full replace, delete |
Groups | Create, search, get, rename, add/remove members, full replace, delete |
Schema discovery | Read-only, used by Entra to validate the connection |
Before you begin
SCIM provisioning is available for Contrast SaaS organizations only (Classic and Northstar platforms). It is not available for on-premises TeamServer deployments.
You need the organization administrator role in Contrast
Your organization must have RBAC enforced. SCIM-provisioned users are created with an RBAC-controlled role, so organizations without RBAC enabled cannot provision users through SCIM.
Users created through SCIM do not receive an invitation email. They authenticate through the SSO connection configured with your identity provider, so make sure SSO is already set up before you provision users.
Register an OAuth2 client
The Contrast SCIM API is accessible only through OAuth2 bearer tokens. Register a client for your organization using the Contrast API.
curl
--request POST \
--url https://<your-contrast-host>/api/v4/organizations/{organizationUuid}/oauth2/configuration \
--header 'Api-Key: <api_key>' \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '{
"clientId": "my-scim-client",
"clientSecret": "mySecretValue123!",
"clientName": "Entra SCIM Provisioning"
}'A successful request returns 201 Created. Save the clientId and clientSecret values. You will need them when you configure Entra ID.
For Entra ID, do not set the optional tokenTtlMinutes field. Entra refreshes its own tokens automatically, so the default 60-minute token lifetime is correct.
Note
You can register up to three OAuth2 clients per organization. Registering a fourth returns 409 Conflict. You'll also get 409 Conflict if the clientId you chose is already registered, either to your organization or to another one. Choose a unique client ID and retry.
Create a non-gallery enterprise application in Entra ID
Use a non-gallery Enterprise Application for SCIM provisioning. This gives you the OAuth2 client credentials flow with automatic token refresh, which gallery apps do not support.
In the Microsoft Entra admin center, go to Identity > Applications > Enterprise applications.
Select New application, then Create your own application.
Enter a name, such as "Contrast Security SCIM Provisioning."
Select Integrate any other application not found in the gallery (Non-gallery).
Select Create.
Note
If your organization already uses a Contrast gallery app for SSO, create a separate Enterprise Application for SCIM provisioning. Use one app for SSO and a different app for provisioning.
Configure provisioning
In the Enterprise Application, go to Provisioning, then select Get started.
Set Provisioning Mode to Automatic.
Under Admin Credentials, enter your Contrast SCIM endpoint as the Tenant URL with the
https://<your-contrast-host>/scim/v2value.For Authentication Method, select OAuth2 Client Credentials Grant, then enter the following
Field | Value |
|---|---|
Token Endpoint URL |
|
Client Identifier | The |
Client Secret | The |
Scope |
|
Select Test Connection. Entra sends a request to both the Users and Groups endpoints to confirm connectivity. Then select Save.
Note
Do not use the "Bearer Token" authentication method. It requires pasting a static token that Entra can't refresh automatically, and Contrast access tokens expire after 60 minutes by default. Use OAuth2 Client Credentials Grant instead, which handles token refresh for you.
Configure attribute mappings
Go to Provisioning > Mappings > Provision Microsoft Entra ID Users and confirm the following mappings.
SCIM attribute | Entra source attribute | Notes |
|---|---|---|
|
| Primary mapping. This is the value Contrast uses to match users, and it becomes the user's login email for new accounts. |
|
| Default Entra expression for account status |
|
| |
|
| |
|
| |
|
|
The userName mapping matters most. Contrast uses it to search for existing users. If a user's userPrincipalName in Entra does not match their login email in Contrast, the search returns no results and Entra creates a new account instead of matching the existing one.
Note
If your organization's UPN format does not match Contrast login emails, map userName to the mail attribute instead of userPrincipalName.
Assign users and groups
In the Enterprise Application, go to Users and groups.
Select Add user/group and assign the users or groups you want to provision to Contrast.
Groups assigned here sync to Contrast as User Access Groups.
Start provisioning
Go to Provisioning > Overview and select Start provisioning.
Entra runs an initial sync of all assigned users and groups.
After the initial sync, subsequent changes (deactivations, group membership updates) sync automatically, typically within 40 minutes. You can also trigger an on-demand sync from the Entra portal for immediate changes.
Known limitations
Login email (userName) is immutable. If a user's UPN changes in Entra, Contrast acknowledges the change but does not apply it. Name fields (
givenName,familyName) update normally.SCIM-provisioned groups have no default role assignments. Users added to a group created through SCIM will not have permissions in Contrast until an admin assigns roles to the group manually in the Contrast UI. This applies to Entra and Okta.
Group membership changes take effect within about 60 seconds after Contrast processes the request, due to caching.
Deprovisioning happens in two stages. When a user is unassigned from the Entra app or deleted in Entra, Entra deactivates the account in Contrast right away, then permanently deletes it once Entra's own 30-day retention window elapses. The account is inaccessible (deactivated) well before it is removed.
Entra ID compared to Okta
Entra ID uses OAuth2 client credentials, which refreshes tokens automatically. Okta's current integration uses a long-lived bearer token that you generate and paste into Okta's configuration, since Okta's SCIM app doesn't support the client-credentials flow. See [Configure SCIM 2.0 provisioning with Okta] for details.
Troubleshoot
Symptom | Cause | Resolution |
|---|---|---|
Entra "Test Connection" fails | Missing endpoint access or incorrect authentication | Confirm the Tenant URL has no trailing slash and no organization ID, and that your OAuth2 credentials are registered correctly. |
Entra user search returns empty, but the user exists in Contrast |
| Check your attribute mapping. Map |
| Your organization already has 3 registered OAuth2 clients, or the client ID you chose is already registered (to this org or another) | Delete an unused client, or choose a different client ID, then retry. |
User provisioning fails | RBAC is not enforced for your organization | Enable RBAC for your organization, then retry. |