Zitadel Role Management on Unique

Since the Release 2025.22 Unique AI supports different modes for role management. This can be configured globally on a customer instance.

The environment variable SCOPE_MANAGEMENT_IDP_ROLE_MANAGEMENT on the scope-management application supports the following configuration, which is impacting the behaviour of the role management between Unique and Zitadel:

• GRANT_AND_REVOKE
  This mode will grant and revoke roles of users based on the users memberships to groups and their attached Zitadel roles. Every time a membership-role-validation is happening Unique will check what roles the user should have on Unique side, what roles the user has on Zitadel and accordingly revoke or grant roles.

• GRANT_ONLY (default)
  This is the default behaviour because of compatibility reasons. This mode will only grant new roles to users but not revoke additional roles the user has on Zitadel which might have been manually assigned. So if a user gets added to a new group with an additional role, Unique will grant this user the additional role.

• IGNORE
  This mode will completely ignore any role modifications on Unique via group or membership assignment.

Detailed description to: membership-role-validation

Whenever a user gets added to a group or a group changes its role assignment Unique will validate the roles of each affected user. Except the SCOPE_MANAGEMENT_IDP_ROLE_MANAGEMENT mode is set to IGNORE.

This action is done asynchronously. Therefore, it might take some time for the role assignment to take action. Anyway due to the fact that the Zitadel roles are on the user token a user needs to logout and login again.

The membership-role-validation will resolve all groups of a single user to detect the attached roles to this user. Then it will check what roles the user has currently assigned via Zitadel API. Afterwards it calculate the differences. If roles are missing the user will get granted those new additional roles via ZitadelAPI. If the mode is GRANT_AND_REVOKE and the user has on Zitadel additional roles assigned which are missing on Unique, the roles are getting revoked from the user.

This validation can also be triggered synchronously via API for a specific user. This allows to add a Post Authentication Action on Zitadel to call this endpoint and validate the roles before a token is getting issued. So if the mode is GRANT_AND_REVOKE, manually assigned roles via Zitadel are always getting revoked if not matching the Unique configuration for this user before the token with the roles is getting issued.

Contact the Customer Success representative to get more information about this.