🛡️ Role-Based Access Control (RBAC)
Permission system, role hierarchy, and authorization patterns
Executive Summary
AIUsagePlatform implements a hybrid RBAC model combining role-based and permission-based access control. System roles provide predefined permission sets, while custom roles allow granular permission assignment per organization.
✅ Role Hierarchy
Role Level enforces authority (10-100)
Role Level enforces authority (10-100)
✅ Permission Granularity
30+ fine-grained permissions
30+ fine-grained permissions
✅ Custom Roles
Organizations define custom roles
Organizations define custom roles
⚠️ No Resource-Level
Cannot scope to specific records
Cannot scope to specific records
👥 System Roles
| Role | Level | Type | Key Permissions | Scope |
|---|---|---|---|---|
| SuperAdmin | 100 | System | All (*) | Platform-wide |
| Admin | 50 | System | Users.*, Roles.Assign, Analytics.View, Reports.*, Org.Edit | Organization |
| Manager | 30 | System | Users.View, Team.View, Analytics.View, Reports.View, Exports.Create | Team (planned) |
| User | 10 | System | Profile.*, Analytics.Own, Sessions.Own | Self only |
| Viewer | 5 | System | Analytics.View (read-only) | Read-only access |
🔐 Role Level Enforcement
Role Level Hierarchy Enforcement
═══════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────┐
│ Role Level Authorization │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Principle: Higher role level = more authority │
│ • Level 100 (SuperAdmin) can manage all levels below │
│ • Level 50 (Admin) can manage levels 30, 10, 5 │
│ • Level 30 (Manager) can manage levels 10, 5 │
│ • Level 10 (User) can only manage self │
│ │
│ Implementation: │
│ ───────────────────────────────────────────────────────────────────────── │
│ │
│ [RequireMinimumRoleLevel(50)] // Admin or higher required │
│ public async Task DeleteUser(Guid id) │
│ { │
│ var currentUserLevel = GetCurrentUserRoleLevel(); // From JWT │
│ var targetUser = await _userService.GetByIdAsync(id); │
│ │
│ // Cannot delete users at same or higher level │
│ if (targetUser.RoleLevel >= currentUserLevel) │
│ return Forbid(); │
│ │
│ // Proceed with deletion │
│ await _userService.DeleteAsync(id); │
│ } │
│ │
│ Security Benefits: │
│ • Prevents privilege escalation │
│ • Enforces organizational hierarchy │
│ • Blocks Admin from deleting SuperAdmin │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
📋 Permission Inventory
| Category | Permissions | Description |
|---|---|---|
| Users | Users.View | List and view user details |
| Users.Create | Create new users | |
| Users.Edit | Modify user profiles | |
| Users.Delete | Delete/deactivate users | |
| Roles | Roles.View | View role definitions |
| Roles.Create | Create custom roles | |
| Roles.Assign | Assign roles to users | |
| Roles.Delete | Delete custom roles | |
| Analytics | Analytics.View | View organization analytics |
| Analytics.Own | View own analytics only | |
| Analytics.Export | Export analytics data | |
| Reports | Reports.View | View generated reports |
| Reports.Create | Create new reports | |
| Reports.Export | Export reports (PDF, CSV) | |
| Organization | Organization.View | View organization details |
| Organization.Edit | Modify organization settings | |
| Organization.Billing | Access billing information | |
| Exports | Exports.Create | Create data exports |
| Exports.Download | Download export files | |
| Audit | Audit.View | View audit logs |
| Audit.Global | View cross-tenant logs (SuperAdmin) |
🎯 Authorization Attributes
// Require specific permission
[HasPermission("Users.Create")]
public async Task CreateUser(CreateUserRequest request)
// Require any of the specified permissions
[HasAnyPermission("Users.Create", "Users.Edit")]
public async Task ManageUser(UserRequest request)
// Require all specified permissions
[HasAllPermissions("Reports.View", "Reports.Export")]
public async Task ExportReport(Guid reportId)
// Require minimum role level
[RequireMinimumRoleLevel(50)] // Admin or higher
public async Task DeleteOrganization(Guid id)
// Require specific role
[RequireRole("SuperAdmin")]
public async Task GetGlobalAnalytics()
// Combined: Role + Permission
[Authorize(Roles = "Admin,SuperAdmin")]
[HasPermission("Users.Delete")]
public async Task DeleteUser(Guid id)
🔐 Permission Resolution Flow
Permission Check Execution Flow
═══════════════════════════════════════════════════════════════════════════════
Request: DELETE /api/usersmanagement/123 (User has Admin role)
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 1: JWT Authentication │
│ ───────────────────────────────────────────────────────────────────────── │
│ • Token validated (signature, expiry) │
│ • Claims extracted: role="Admin", role_level=50, permissions=[...] │
│ • ClaimsPrincipal built with identity │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 2: Authorization Filter (HasPermissionAttribute) │
│ ───────────────────────────────────────────────────────────────────────── │
│ │
│ 1. Get required permission from attribute: "Users.Delete" │
│ │
│ 2. Extract current user info from HttpContext: │
│ • UserId: usr_abc123 │
│ • OrganizationId: org_xyz789 │
│ │
│ 3. Call IRoleManagementService.HasPermissionAsync(): │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ a) Get user's roles: │ │
│ │ SELECT r.* FROM Roles r │ │
│ │ JOIN UserRoles ur ON ur.RoleId = r.Id │ │
│ │ WHERE ur.UserId = 'usr_abc123' │ │
│ │ AND ur.OrganizationId = 'org_xyz789' │ │
│ │ │ │
│ │ Result: [{ Id: 'role_admin', Name: 'Admin', Level: 50 }] │ │
│ │ │ │
│ │ b) Get permissions for these roles: │ │
│ │ SELECT p.Name FROM Permissions p │ │
│ │ JOIN RolePermissions rp ON rp.PermissionId = p.Id │ │
│ │ WHERE rp.RoleId = 'role_admin' │ │
│ │ │ │
│ │ Result: ["Users.View", "Users.Create", "Users.Edit", │ │
│ │ "Users.Delete", "Roles.Assign", ...] │ │
│ │ │ │
│ │ c) Check if "Users.Delete" in permissions list: │ │
│ │ YES → Return TRUE │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ 4. Result: Permission GRANTED → Continue to controller │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 3: Controller Execution │
│ ───────────────────────────────────────────────────────────────────────── │
│ public async Task DeleteUser(Guid id) │
│ { │
│ // Additional resource-level check possible here │
│ await _userService.DeleteAsync(id); │
│ return NoContent(); │
│ } │
└─────────────────────────────────────────────────────────────────────────────┘
⚠️ RBAC Security Concerns
No Resource-Level ACL
Cannot restrict access to specific records (e.g., "can only view own team's data"). All-or-nothing per permission.
Role Level Bypass Risk
Custom roles could potentially be assigned high role levels. Needs server-side validation on creation.
Cached Permissions in JWT
Permissions embedded in JWT means no DB lookup for auth checks. Fast validation.
Attribute-Based Security
Declarative [HasPermission] attributes make authorization logic clear and maintainable.