Role-Based Access Control

Fine-grained permissions with RBAC

Rackd implements role-based access control (RBAC) for fine-grained permission management.

Overview

RBAC in Rackd follows the standard model:

• Users - Accounts that can authenticate
• Roles - Collections of permissions
• Permissions - Fine-grained resource:action access controls

Users are assigned roles, and roles grant permissions. A user’s effective permissions are the union of all permissions from their assigned roles.

Default Roles

Rackd includes three built-in system roles that cannot be modified or deleted:

Admin

Full administrative access with all permissions. Can manage all resources including users, roles, and system configuration.

Operator

Operational access for day-to-day management:

Cannot delete resources or manage users/roles.

Viewer

Read-only access to view resources:

Permissions Reference

Devices

Networks

Datacenters

Pools

NAT

Circuits

Discovery

Credentials

Scan Profiles

Scheduled Scans

Relationships

Conflicts

Reservations

DNS Providers

DNS Zones

DNS Records

Users

Roles

API Keys

Webhooks

Custom Fields

Audit Logs

Search

Dashboard

Managing Roles

CLI Commands

# List roles
rackd role list

# List available permissions
rackd role permissions

# Filter permissions by resource
rackd role permissions --resource devices

# Create a custom role
rackd role create --name "Network Admin" --description "Full network management"

# Assign role to user
rackd role assign --user-id user-123 --role-id role-456

# Revoke role from user
rackd role revoke --user-id user-123 --role-id role-456

# Delete a custom role
rackd role delete --id role-456

Web UI

1. Navigate to Settings → Roles
2. View existing roles and their permissions
3. Create custom roles with specific permission sets
4. Assign roles to users from the user management page

API Endpoints

Roles

Permissions

User Role Assignment

Permission Checking

In Code

Permissions are checked at the service layer using the requirePermission function:

func (s *DeviceService) Create(ctx context.Context, device *model.Device) error {
    if err := requirePermission(ctx, s.checker, "devices", "create"); err != nil {
        return err
    }
    // ... create device
}

For API Keys

API keys inherit permissions from their owning user. When an API key makes a request:

1. The system resolves the user associated with the API key
2. Checks the user’s roles and permissions
3. Allows or denies the action based on permissions

For OAuth Tokens (MCP)

OAuth tokens can be scoped to specific permissions. The token’s scope restricts what actions can be performed, even if the user has broader permissions.

Best Practices

1. Principle of Least Privilege - Assign only the minimum required permissions
2. Use Built-in Roles - Start with viewer/operator before creating custom roles
3. Regular Audits - Periodically review role assignments
4. Document Custom Roles - Maintain clear descriptions of custom role purposes
5. Separate Duties - Use different roles for different operational areas

Related Documentation

• User Authentication - Authentication methods
• API Reference - REST API endpoints
• CLI Reference - Role management commands