Sign in

Configuring Azure AD SCIM v2.0

Learn about syncing your app with Azure AD SCIM v2.0


This guide outlines how to synchronize your application's Azure AD directories using SCIM v2.0.

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

  • An Endpoint that Azure AD will make requests to.
  • A Bearer token for Azure AD to authenticate its endpoint requests.

Both of these are available in your Endpoint's Settings in the Developer Dashboard.

Steps 2, 3, and 4 below will need to be carried out by the Enterprise when configuring your application in their Azure AD instance.

Set up your directory sync endpointLink

Login to your WorkOS Dashboard and select "Organizations" from the left hand navigation bar.

Click "Add Directory".

Input your Enterprise's Name and Domain and select "Azure AD SCIM v2.0" from the dropdown.

Then, click "Create Connection."

We have support for whitelabeled URLs for Directory Sync endpoints. Contact us for more info!

You will now see your Azure AD SCIM v.2.0 directory sync has created successfully with an Endpoint, Bearer Token, and the Company Domain.

Log in to the Azure AD instanceLink

Log in to the Azure Active Directory Admin Center Dashboard. Select "Find an enterprise application" located in the right hand section labelled "Quick tasks," and select your application from the list of Enterprise applications.

Configure your integrationLink

Select "Provisioning" from the "Manage" section found in the navigation menu.

In the "Admin Credentials" section, copy and paste the Endpoint from your Developer Dashboard in the "Tenant URL" field.

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

Click "Test Connection" to receive confirmation that your connection has been set up correctly.

Set and enable Attribute mappingsLink

Expand the "Mappings" section.

Enable the following custom Group Attribute mappings. (See image above for reference.)

  • displayName -> displayName
  • objectId -> externalId
  • members -> members

Assign users and groups to your applicationLink

Confirm the "Provisioning Status" is set to "On" and that the "Scope" is set to "Sync all users and groups."

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

Frequently asked questionsLink

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

Azure AD usually pulls the email from the mail attribute in Exchange. If your customer doesn't have this set up, they may need to configure configure attribute mapping in their SCIM app in Azure. 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.