Skip to main content
All CollectionsTechnical DocumentationIntegrations
Integrations: User Provisioning with SCIM
Integrations: User Provisioning with SCIM
A
Written by Annelies van Hoesel
Updated over 3 weeks ago

SCIM (System for Cross-domain Identity Management) is an open standard protocol used to automate the exchange of user identity information between identity providers, such as Okta or Microsoft Entra ID, and service providers, such as our platform. It helps with provisioning, deprovisioning, and managing user accounts across different systems. SCIM is commonly used with Single Sign-On (SSO).

When connecting an identity provider to our platform using our SCIM api it will allow:

  • Provisioning: Automatically creates user accounts in our platform when a new employee joins.

  • Deprovisioning: Automatically suspend a user access when an employee leaves.

  • Updating: Syncs changes (e.g., name, email) from the identity provider to our platform.

  • Group Management: Helps assign users to roles and groups dynamically.
    ​

How it works

After a connection is set up between the external identity provider and our platform, the identity provider will be able to push any changes in the users or groups to our platform. When an employee is added, updated or removed in the external system, the user will be immediately created, updated or suspended on our platform. This is great for when you do not want to wish for an importer to run the next night, or for someone to manually update the user.

User management

Our SCIM implementation allows create/updating/suspending users with the following fields:

  • username

  • email

  • first name

  • last name

  • user language

  • scim external id (used to more easily identify the user on the external system)

When a user already exists on the platform, we allow the external identity provider to manage the existing user through our SCIM implementation.

Note that no invites are send, as SCIM is usually used in combination with SSO.

Group management

Our SCIM implementations allows the external system to create groups and manage their members. New groups will be created with group type "scim" and under a "scim" parent group. After creation you can manually change the group type, parent group, translatable name, and add automations to the group as you normally do.

When a new group is created through SCIM the platform will try to link it to an existing group, in case a group with the same group identifier already exists. This allows you to link scim to an existing group structure and all automations related to it. However it is not possible to link to a group that is managed by an importer, as the importer would remove all users not in the importer.

When group memberships are updated through SCIM, only members that have once been managed by SCIM are added or removed. Unlike with importer groups, it is possible for other platform members to be in a group managed through SCIM.

Note that it is not possible to delete a group through SCIM to avoid groups containing non SCIM users to be removed. Groups will have to be removed manually when no longer needed.

How to set up SCIM

SCIM endpoints

Our SCIM api is accessible through the following endpoints:

Authentication

We allow external identity providers to authenticate using OAuth. When you want to use SCIM for your user provisioning please contact our service desk, and ask them to set up OAuth client credentials access for your platform with scope "scim".

Using the provided client id and client secret the external identity provider will be able to fetch an access token from

In case the application requires the code flow (not recommended), you also need the authorization endpoint

It is also possible to authenticate using a bearer token. In this, the token will have to manually be fetched from the token endpoint above. The token will be valid for a year.

Setting up a SCIM integration with our platform in Okta

Please note that we are not Okta experts. If you run into any issues setting up the connection in Okta contact your Okta support or check the Okta documentation for more information.

First, create a saml application in Okta

Go to Applications > Applications > Create App Integration

In the popup select "SAML 2.0" and click next

In the next screen give your app a recognizable name and click next

Add the saml urls for your platform https://{your platform name}.platform.co.nl/saml2 And set up the fields used for the name ID and application username. And continue.

In the next screen select "This is an internal app that we have created" and click "Finish".

Your saml application is now set up. See our saml documentation on how to set up saml on our platorm so users can log in through your application.

Second, add SCIM user provisiong to your saml application

When viewing your application (accessible through Applications > Application > your application name), go to the general tab and click "edit" in the "App Settings" box.

Select "Enable SCIM provisioning" and hit save.

Next, go the the new "Provisioning" tab and click "Edit" next to "SCIM Connection"

Add the SCIM connector base URL. Use email as the unique identifier. Select Push new users, Push profile updates, and push groups (if you want to manage group memberships). For the authentication Mode select "HTTP" header and copy paste the bearer token provided by our service desk. Before you hit save and continue it is possible to test the connection.

Last, start adding users and groups

You can assign users to the application under the "Assignments" tab. It is possible to select on or more specific users, or one or more groups with users. Using the assign menu. As soon as user is assigned to the application a user will be created on the platform.

When push groups are enabled you can add them under the "Push Groups" tab. Click "+Push Groups". Select the group you want to add and select "create group" before saving/assinging.

Setting up a SCIM integration with our platform in Microsoft Entra

Please note that we are not Microsoft experts. If you run into any issues setting up the connection contact your Microsfot support or check the documentation.

First, create a saml application in Entra

See our other intercom article on how to set up saml in azure.

Second, add SCIM user provisiong to your saml application

Find your application (Service Principal) in azure and go to provisioning.

This should open the "Getting started" window. Here click on "Connect your application"

Add the SCIM base url for your platform as the "Tenant URL" and the token provided by our service desk. Test the connection and click create.

Did this answer your question?