Skip to main content

Role-Based Access Control (RBAC)

zymtrace uses Role-Based Access Control (RBAC) to manage user permissions. Roles are assigned to users, and each role contains a set of permission patterns that define what actions the user can perform.

Quick Start

Assign built-in roles to users via Profile picture → Account → Users → select user → Edit → add roles → Save

How RBAC Works​

  1. Roles are assigned to one or more users
  2. Roles contain permission patterns (not individual permissions)
  3. Permission patterns use wildcards to match multiple permissions
  4. Services validate requests by matching required permissions against patterns in the token

Permission Patterns​

Permission patterns use a hierarchical format with wildcard support:

resource:subresource:action

Wildcard Types:

  • * - matches a single level (e.g., project:* matches project:create, project:read)
  • ** - matches multiple levels (e.g., **:read matches project:read, admin:user:read, etc.)

Examples:

# Allow all project operations
project:*

# Allow reading anything
**:read

# Allow all admin operations
admin:**

# Allow all service token operations
service:token:*

# Allow everything (admin role)
**:**

Built-in Roles​

zymtrace includes three default roles:

  • System Admin (full system access with all permissions)
  • System Editor (can edit all system resources)
  • System Viewer (read-only access to all system resources)
  • Default Project Viewer (all users have read-only access to the default project)

Permission Model​

Understanding available permissions is essential for creating custom roles.

Service Token Permissions​

DescriptionPermission
Create service tokensservice:token:create
View service tokensservice:token:read
Revoke service tokensservice:token:revoke

Project Permissions​

DescriptionPermission
Create new projectsproject:create
View project detailsproject:read
Modify project settingsproject:update
Delete projectsproject:delete

Admin User Permissions​

DescriptionPermission
Create user accountsadmin:user:create
View user accountsadmin:user:read
Modify user accountsadmin:user:update
Delete user accountsadmin:user:delete

Admin Role Permissions​

DescriptionPermission
Create custom rolesadmin:role:create
View role definitionsadmin:role:read
Modify role permissionsadmin:role:update
Delete custom rolesadmin:role:delete
Assign roles to usersadmin:role:assignment:set

Audit Permissions​

DescriptionPermission
View audit log entriesadmin:audit:read

Authentication Permissions​

DescriptionPermission
Log in with local credentialsauth:local:login

Common RBAC Patterns​

Here are practical role configurations for common use cases:

Read-Only Viewer​

Perfect for stakeholders who need access but shouldn't make changes.

**:read

CI/CD Agent Role​

For automated deployments and monitoring systems.

service:token:read
project:read

Project Manager​

Can view and modify project settings, but cannot manage users or roles.

project:read
project:update

Analyst Role​

Can create and view resources but cannot delete.

project:create
project:read
admin:audit:read

User roles can be managed in the admin page.

Managing User Roles​

  1. Log in as an admin user
  2. Navigate to Profile picture → Account → Users

Users list

  1. Select a user and click three vertical dots
  2. Click Edit

Edit user dialogue

  1. Add or remove roles
  2. Save changes
Changes Don't Immediately Take Effect

Role changes apply when the user's next access token is issued. Access tokens are short-lived (typically 5 minutes), so changes take effect quickly.

Creating Custom Roles​

Custom roles allow fine-grained access control tailored to your organization's needs.

  1. Navigate to Profile picture → Account → Users
  2. Click Role & Permissions
  3. Click Add Role

Create new role dialogue

  1. Add permission patterns and role name
  2. Save the role

Roles with Constraints​

Roles can be restricted to specific projects, enabling fine-grained project-level access control.

Project-Scoped Roles​

When creating or editing a role, you can specify a list of projects the role grants access to:

  1. Navigate to Profile picture → Account → Users
  2. Click Role & Permissions
  3. Click Add Role or edit an existing role
  4. Add permission patterns
  5. Under Project Access, select which projects this role applies to
  6. Save the role

Example: Project Lead​

A project-scoped role that allows users to manage a specific project:

project:read
project:update

Apply this role with project constraint to "Project A" to allow leadership to modify only that project's settings.

Audit Logging​

All permission-related actions are logged to the audit log:

  • Role assignments and removals
  • Role creation, modification, and deletion
  • Permission checks that result in denial
  • Service token creation and revocation
  • Admin actions on user accounts