Unique AI Documentation

Zitadel roles on groups

2 min read

Unique AI offers the ability to define Zitadel roles on group level. This means each user that gets assigned to this group (including sub groups) will also gain its defined Zitadel roles.

Of course its also the other way around. If a user gets removed from one group which has a Zitadel role assigned and this user is not part of any other group with this role it will be revoked from the user.

Scenario

  • Group Chat has role chat.chat.basic as Zitadel role assigned.

  • Group Admin has role chat.admin.all as Zitadel role assigned and is a sub group of Group Chat.

  • Group Knowledge has role chat.knowledge.read as Zitadel role assigned and is a sub group of Group Chat.

  • Group Feedback has role chat.feedback.read as Zitadel role assigned.

  • User Reto gets assigned to Group CHAt. This grants his user automatically the role chat.chat.basic

  • User Peter gets assigned to Group Admin. This grants his user automatically the roles chat.chat.basic and chat.admin.all.

  • Peter now gets removed from Group Admin and added to the Group Feedback. Means the User Peter gets revoked the roles chat.chat.basic and chat.admin.all but gets new role chat.feedback.read.

note

Note: User authorisations (roles) can still be added or removed directly in Zitadel manually. This can cause data inconsistency and will not be detect from Unique AI.

Means Unique does not consider such manual role assignments in Zitadel. This primary has an impact if a user looses in Unique AI access to a role because the user was removed from a Group.

Example: User Harry has been granted the role chat.feedback.read in Zitadel. Now Harry gets removed from a Group which has this chat.feedback.read role assigned and does in Unique not have access to this role anymore. Results that this chat.feedback.read role will be revoked from Harry.

info

Roles are stored on the user token. Means newly assigned roles will not affect users directly. The user needs either to logout and login manually or the currently used JWT needs to expire and a new login will be performed.

info

Verify if the service user for the user-sync between Zitadel and Unique is setup correctly including permissions accordingly to this setup documentation.

Configuration

These role assignments can be configured currently only via API. Please use the following curl template to change the role attribute on a group. Adjust the URL, token, groupId, and roles before sending. The user from which this token is needs to have the chat.admin.all role.

bash
curl --location 'https://<baseUrl>/scope-management/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <yourToken>' \
--data '{"query":"mutation UpdateGroup($updateGroupId: String!, $input: GroupUpdateInput!) {\n  updateGroup(id: $updateGroupId, input: $input) {\n  id\n  }\n}","variables":{"updateGroupId":"<groupId>","input":{"roles":<roles>}}}'

Explanation:

  • <baseUrl>: The host URL of your Unique API gateway (e.g. gateway.unique.app)

  • <yourToken>: The user token of a user with chat.admin.all permission (e.g. eyJhXXXXXX…)

  • <groupId>: ID of the group you want to modify - always starts with group_ (e.g. group_xxxxxx…)

  • <roles>: A JSON array of strings containing the role key (e.g. ["chat.chat.basic","chat.feedback.read"]

Last updated