/
Connect MS Entra ID with SCIM

Connect MS Entra ID with SCIM

Owned by Michael Dreher
Last updated: Mar 24, 2025 by Sandro Camastral
5 min read

Introduction

Unique AI provides SCIM compliant endpoints to be able to connect an IDP via the SCIM protocol. This protocol defines a standard for managing groups and users across multiple applications. An IDP is therefore able to sync its users and groups with other applications which supports this standard protocol.
The SCIM integration has been tested thoroughly with Microsoft Entra ID. This documentation guides through the setup process for Microsoft Entra ID.

Setup

This setup guide leads you through the process of connecting the Microsoft Entra ID application with Unique AI

The service user which until now synced the changes from Zitadel (events) with Unique AI requires now more privileges (IAM Owner Viewer & IAM User Manager). This service user now needs to also be able to create, modify and delete users from any organisation on Zitadel via API (IAM User Manager). But also fetch information about Organisations to be able to assign roles and IDPs to new created users (IAM Owner Viewer).
The service user also needs to be a service user of the Cluster IAM organisation (The organisation which has the Unique project created). Otherwise the role assignments will not work.

Screenshot 2025-03-24 at 09.57.13.png

[Zitadel] Adjusting permission of service user

  1. Login to Zitadel with a user that has IAM Owner capabilities (instance manager).

  2. Switch to Cluster IAM organisation on top left.

Screenshot 2025-01-30 at 16.36.43.png

  1. Switch to the instance view on top right.

Screenshot 2025-01-30 at 16.33.16.png

  1. Open the instance users managing view.

Screenshot 2025-01-30 at 16.36.59.png

  1. There should be a service user (robot icon) which has currently at least

    IAM Owner Viewer capability called user-sync or scope-management-user.

Screenshot 2025-01-30 at 16.37.11.png

  1. Adjust the Permission of this user including IAM Owner Viewer and IAM User Manager

Screenshot 2025-01-30 at 16.37.18.png

 

[MS Portal] Creating the SCIM Enterprise Application

These screenshots will guide you through the process of creating an Enterprise Application for SCIM.

  1. Microsoft Entra ID resource

 

Screenshot 2024-12-27 at 16.37.27.png
Open Micosoft Entra ID resource

  1. Enterprise Applications

 

Screenshot 2024-12-27 at 16.37.56.png
Switch to “Enterprise applications”

  1. New Enterprise Application

 

Screenshot 2024-12-27 at 16.38.08.png
Click “New application”

  1. Own Application

 

Screenshot 2024-12-27 at 16.38.19.png
Click “Create your own application”

  1. Name and Type

 

Screenshot 2024-12-27 at 16.38.43.png
Name the application and choose “Non-gallery” and click “Create”

  1. Finished

 

image-20250107-121114.png
Now the Enterprise Application for SCIM has been created

 

[MS Portal] Adding Users/Groups to the Application

In this step you define which users or groups are getting synced with Unique AI.

  1. Adding users/groups

 

Screenshot 2024-12-27 at 16.55.20.png
Select “Users and groups” and “Add user/group” in your created Enterprise Application

  1. Selecting users/groups

 

image-20250107-121409.png
Select the Users or Groups and click “Assign”

 

  1. Assigned users/groups

 

Screenshot 2024-12-27 at 16.57.49.png
The users/groups are now assigned

 

[Unique API] Creating the SCIM key

To be able to connect Microsoft Entra ID to Unique AI an API-Key is required. A user with the “Chat.Admin.All” role is able to run the following curl. This will create a key, which is authorised to access the SCIM endpoints of Unique AI for the organisation the user belongs to.

curl --location 'http://gateway.<baseUrl>/scope-management/graphql' \ --header 'Content-Type: application/json' \ --header 'Authorization: <your-access-token>' \ --data '{"query":"mutation ScimKeyCreate {\n scimKeyCreate {\n id\n key\n }\n}","variables":{}}'

In the response you will find the key attribute. Store this in a save place you will not be able to get it again but you can create a new one and delete old ones. The key will be used for the next step “[MS Portal] Connecting the Provisioning“.

 

[MS Portal] Connecting the Provisioning

With generating an API-key to access the SCIM endpoints of Unique AI (created in the step before “[Unique API] Creating the SCIM key“) it is possible to connect now the Microsoft Entra ID with Unique AI.

  1. Switch to Provisioning

 

image-20250107-121241.png
Switch to “Provisioning” on the Enterprise Application

 

  1. Add Configuration

 

Screenshot 2024-12-27 at 17.07.27.png
Click “New configuration”

  1. Fill URL and Token

Screenshot 2025-02-25 at 12.01.52-20250225-110523.png
Insert the “Tenant URL” and key as “Secret token”

The <API-URL> is the base API URL on which the Unique AI backend services are available. Normally its something similar like: https://gateway.xxx.unique.app. But especially for customer managed tenant this can vary.

  1. Test and create

 

Screenshot 2024-12-27 at 17.16.49.png
After successful test connection click “Create“

  1. Adjust the attribute mapping

 

Screenshot 2025-01-06 at 10.00.00.png
Switch to the User Attribute Mapping “Provision Microsoft Entra ID Users“

  1. Modify externalId to ObjectId

 

Screenshot 2025-01-06 at 09.56.57.png
Modify the mapping according to screenshot. Especially externalId → objectId

  1. Start Provisioning

Hint: When you apply SCIM provisioning on a tenant that has already users on it we recommend to first start provisioning specific users (a new one and an existing one). This should show if the provisioning works. Also check on Zitadel differences between the newly added user and the existing ones. Adjust the User mapping then when there are differences in the user name for example.

Screenshot 2024-12-27 at 17.19.17.png
Now start with the provisioning of the users and groups

 

Author

@Adrian Gugger

Related content

© 2025 Unique AG. All rights reserved. Privacy Policy – Terms of Service