Entra ID SCIM (formerly Azure AD)

This guide outlines how to synchronize your application’s Entra ID directories using SCIM.

To synchronize an organization’s users and groups provisioned for your application, you’ll need to provide the organization with two pieces of information:

Both of these are available in your Endpoint’s Settings in the WorkOS Dashboard.

Sign in to your WorkOS Dashboard and select “Organizations” from the left hand navigation bar.

Select the organization you’ll be configuring a new Directory Sync for.

Click “Add Directory”.

Select “Entra ID” from the dropdown, and enter the organization name.

Then, click “Create Directory.”

Your Entra ID directory sync has now been created successfully with an Endpoint and Bearer Token.

Sign in to the Entra ID Admin Center Dashboard. Select “Enterprise applications” from the list of Azure services.

If your application is already created, select it from the list of applications and move to Step 3.

If you haven’t created a SCIM application in Azure, select “New Application”.

Select “Create your own application” and continue.

Give your application a descriptive name, and select the “Integrate any other application you don’t find in the gallery (Non-gallery)” option, then click “Create”.

Select “Provisioning” from the “Manage” section found in the navigation menu.

Click the “Get Started” button.

Select the “Automatic” Provisioning Mode from the dropdown menu.

In the “Admin Credentials” section, copy and paste the Endpoint from your WorkOS Dashboard in the “Tenant URL” field.

Then, copy and paste the Bearer Token from your WorkOS Dashboard into the Secret Token field.

Click “Test Connection” to receive confirmation that your connection has been set up correctly. Then, select “Save” to persist the credentials.

Expand the “Mappings” section.

Make sure the group and user attribute mappings are enabled, and are mapping the correct fields. The default mapping should work, but your specific Azure setup may require you to add a custom mapping.

Make sure that you are mapping “objectId” to “externalId” within the Attribute Mapping section.

In order for your users and groups to be synced, you will need to assign them to your Entra ID SCIM Application. Select “Users and groups” from the “Manage” section of the navigation menu.

Select “Add user/group” from the top menu.

Select “None selected” under the “Users and Groups”. In the menu, select the users and groups that you want to add to the SCIM application, and click “Select”.

Select “Assign” to add the selected users and groups to your SCIM application.

In the Provisioning menu, confirm the “Provisioning Status” is set to “On” and that the “Scope” is set to “Sync only assigned users and groups”.

Begin provisioning users and groups and witness realtime changes in your WorkOS Dashboard.

A detailed guide to integrate the WorkOS API with your application can be found here

No emails are coming through for users from Azure. How do I get emails for my Azure users?

For cloud-managed users, Entra ID pulls the email from the mail attribute in Exchange. If your customer doesn’t have this set up, they will need to configure attribute mapping in their SCIM app in Azure in order to provision users with WorkOS. They can use this tutorial from Microsoft. They’ll want to map a known email attribute, such as UPN, to the emails[type eq “work”].value SCIM attribute. For directories with synchronized-users, they will need to map the userPrincipalName attribute into the emails[type eq “work”].value SCIM attribute.

Sometimes, reactivating "suspended" users does not re-add them to their Azure groups. Why is that and how can I fix it?

When a user is deleted from the entire directory, instead of only being deprovisioned from the SCIM app, the user may be soft-deleted (their state is set as "suspended"). Reactivating these suspended users will not send SCIM requests to re-add the user to the groups. To do so, the IT admin will need to select the "Restart Provisioning" button for the SCIM app in Azure.

Can profile images be accessed with Azure SCIM?

Entra ID's SCIM provisioning does not support transmitting image.

Why do I receive a dsync.user.updated event after dsync.user.created?

Entra ID sends a newly provisioned user over to WorkOS in two separate actions. WorkOS will then send these actions as two individual events to your app. This is expected behavior.

How often do Entra ID SCIM 2.0 directories perform a sync?

Entra ID SCIM 2.0 Directory Sync Interval:

By default, Entra ID SCIM 2.0 directories sync events on a scheduled time interval, typically every 40 minutes.

For more details, please refer to Entra ID's official documentation.

On-Demand Provisioning:

There's also an option for On-demand provisioning which syncs events in real-time.