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:

1. The user logs in via SSO

2. The client’s IdP (Zitadel) is configured to include relevant user groups as groups claims to the ID token

3. Unique’s IdP gets the ID token, reads the groups and stores the information as metadata on the user

4. 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.