RBAC Overview

RBAC Overview

Role-Based Access Control (RBAC) in Mantis provides granular security for all system resources.

Overview

Key Concepts

Users

Users are individual accounts that can authenticate to Mantis. Each user:

• Has unique email and username
• Can be assigned one or more roles
• May be scoped to a specific tenant
• Can authenticate via local credentials or external identity providers

Roles

Roles are named groups of permissions. Mantis includes system roles:

Role	Description
admin	Full system access with all permissions
operator	Deployment and target management
viewer	Read-only access to resources
tenant_admin	Full access within assigned tenant

Custom roles can be created to match your organizational needs.

Permissions

Permissions grant specific actions on resources. Format: resource:action

Component	Examples
Resource	deployments, targets, actions, users
Action	create, read, update, delete

Example permissions:

• deployments:create - Start new deployments
• targets:read - View target information
• users:delete - Remove user accounts

Permission Model

Permission Inheritance

Users receive permissions through their roles:

User → Roles → Permissions

If a user has multiple roles, they receive the union of all permissions:

Authorization Flow

Permission Checking

Every protected endpoint validates permissions:

// In handler
check_permission(&mut conn, audit, &auth.claims, "deployments:create").await?;

The check:

1. Extracts user_id from JWT claims
2. Queries database for user’s permissions via roles
3. Returns success or logs denial to audit

System Roles

Admin

Full system access:

• All permissions across all resources
• Cannot be modified or deleted
• Typically assigned to platform administrators

Operator

Deployment operations:

• Create, read, update actions/sequences/solutions
• Create and manage deployments
• Register and manage targets

Viewer

Read-only access:

• View deployments and their status
• View targets and environments
• View actions, sequences, solutions
• Cannot make any modifications

Tenant Admin

Full access within tenant scope:

• The seed grants tenant_admin every permission except five system-tier ones:
  • tenants:create - Cannot create new tenants
  • tenants:delete - Cannot delete tenants
  • system:admin - No system administration
  • settings:manage - Cannot modify system settings
  • audit:read - Cannot read audit logs
• Delegation is secure by default: when a tenant_admin (or any non-system-admin) assigns roles/permissions, it may confer only permissions it itself holds or ones carried by the baseline viewer/operator roles. Everything else — including any future system-tier permission — is refused. See Permissions → Tenant Admin Role for details.
• Ideal for delegated tenant management

Multi-Tenant Context

When a user has a tenant_id:

1. All queries are automatically filtered by tenant
2. User can only access resources within their tenant
3. Cross-tenant access returns 404 (not 403) to prevent enumeration

Note

Users without a tenant_id (global users) can access resources across tenants if they have the required permissions.

Best Practices

Principle of Least Privilege

Assign the minimum permissions required:

Role Hierarchy Strategy

Create roles matching your organization:

Level	Example Roles	Typical Permissions
Platform	admin, auditor	Full access, read all
Operations	operator, deployer	Deployment management
Read-only	viewer, support	View resources
Custom	env-prod-admin	Specific environment access

Audit Compliance

All authorization decisions are logged:

{
  "event_type": "authz.permission_denied",
  "event_category": "authorization",
  "severity": "security",
  "actor_type": "user",
  "actor_id": "019b937d-4862-8e07-ac3a-1b8589d1b807",
  "actor_name": "alice",
  "action": "check_permission",
  "outcome": "denied",
  "outcome_reason": "Insufficient permission",
  "occurred_at": "2026-01-15T14:23:01"
}

Configuration

API Endpoints

Endpoint	Description
GET /api/v1/admin/users	List users
GET /api/v1/admin/roles	List roles
GET /api/v1/admin/permissions	List permissions
POST /api/v1/admin/roles/{id}/permissions	Assign permissions
POST /api/v1/admin/users/{id}/roles	Assign roles

Required Permission to Manage RBAC

Action	Permission
View users	users:read
Create users	users:create
Modify users	users:update
Delete users	users:delete
List/view roles	roles:manage
Create roles	roles:create
Modify roles	roles:update
Assign/remove permissions	roles:manage

Troubleshooting

User Cannot Access Resource

1. Check user’s assigned roles:

   curl -s -H "Authorization: Bearer $TOKEN" \
       https://api.mantis.local/api/v1/admin/users/$USER_ID/roles

2. Check role’s permissions:

   curl -s -H "Authorization: Bearer $TOKEN" \
       https://api.mantis.local/api/v1/admin/roles/$ROLE_ID/permissions

3. Verify required permission for endpoint

Permission Denied Despite Having Role

1. Verify user-role assignment is active
2. Check if permission is assigned to the role
3. Review audit logs for specific denial reason

Next Steps

• Users - User management
• Roles - Role configuration
• Permissions - Permission reference
• Tenant Isolation - Multi-tenant access control