Introduction
In this guide, you learn how to set up the Azure SCIM client for your Workspace environment. We recommend to set up and enable automated user provisioning via SCIM outside business hours.
Before you begin, please read the introduction article for the prerequisites, limitations and requirements.
Instructions
Step 1. Enabling SCIM API in Workspace
In this step, we need to enable the SCIM API in Workspace. Enabling the API will generate a SCIM API access token (API key). This is needed for authentication between Workspace and Microsoft Entra ID (previously called Azure AD).
Go to the Workspace admin settings page.
Navigate to Users & groups.
Select User provisioning.
Choose Automated user provisioning (SCIM) as user provisioning method.
Ensure the checkbox Enable sync using SCIM is checked. We recommend keeping the sync enabled
Choose a Default status for synced users. Note that this impacts the monthly invoice, which is based on active users. For more information, refer to About billing and invoicing.
Inactive: users are marked as inactive by default, you will need to activate them manually after syncing
(Recommended) Active: users are marked as active by default and can use the workspace immediately
Click Done.
A dialogue 'API key generated' will be shown. Copy the API key. This key will only be shown once.
Note down the API key. We need this in the next step.
Step 2. Setup SCIM client in Azure
Go to Microsoft Entra ID.
Navigate to Enterprise applications.
Click New application.
Click Create your own application.
Fill in the app Name, e.g. "Workspace 365 SCIM sync".
Select Integrate any other application you don't find in the gallery (Non-gallery).
Click Create.
In the menu on the left, under Manage, click Provisioning.
Click Get started.
Select the ' Provisioning Mode' to Automatic.
Under 'Tenant URL' fill in the SCIM API URL. Use the following format:
For the acceptance environment:
Under 'Secret token' fill in the access token.
The access token is retrieved from the final step in step 1 "Enabling SCIM API in Workspace".
Click Test Connection. The Azure SCIM Client will try to connect using the provided URL and access token and will report the result with a notification.
Note: If the connection fails (403 error), check if SCIM is enabled from the Workspace admin settings and/or make sure the key is valid. Then, try again.
Click Save.
Go back to the Provisioning section.
Click Edit provisioning.
Under 'Mappings' click Provision Microsoft Entra ID Users.
Scroll down to the bottom of the page and check the Show advanced options checkbox.
Click the Review your schema here link at the bottom of the page.
Overwrite the schema with our custom schema, which is the schema.json file. You can do this by copying the content of our schema.json file and pasting this into the schema editor window.
Download: Schema.json
Password: qQNNbccGwkZj
Click Save. You should see "Schema updated successfully".
Refresh the page.
Go back to Provisioning page.
Under Manage provisioning, click Edit attribute mappings.
Select Mappings.
From the drop-down list, select Provision Azure Active Directory Users.
Verify that the 'Attribute Mappings' looks like the screenshots depicted below.
Under 'Mappings' click Provision Azure Active Directory Groups.
Verify that the 'Attribute Mappings' looks like the screenshot depicted below.
Step 3. Define the user scope
You can choose to sync all users and/or groups from Microsoft Entra ID to Workspace, or just selected (assigned) users and/or groups.
Go to the SCIM enterprise application.
Select Provisioning.
Click Edit provisioning.
Under 'Settings' select the scope.
(RECOMMENDED) 'Sync only assigned users and groups'. Only users and groups assigned to the SCIM scope (configured in the next step) will be synced to the workspace.
'Sync all users and groups'. All users and groups present in Microsoft Entra ID will be synced. Note that this may impact performance depending on the size of your Entra ID.
(OPTIONAL) If desired, you can check 'Send an email notification when a failure occurs' and/or 'Prevent accidental deletion'. Neither option is required for the SCIM sync to work.
Click Save.
Step 4. Managing the user scope from Microsoft Entra ID
If your SCIM is set to the recommended setting of 'Sync only assigned users and groups', you will need to define the scope of users and groups to sync.
Go to the SCIM enterprise application.
Select Users and groups.
Click + Add user/group.
Click None selected, this will open a menu on the right side of your screen.
Search and select the users and/or groups you want to add to the SCIM scope
We recommend setting up the SCIM scope using groups rather than individual users
Click Select.
Click Assign. The selected user (and/or groups) are now assigned to the SCIM enterprise application.
You can click Refresh from the 'Provisioning' section to see if you assigned the correct user (and/or groups).
Nested groups
Nested groups must be individually added to the SCIM scope. If only the overarching group is added to the scope, SCIM's automatic sync will sync any nested groups, but users in the nested groups will not be added to the corresponding groups in the workspace. Provision on demand will not work for any group not included in the scope.
To make sure members of nested groups are synced, follow these instructions:
Go to the SCIM enterprise application.
Select Users and groups.
Click + Add user/group.
Click None selected under 'Users and groups'.
Search for the nested groups and select them. These groups should appear individually under 'Selected items'.
Click Select.
Click Assign.
Step 5. Start automatic user provisioning
The SCIM application and its scope have been defined, which means that the sync can now be started.
Go back to the Provisioning page.
Click Start provisioning.
After the initial sync has finished, SCIM will automatically run every 40 minutes and process any changes it detects. This interval cannot be changed. You can check the audit logs in Azure to see whether or not user provisioning has succeeded.
Provision on demand
You can forcefully provision (sync) users for 5 users and the same time. For new users this will always work, for existing users an attribute we sync must be changed (i.e. SCIM must detect a change that needs to be synced).
Go to the SCIM enterprise application.
Select Provisioning.
Click Provision on demand.
You have two options:
Search for a group and select 5 members within this group.
Search for and select 5 users.
Click Provision.
Azure will indicate if and why provisioning was successful or not.
Step 6. Disable the synctool (OPTIONAL)
If you were previously using our Azure AD synctool to sync users from Azure to the workspace, you can remove this once you have verified that the SCIM sync is working correctly. After changing the user provisioning method to SCIM during Step 1, the workspace is no longer "listening" to the synctool.