The purpose of User Provisioning at Unique is to enable clients to manage their users and groups centrally, such as through Azure Entra ID, and to provision and keep these entities in sync with Unique. This ensures compliance with the need-to-know principle and regulatory requirements, limiting data access to relevant users only and upholding AI Governance. It also allows users to determine and assign data ownership according to their preferences.

1 Background
2 Group claims on ID token
- 2.1 Prerequisites
- 2.2 ID token sync concept
3 SCIM (System for Cross-domain Identity Management)
- 3.1 Prerequisites
- 3.2 SCIM sync concept

Background

In Unique, clients have the ability to manage users and groups, which is essential for controlling access to knowledge and specific spaces in the chat. Traditionally, creating groups and managing memberships has been a manual and time-consuming process. To address the scalability and error-prone nature of manual synchronization, there is a need for an automated solution to provision users and sync group setups with clients' organizational structures.

There are two approaches for syncing user groups in Unique:

Group claims on ID Token: This approach involves embedding user group information directly within the ID token issued by the Identity Provider (IdP). This method ensures that when a user authenticates, their group memberships are immediately available within Unique.
SCIM (System for Cross-domain Identity Management): SCIM is an open standard for automating the exchange of user identity information between identity domains or IT systems. By supporting SCIM, Unique can synchronize user and group information from clients' user management systems.

These different approaches will be described in more detail in the following sections.

Group claims on ID token

When clients connect their Identity Provider (IdP) with Unique, users can log in via Single Sign-On (SSO). In this process, the IdP of the client issues an ID token to Unique, that contains information about the user. This mechanism can be used to pass along specific information on the user from the clients' user-management system to Unique by including additional claims on the ID token.

Prerequisites

The Identity Provider (IdP) must be configured to include claims for user group information in the ID token. Unique expects that a groups field is present on the ID token that contains the user’s groups in an array. Each entry in the array must be an object and include id and displayName properties.

The groups field on the ID token must follow this format:

// id token object
{
...
"groups": [
  {
    "id": "<group-1-id>",
    "displayName": "<group-1-display-name>"
  },
  {
    "id": "<group-2-id>",
    "displayName": "<group-2-display-name>"
  },
  ...
]
}

All groups of users that should get synced into Unique must be present on the ID token. Every provided group will be synced and the user will become a member of this group in Unique.

ID token sync concept

The following steps are performed to sync a user’s groups passed in the ID token claims to Unique:

The user logs in via SSO
The client’s IdP (Zitadel) is configured to include relevant user groups as groups claims to the ID token
Unique’s IdP gets the ID token, reads the groups and stores the information as metadata on the user
A scheduled “user-sync” job runs every 5 minutes and fetches all user information including the metadata and performs the group sync operation (see diagram below)

The current implementation requires the scheduled user-sync job to run and therefore a delay of a maximum of 5 minutes can occur until a user’s groups are synced when they login for the first time or their groups changed.

User group sync - Including group claims on ID token

SCIM (System for Cross-domain Identity Management)

The SCIM implementation at Unique is currently a work in progress and will be available later in 2024 (Q4)

System for Cross-domain Identity Management (SCIM) is an open standard designed to make it easier to manage user identities in cloud-based applications and services. The SCIM protocol uses a standardized API to exchange user identity information between systems. When a user's information is created, updated, or deleted in an IDP, the IDP can send a corresponding SCIM request (in JSON format) to a cloud application’s SCIM endpoint, which then programmatically applies these changes to the user's profile or access rights. This ensures real-time synchronization of user data across different systems using RESTful APIs and a standardized schema.

More information can be found on the official SCIM homepage.

Prerequisites

The identity provider/user management system must be able to support the SCIM protocol.

Unique will provide:

URL for SCIM API endpoint of Unique
API key for calling SCIM API endpoint of Unique

The URL and API key need to be configured on the IdP in order to sync users and groups from the user management system to Unique.

SCIM sync concept

This concept is still a work in progress and changes might be made to it.

The following steps are performed to sync users into the Unique solution using SCIM:

Users get provisioned via SCIM (fixed interval or on demand)
1. IdP calls the SCIM endpoint of Unique and passes along the user information
2. Unique gets the request and syncs the users to its IdP (Zitadel)
3. Group information gets stored as metadata on the user in Zitadel
The user logs in and makes a request
1. Group metadata is passed in the JWT accessToken and set on the headers
2. In the backend, a middleware reads the metadata on the headers and ensures the groups in the backend are kept in sync
A scheduled “user-sync” job runs every 5 minutes and fetches all user information including the metadata and performs the group sync operation (see diagram below)

User group sync - SCIM user sync

Author	@Sandro Camastral

Author	@Sandro Camastral