Access Management for Admins

5 min read

This feature is EXPERIMENTAL and under active development. It may change significantly, be discontinued, or have breaking changes without notice. Documentation may be incomplete or outdated and is not recommended for production use. Use at your own risk. Please refer to our Upgrade and Release Process for more information.

Overview

Unique is introducing a new, fine-grained access control system that replaces the previous role-based model managed entirely in Zitadel. The new system has two parts:

Gatekeeper - a dedicated backend authorization service that evaluates access policies in real time.
Access Management UI - a new admin interface for managing users, roles, and groups directly within Unique.

The new model keeps full backward compatibility with all existing Zitadel roles while adding the ability to create custom roles, organize users into groups, and define granular policies per resource.

Backend: The Gatekeeper Service

What is Gatekeeper?

Gatekeeper is a dedicated authorization service built on Casbin, an open-source policy engine. Every time a user performs an action in Unique (e.g. opening a chat, uploading a document, managing a space), the platform asks Gatekeeper: Is this user allowed to do this? Gatekeeper evaluates the request against the configured roles, groups, and policies and returns an allow or deny decision.

Deployment Modes

Gatekeeper supports three operating modes, controlled by the environment variable GATEKEEPER_RUNNING_MODE:

Mode	Value	Behavior
Disabled	`disabled`	Gatekeeper is not consulted. All actions are allowed (legacy behavior).
Report Only	`report_only`	Gatekeeper evaluates every request and logs the result, but never blocks access. Useful for monitoring what would be denied before switching to enforcement.
Enforce	`enforce`	Gatekeeper actively allows or denies every request based on configured policies.

Gradual rollout: Enforcement can also be enabled per company using the GATEKEEPER_ENFORCE_COMPANIES environment variable (comma-separated list of company IDs). This allows individual tenants to be moved to enforce mode while the global setting remains report_only.

System Roles

Gatekeeper ships with a set of system roles that mirror the existing Zitadel role model. These roles are read-only and cannot be modified or deleted. They ensure that all current permissions continue to work seamlessly after enabling Gatekeeper.

System roles support inheritance - for example, Company Administrator inherits from User Management Admin, KB Admin, Space Admin, Chat Admin, Benchmarking Admin, Feedback Admin, Analytics Admin, Apps Admin, and Module Template Admin, so it automatically receives all their permissions.

For the full list of system roles, their legacy Zitadel mappings, and detailed permissions, see the System Roles subpage.

Custom Roles

Administrators can create custom roles that inherit permissions from one or more existing roles (system or other custom roles). This allows tailoring access to specific organizational needs without modifying the built-in roles.

Example: You might create a custom "Senior Analyst" role that inherits from both Analytics Admin and Benchmarking Viewer, giving users with that role access to analytics dashboards and read-only benchmarking data in a single assignment.

Granular Policies

Policies in Gatekeeper are defined at a granular level per resource. Each policy specifies:

Who - a role, group, user, or company
What resource - e.g. chat, message, knowledge base content, space, assistant, feedback, benchmark, connector, and more
What action - e.g. read, write, delete, manage, create, list
Ownership scope - optionally restrict to the user's own data

Example for non-technical readers:

Imagine you have a "Chat User" role. The policy for this role says:
Resource: Chats | Actions: Read, Write, Delete | Scope: Own chats only
Resource: Messages | Actions: Read, Write, Delete, Manage | Scope: Own messages only
This means a Chat User can create and manage their own conversations, but cannot see or modify another user's chats.
Now compare this with "Chat Admin", which has the same permissions but with scope set to all chats (not just their own), plus additional permissions for resources like analytics and settings.

Policy Assignment Levels

Policies can be applied at four different levels:

Level	Description	Example
Company	Applies to all users within a company/tenant	Default system role permissions are scoped per company
Role	Applies to all users assigned to a specific role	The "KB Manager" role grants write access to knowledge base content
Group	Applies to all members of a group	A "Data Team" group inherits the "Analytics Admin" role, giving all members access
User	Applies to a specific individual user	A specific admin user is granted root-level access

Frontend: Access Management UI

Feature Flags

The new Access Management UI is behind the feature flag:

FEATURE_FLAG_NEW_ACCESS_CONTROL_UI_UN_11268

When this flag is enabled, the "User Management" navigation item is renamed to "Access Management" and links to the new three-page UI described below. When disabled, the legacy single-page User Management view is shown.

Who Can Access It

Users with the Zitadel role admin.user-management.write (mapped to the User Management Admin system role in Gatekeeper) have access to the Access Management UI.

Pages

The UI consists of three pages, accessible via tabs:

1. Users

A table view of all users in the company.

Features:

Search by user name
Filter by role or group
Export as CSV - downloads a users-export-<date>.csv file containing all users matching the current search and filters (includes name, email, creation date, groups, and roles)
Manage Groups - per-user action to add or remove group memberships

2. Roles

A table view of all roles (system and custom).

Features:

Search by role name
Filter by type: All / System / Custom
Create Role - create a new custom role with a name, description, and one or more existing roles to inherit from
Manage Role (custom roles only) - edit name, description, and inherited roles
Manage Users (custom roles only) - assign or remove users from the role
Delete (custom roles only) - delete with confirmation showing the impact (number of affected users, policies, and inherited roles)
System roles are marked with a lock icon and cannot be edited or deleted

3. Groups

A table view of all groups.

Features:

Search by group name
Filter by member count (few / medium / many) or by assigned role
Create Group - create a new group
Manage Group - rename the group
Manage Members - add or remove users from the group
Manage Roles - assign or remove roles for the group (all group members inherit these roles)
Delete - delete the group with a confirmation warning about the access impact on members
Groups that are managed externally (e.g. synced from an identity provider) are marked with a lock icon and cannot be modified from within Unique

Enable Access Management

FEATURE_FLAG_ENABLE_GATEKEEPER_PERMISSIONS_UN_15116

What it does

Switches the frontend's access control from the legacy JWT role model to fine-grained Gatekeeper permissions.

Off (default): UI access is decided by the user's roles embedded in the auth token (e.g. CHAT_BASIC, ADMIN_ALL, KNOWLEDGE_READ).
On: UI access is decided by the per-user uiPermissions set fetched from the user profile (e.g. CAN_ACCESS_CHAT, CAN_ACCESS_ADMIN, CAN_READ_KNOWLEDGE_BASE). Roles passed to access checks are mapped to their equivalent permissions, so existing route guards keep working without code changes.

Where it applies

It gates client-side authorization across the frontend apps: chat, admin, theme, and knowledge-upload.