atlas/docs/RBAC_PERMISSIONS.md

Role-Based Access Control (RBAC) - Current Implementation

Overview

AtlasOS implements a three-tier role-based access control system with the following roles:

1. Administrator (administrator) - Full system control
2. Operator (operator) - Storage and service operations
3. Viewer (viewer) - Read-only access

Current Implementation Status

✅ Fully Implemented (Administrator-Only)

These operations require Administrator role:

• User Management: Create, update, delete users, list users
• Service Management: Start, stop, restart, reload services, view service logs
• Maintenance Mode: Enable/disable maintenance mode

⚠️ Partially Implemented (Authentication Required, No Role Check)

These operations require authentication but don't check specific roles (any authenticated user can perform them):

• ZFS Operations: Create/delete pools, datasets, ZVOLs, import/export pools, scrub operations
• Snapshot Management: Create/delete snapshots, create/delete snapshot policies
• Storage Services: Create/update/delete SMB shares, NFS exports, iSCSI targets
• Backup & Restore: Create backups, restore backups

✅ Public (No Authentication Required)

These endpoints are publicly accessible:

• Read-Only Operations: List pools, datasets, ZVOLs, shares, exports, targets, snapshots
• Dashboard Data: System statistics and health information
• Web UI Pages: All HTML pages (authentication required for mutations via API)

Role Definitions

Administrator (administrator)

• Full system access
• Can manage users (create, update, delete)
• Can manage services (start, stop, restart, reload)
• Can enable/disable maintenance mode
• Can perform all storage operations
• Can view audit logs

Operator (operator)

• Storage and service operations (intended)
• Currently: Same as authenticated user (can perform storage operations)
• Should be able to: Create/manage pools, datasets, shares, snapshots
• Should NOT be able to: Manage users, manage services, maintenance mode

Viewer (viewer)

• Read-only access (intended)
• Currently: Can view all public data
• Should be able to: View all system information
• Should NOT be able to: Perform any mutations (create, update, delete)

Current Permission Matrix

Operation	Administrator	Operator	Viewer	Unauthenticated
User Management
List users	✅	❌	❌	❌
Create user	✅	❌	❌	❌
Update user	✅	❌	❌	❌
Delete user	✅	❌	❌	❌
Service Management
View service status	✅	❌	❌	❌
Start/stop/restart service	✅	❌	❌	❌
View service logs	✅	❌	❌	❌
Storage Operations
List pools/datasets/ZVOLs	✅	✅	✅	✅ (public)
Create pool/dataset/ZVOL	✅	✅*	❌	❌
Delete pool/dataset/ZVOL	✅	✅*	❌	❌
Import/export pool	✅	✅*	❌	❌
Share Management
List shares/exports/targets	✅	✅	✅	✅ (public)
Create share/export/target	✅	✅*	❌	❌
Update share/export/target	✅	✅*	❌	❌
Delete share/export/target	✅	✅*	❌	❌
Snapshot Management
List snapshots/policies	✅	✅	✅	✅ (public)
Create snapshot/policy	✅	✅*	❌	❌
Delete snapshot/policy	✅	✅*	❌	❌
Maintenance Mode
View status	✅	✅	✅	✅ (public)
Enable/disable	✅	❌	❌	❌

*Currently works but not explicitly restricted - any authenticated user can perform these operations

Implementation Details

Role Checking

Roles are checked using the requireRole() middleware:

// Example: Administrator-only endpoint
a.mux.HandleFunc("/api/v1/users", methodHandler(
    func(w http.ResponseWriter, r *http.Request) { a.handleListUsers(w, r) },
    func(w http.ResponseWriter, r *http.Request) {
        adminRole := models.RoleAdministrator
        a.requireRole(adminRole)(http.HandlerFunc(a.handleCreateUser)).ServeHTTP(w, r)
    },
    nil, nil, nil,
))

Multiple Roles Support

The requireRole() function accepts multiple roles:

// Allow both Administrator and Operator
a.requireRole(models.RoleAdministrator, models.RoleOperator)(handler)

Current Limitations

1. No Operator/Viewer Differentiation: Most storage operations don't check roles - they only require authentication
2. Hardcoded Role Checks: Role permissions are defined in route handlers, not in a centralized permission matrix
3. No Granular Permissions: Can't assign specific permissions (e.g., "can create pools but not delete them")

Future Improvements

To properly implement Operator and Viewer roles:

1. Add Role Checks to Storage Operations:

   • Allow Operator and Administrator for create/update/delete operations
   • Restrict Viewer to read-only (GET requests only)

2. Centralize Permission Matrix:

   • Create a permission configuration file or database table
   • Map operations to required roles

3. Granular Permissions (Future):

   • Allow custom permission sets
   • Support resource-level permissions (e.g., "can manage pool X but not pool Y")

Testing Roles

To test different roles:

1. Create users with different roles via the Management page
2. Login as each user
3. Attempt operations and verify permissions

Note: Currently, most operations work for any authenticated user. Only user management, service management, and maintenance mode are properly restricted to Administrators.