Use Case 006: Role-Based Access Control Management

Overview

Property Value
Use Case ID UC-006
Use Case Name Role-Based Access Control Management
Module Identity Management - Authorization
Priority Medium
Status Implemented
Version 1.0
Last Updated January 30, 2026

Description

This use case describes the comprehensive role-based access control (RBAC) system that governs user permissions across the Riptide Application Manager platform. The system enables administrators to create custom roles, define granular capabilities (permissions), assign capabilities to roles, and manage role-user assignments in both directions: assign roles to users (user-centric view) or assign users to roles (role-centric view). The RBAC system enforces the principle of least privilege and supports both built-in system roles and custom organizational roles. Permission checks occur at every API endpoint and UI interaction to ensure users can only access resources and perform actions they are authorized for.

Actors

Actor Description Role
System Administrator Platform admin with full RBAC management privileges Primary
Organization Administrator Org-level admin who can manage roles within their organization Primary
Application User Any authenticated user subject to role-based permissions Secondary
System Application Manager platform enforcing permissions Supporting
Audit Service Service logging all permission changes and access attempts Supporting

Preconditions

  1. Application Manager identity service is running
  2. Administrator is authenticated with appropriate permissions
  3. At least one built-in role exists (Admin, TrialUser, etc.)
  4. Database schema for roles, capabilities, and assignments is initialized
  5. Permission checking middleware is enabled on all protected endpoints

Postconditions

Success Postconditions

  1. Role created/updated/deleted in database
  2. Capabilities defined and assigned to roles
  3. Users assigned to roles with effective permissions
  4. Permission changes immediately enforced across the system
  5. All changes logged in audit trail
  6. Cache invalidated for affected users
  7. Users notified of role/permission changes (if configured)

Failure Postconditions

  1. No changes committed if validation fails
  2. Error logged with reason for failure
  3. Existing permissions remain unchanged
  4. User access unaffected by failed operations

Triggers

  • Administrator navigates to role management interface
  • Administrator creates/modifies/deletes a role
  • Administrator assigns capabilities to a role
  • Administrator assigns a role to a user (user-centric)
  • Administrator assigns users to a role (role-centric)
  • User attempts action requiring permission check
  • System evaluates user capabilities for authorization

Basic Flow (Happy Path)

sequenceDiagram actor Admin as Administrator participant Web as Admin Web UI participant API as Application Manager API participant AuthZ as Authorization Service participant DB as Identity Database participant Cache as Permission Cache participant Audit as Audit Service Note over Admin,Audit: Role Creation Flow Admin->>Web: Navigate to Roles page Web->>API: GET /api/v1/roles API->>DB: Query all roles DB->>API: Return roles list API->>Web: 200 OK (roles data) Web->>Admin: Display roles list Admin->>Web: Click "Create Role" Web->>Admin: Show role creation form Admin->>Web: Enter role details + select capabilities Web->>API: POST /api/v1/roles API->>AuthZ: Verify admin has role:create capability AuthZ->>DB: Check admin's roles and capabilities DB->>AuthZ: Admin has permission AuthZ->>API: Authorized API->>API: Validate role data API->>DB: Check role name uniqueness DB->>API: Name available API->>DB: Create role record DB->>API: Role created (ID: role-123) API->>DB: Create role-capability assignments DB->>API: Capabilities assigned API->>Audit: Log role creation Audit->>Audit: Store audit record API->>Web: 201 Created (role details) Web->>Admin: Show success message Note over Admin,Audit: User Role Assignment Flow Admin->>Web: Navigate to user details Web->>API: GET /api/v1/users/{userId} API->>DB: Query user with roles DB->>API: User data with current roles API->>Web: 200 OK (user data) Web->>Admin: Display user with roles Admin->>Web: Assign role to user Web->>API: POST /api/v1/users/{userId}/roles API->>AuthZ: Verify admin has user:assign-role capability AuthZ->>DB: Check admin's capabilities DB->>AuthZ: Admin authorized API->>DB: Check if role exists DB->>API: Role exists API->>DB: Create user-role assignment DB->>API: Role assigned to user API->>Cache: Invalidate user's permission cache Cache->>Cache: Cache entry removed API->>Audit: Log role assignment Audit->>Audit: Store audit record API->>Web: 200 OK (updated user roles) Web->>Admin: Show success message Note over Admin,Audit: Permission Check Flow Admin->>API: POST /api/v1/applications (create app) API->>AuthZ: Check permission (application:create) AuthZ->>Cache: Check cached permissions Cache->>AuthZ: Cache miss or expired AuthZ->>DB: Query user's roles DB->>AuthZ: User has "Platform Admin" role AuthZ->>DB: Query role's capabilities DB->>AuthZ: Capabilities list includes "application:create" AuthZ->>Cache: Store computed permissions Cache->>AuthZ: Cached AuthZ->>API: Permission granted API->>API: Execute application creation API->>Admin: 201 Created (application)

Detailed Steps

  1. Administrator Accesses Role Management

    • Navigate to /admin/roles or equivalent
    • System displays list of all roles (built-in and custom)
    • Each role shows: name, description, capability count, user count

  2. Administrator Creates New Role

    • Click "Create Role" button
    • System displays role creation form
    • Enter role details:
      • Role Name (required, unique)
      • Display Name (required)
      • Description (optional)
      • Select capabilities from organized capability tree
      • Set role as default for new users (optional)
    • System validates input and checks permissions

  3. System Validates Role Data

    • Verify role name is unique within scope (global or org-level)
    • Check role name follows naming convention (alphanumeric, dashes, underscores)
    • Validate selected capabilities exist
    • Verify admin has permission to create roles
    • Check for circular dependencies if role hierarchy is enabled

  4. System Creates Role Record

    • Generate unique role ID (GUID)
    • Store role metadata (name, description, scope)
    • Set CreatedBy to current administrator ID
    • Set CreatedAt timestamp
    • Mark role as active (IsActive = true)

  5. System Assigns Capabilities to Role

    • For each selected capability:
      • Create RoleCapability association record
      • Link role ID to capability ID
      • Set GrantedAt timestamp
      • Set GrantedBy to administrator ID

  6. System Logs Role Creation

    • Create audit log entry with:
      • Action: "RoleCreated"
      • Actor: Administrator ID
      • Target: Role ID
      • Changes: Full role details and capabilities
      • Timestamp and correlation ID

  7. Administrator Assigns Role to User

    • Navigate to user details page
    • View current roles assigned to user
    • Click "Add Role" button
    • Select role from dropdown
    • Optionally set role assignment expiration date
    • Submit role assignment

  8. System Creates User-Role Assignment

    • Validate role exists and is active
    • Check user doesn't already have this role
    • Create UserRole association record
    • Link user ID to role ID
    • Set AssignedAt timestamp and AssignedBy administrator
    • Store optional expiration date

  9. System Invalidates Permission Cache

    • Remove cached permission data for affected user
    • Clear any permission evaluation results
    • Ensure next request will compute fresh permissions

  10. System Enforces Permissions on Request

    • User makes API request or UI interaction
    • Authorization middleware intercepts request
    • Extract required capability from endpoint metadata
    • Check user's effective capabilities (computed from all roles)
    • Grant or deny access based on capability check
    • Log authorization decision if denied

Alternative Flows

Alt Flow 1: Role Name Conflict

sequenceDiagram actor Admin as Administrator participant API as Application Manager API participant DB as Identity Database Admin->>API: POST /api/v1/roles (name: "Viewer") API->>DB: Check if role name exists DB->>API: Role "Viewer" already exists API->>Admin: 409 Conflict - Role name already exists Note over Admin,API: Suggest alternative names Admin->>API: POST /api/v1/roles (name: "Custom Viewer") API->>DB: Check if role name exists DB->>API: Name available API->>DB: Create role DB->>API: Role created API->>Admin: 201 Created

Steps:

  1. Administrator submits role with name that already exists
  2. System detects duplicate during validation (step 3)
  3. Return 409 Conflict with message: "Role name 'Viewer' already exists"
  4. Suggest alternative names: "Custom Viewer", "Org Viewer", "Viewer_2"
  5. Administrator modifies name and resubmits
  6. Process continues from step 3 with valid unique name

Alt Flow 2: Role Deletion with Active Users

sequenceDiagram actor Admin as Administrator participant Web as Admin Web UI participant API as Application Manager API participant DB as Identity Database Admin->>Web: Click "Delete Role" for "Analyst" role Web->>API: DELETE /api/v1/roles/{roleId} API->>DB: Check users assigned to role DB->>API: 15 users have this role alt Force Delete Not Allowed API->>Web: 409 Conflict - Role in use Web->>Admin: Show error: "Cannot delete role with 15 active users" Note over Admin,Web: Admin must reassign users first else Force Delete with Confirmation API->>Web: 200 OK - Requires confirmation Web->>Admin: Show warning dialog Admin->>Web: Confirm deletion Web->>API: DELETE /api/v1/roles/{roleId}?force=true API->>DB: Remove all user-role assignments API->>DB: Delete role API->>Web: 204 No Content Web->>Admin: Role deleted, users unassigned end

Steps:

  1. Administrator attempts to delete role
  2. System checks for users assigned to role (step 8)
  3. If users exist and force delete not enabled:
    • Return 409 Conflict with count of affected users
    • Display message: "Cannot delete role 'Analyst' - 15 users are assigned"
    • Provide option to view affected users
    • Require administrator to reassign users first
  4. If force delete enabled:
    • Display confirmation dialog with user count and impact
    • If confirmed:
      • Remove all user-role assignments
      • Invalidate permission cache for all affected users
      • Delete role record
      • Log bulk unassignment in audit trail
      • Notify affected users of permission change

Alt Flow 3: Capability Inheritance and Conflicts

flowchart TD A[User has multiple roles] --> B{Compute effective capabilities} B --> C[Role 1: Read-only access] B --> D[Role 2: Write access] B --> E[Role 3: Admin access] C --> F[user:read] D --> G[user:read + user:write] E --> H[user:* all capabilities] F --> I[Union of all capabilities] G --> I H --> I I --> J{Check for deny rules} J -->|No denies| K[Grant most permissive] J -->|Deny exists| L[Apply deny restriction] K --> M[User can perform action] L --> N[User denied action]

Steps:

  1. User has multiple roles assigned (common scenario)
  2. System must compute effective capabilities
  3. Default strategy: Union (additive permissions)
    • Collect capabilities from all assigned roles
    • Remove duplicates
    • User has permission if ANY role grants it
  4. Alternative strategy: Intersection (restrictive)
    • User only has capabilities present in ALL roles
    • Rarely used, very restrictive
  5. Explicit deny rules (if implemented):
    • Check for explicit deny capabilities
    • Deny rules override grant rules
    • User denied if ANY role has explicit deny
  6. Permission granted if capability in effective set and no deny rules

Alt Flow 4: Built-in Role Protection

sequenceDiagram actor Admin as Administrator participant API as Application Manager API participant DB as Identity Database Admin->>API: PUT /api/v1/roles/builtin-admin (modify Admin role) API->>DB: Query role details DB->>API: Role metadata (IsBuiltIn: true) API->>API: Check if role is protected API->>Admin: 403 Forbidden - Cannot modify built-in role Note over Admin,API: Built-in roles are immutable Admin->>API: POST /api/v1/roles (create custom admin role) API->>DB: Create new custom role DB->>API: Role created API->>Admin: 201 Created

Steps:

  1. Administrator attempts to modify built-in role (Admin, TrialUser, etc.)
  2. System detects IsBuiltIn = true flag on role
  3. Return 403 Forbidden: "Built-in roles cannot be modified or deleted"
  4. Display message: "Create a custom role instead with desired permissions"
  5. Protected operations on built-in roles:
    • Cannot delete
    • Cannot rename
    • Cannot modify core capabilities
    • Can view but not edit
  6. Administrator creates custom role with similar permissions instead

Alt Flow 5: Permission Check Denial

sequenceDiagram actor User as Application User participant API as Application Manager API participant AuthZ as Authorization Service participant DB as Identity Database participant Audit as Audit Service User->>API: DELETE /api/v1/applications/{id} API->>AuthZ: Check permission (application:delete) AuthZ->>DB: Query user's roles and capabilities DB->>AuthZ: User roles: ["Viewer", "Analyst"] AuthZ->>DB: Query capabilities for roles DB->>AuthZ: Capabilities: [user:read, app:read, data:read] AuthZ->>AuthZ: application:delete NOT in capability list AuthZ->>API: Permission denied API->>Audit: Log unauthorized access attempt Audit->>Audit: Store security event API->>User: 403 Forbidden - Insufficient permissions Note over User,API: User sees permission error

Steps:

  1. User attempts action requiring specific capability
  2. Authorization service computes user's effective capabilities
  3. Required capability not found in user's capability set
  4. Permission denied, request blocked
  5. Return 403 Forbidden with message: "You lack permission: application:delete"
  6. Log unauthorized access attempt with:
    • User ID
    • Requested action and resource
    • Required capability
    • User's current roles
    • Timestamp
  7. Optionally display helpful message suggesting who to contact for access

Alt Flow 6: Add Users to Role (Role-Centric Assignment)

sequenceDiagram actor Admin as Administrator participant Web as Admin Web UI participant API as Application Manager API participant DB as Identity Database participant Cache as Permission Cache participant Audit as Audit Service Admin->>Web: Navigate to role details page Web->>API: GET /api/v1/roles/{roleId}/users API->>DB: Query users assigned to role DB->>API: Return user list API->>Web: 200 OK (users with role) Web->>Admin: Display role with assigned users Admin->>Web: Click "Add Users to Role" Web->>API: GET /api/v1/users?filter=eligible API->>DB: Query users not yet having this role DB->>API: Return eligible users API->>Web: 200 OK (eligible users) Web->>Admin: Show user selection dialog Admin->>Web: Select multiple users + submit Web->>API: POST /api/v1/roles/{roleId}/users API->>API: Verify admin has role:assign capability loop For each selected user API->>DB: Check if user already has role alt User already has role API->>API: Skip (already assigned) else User doesn't have role API->>DB: Create user-role assignment DB->>API: Assignment created API->>Cache: Invalidate user's permission cache API->>Audit: Log role assignment end end API->>Web: 200 OK (summary: 5 assigned, 2 skipped) Web->>Admin: Show success message with details

Steps:

  1. Administrator navigates to specific role details page (e.g., "Data Analyst" role)
  2. System displays role information including:
    • Role name, description, capabilities
    • List of users currently assigned to this role
    • Count of assigned users
  3. Administrator clicks "Add Users to Role" button
  4. System displays user selection dialog:
    • Shows all users eligible for role assignment (users not already having this role)
    • Provides search/filter functionality
    • Allows multi-select with checkboxes
    • Shows user details: name, email, current roles count
  5. Administrator selects one or multiple users from the list
  6. Administrator optionally sets:
    • Assignment expiration date (applies to all selected users)
    • Whether to send notification email to each user
  7. Administrator submits the bulk assignment
  8. System processes each selected user:
    • Validates user exists and is active
    • Checks if user already has this role (skip if duplicate)
    • Creates UserRole assignment record
    • Invalidates permission cache for affected user
    • Logs assignment in audit trail
  9. System returns summary:
    • Number of users successfully assigned
    • Number of users skipped (already had role)
    • List of any errors encountered
  10. Administrator sees success message with assignment summary
  11. Role details page refreshes with updated user list

Benefits of Role-Centric Assignment:

  • Efficient for assigning same role to multiple users at once
  • Natural workflow when provisioning team members ("Add all analysts to Data Analyst role")
  • Easier to manage role membership from role perspective
  • Complements user-centric assignment (different use cases)

Business Rules

Rule ID Description Enforcement
BR-001 Role names must be unique within organization scope Database unique constraint + API validation
BR-002 Built-in roles cannot be modified or deleted Role metadata flag + API guard
BR-003 At least one user must have the Admin role at all times Pre-delete validation
BR-004 Users can be assigned multiple roles (union of capabilities) Data model supports many-to-many
BR-005 Capabilities follow namespace convention: resource:action Validation regex: ^[a-z-]+:[a-z-]+$
BR-006 Wildcard capabilities use asterisk: application:* for all app operations Permission evaluation logic
BR-007 Permission cache expires after 5 minutes Cache TTL configuration
BR-008 Role assignments can have optional expiration dates UserRole.ExpiresAt field
BR-009 Expired role assignments are automatically removed by background job Scheduled task (daily)
BR-010 Audit log retained for all role/capability changes (365 days) Audit service configuration

Data Requirements

Role Record

{
  "Id": "uuid-v4",
  "Name": "string (required, unique per org, 2-50 chars, alphanumeric+dashes)",
  "DisplayName": "string (required, 2-100 chars)",
  "Description": "string (optional, max 500 chars)",
  "OrganizationId": "uuid-v4 (nullable, null = global role)",
  "IsBuiltIn": "boolean (default: false)",
  "IsDefault": "boolean (default: false, auto-assign to new users)",
  "IsActive": "boolean (default: true)",
  "CreatedBy": "uuid-v4 (user ID)",
  "CreatedAt": "datetime (UTC)",
  "UpdatedAt": "datetime (UTC)",
  "Metadata": "json (optional, extensible metadata)"
}

Capability Record

{
  "Id": "uuid-v4",
  "Name": "string (required, unique, e.g., 'application:create')",
  "DisplayName": "string (required)",
  "Description": "string (optional)",
  "Category": "string (e.g., 'Application Management', 'User Management')",
  "IsSystemCapability": "boolean (default: false)",
  "RequiresElevation": "boolean (default: false, requires MFA)",
  "CreatedAt": "datetime (UTC)"
}

Role-Capability Assignment

{
  "Id": "uuid-v4",
  "RoleId": "uuid-v4 (foreign key)",
  "CapabilityId": "uuid-v4 (foreign key)",
  "GrantedAt": "datetime (UTC)",
  "GrantedBy": "uuid-v4 (admin user ID)"
}

User-Role Assignment

{
  "Id": "uuid-v4",
  "UserId": "uuid-v4 (foreign key)",
  "RoleId": "uuid-v4 (foreign key)",
  "AssignedAt": "datetime (UTC)",
  "AssignedBy": "uuid-v4 (admin user ID)",
  "ExpiresAt": "datetime (UTC, nullable)",
  "IsRevoked": "boolean (default: false)",
  "RevokedAt": "datetime (UTC, nullable)",
  "RevokedBy": "uuid-v4 (admin user ID, nullable)"
}

Permission Evaluation Cache Entry

{
  "UserId": "uuid-v4",
  "Capabilities": [
    "application:read",
    "application:create",
    "user:read",
    "role:assign"
  ],
  "ComputedAt": "datetime (UTC)",
  "ExpiresAt": "datetime (UTC)",
  "CacheKey": "permissions:user:{userId}"
}

Built-in Roles

Admin Role

{
  "Name": "admin",
  "DisplayName": "Platform Administrator",
  "Description": "Full access to all platform features and settings",
  "IsBuiltIn": true,
  "Capabilities": ["*:*"]
}

TrialUser Role

{
  "Name": "trial-user",
  "DisplayName": "Trial User",
  "Description": "Limited access for trial account holders",
  "IsBuiltIn": true,
  "Capabilities": [
    "application:read",
    "application:access",
    "session:create",
    "profile:read",
    "profile:update"
  ]
}

Viewer Role

{
  "Name": "viewer",
  "DisplayName": "Viewer",
  "Description": "Read-only access to applications and data",
  "IsBuiltIn": true,
  "Capabilities": [
    "application:read",
    "user:read",
    "role:read",
    "data:read"
  ]
}

Operator Role

{
  "Name": "operator",
  "DisplayName": "Operator",
  "Description": "Operational access to manage running applications",
  "IsBuiltIn": true,
  "Capabilities": [
    "application:read",
    "application:start",
    "application:stop",
    "application:restart",
    "log:read",
    "metric:read"
  ]
}

Capability Taxonomy

Application Management

  • application:create - Create new applications
  • application:read - View application details
  • application:update - Modify application configuration
  • application:delete - Delete applications
  • application:access - Access/use the application
  • application:publish - Publish application versions

User Management

  • user:create - Create new users
  • user:read - View user details
  • user:update - Modify user information
  • user:delete - Delete users
  • user:assign-role - Assign roles to users
  • user:revoke-role - Remove roles from users
  • user:impersonate - Impersonate another user (admin)

Role Management

  • role:create - Create custom roles
  • role:read - View role details
  • role:update - Modify role capabilities
  • role:delete - Delete custom roles
  • role:assign - Assign roles to users
  • role:assign-capability - Add capabilities to roles

Organization Management

  • organization:create - Create organizations
  • organization:read - View organization details
  • organization:update - Modify organization settings
  • organization:delete - Delete organizations

Configuration Management

  • config:read - View configuration
  • config:update - Modify configuration
  • config:export - Export configuration
  • config:import - Import configuration

Audit and Monitoring

  • audit:read - View audit logs
  • audit:export - Export audit logs
  • metric:read - View system metrics
  • log:read - View system logs

Wildcard Capabilities

  • *:* - All capabilities (super admin)
  • application:* - All application operations
  • user:* - All user operations
  • role:* - All role operations

User Interface

Role List View

┌───────────────────────────────────────────────────────────────────────┐
│  Roles & Permissions                        [+ Create Role]  [⚙️ ]    │
│  ═══════════════════════════════════════════════════════════════════  │
│                                                                        │
│  🔍 Search roles...                              Filter: [All ▾]      │
│                                                                        │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │ Name                Description              Users   Actions    │  │
│  ├────────────────────────────────────────────────────────────────┤  │
│  │ 🔒 Admin            Full platform access      5      [View]     │  │
│  │ 🔒 Trial User       Limited trial access      142    [View]     │  │
│  │ 🔒 Viewer           Read-only access          28     [View]     │  │
│  │ 🔒 Operator         Operational access        12     [View]     │  │
│  │ ────────────────────────────────────────────────────────────── │  │
│  │ Custom Roles                                                     │  │
│  │ ────────────────────────────────────────────────────────────── │  │
│  │ 📋 Data Analyst     Data access & reporting   18     [Edit] [⋮] │  │
│  │ 📋 App Developer    Application development   7      [Edit] [⋮] │  │
│  │ 📋 Support Agent    Customer support access   24     [Edit] [⋮] │  │
│  │ 📋 Finance Manager  Financial data access     4      [Edit] [⋮] │  │
│  └────────────────────────────────────────────────────────────────┘  │
│                                                                        │
│  🔒 = Built-in role (cannot be modified)                              │
│  📋 = Custom role                                                      │
└───────────────────────────────────────────────────────────────────────┘

Role Editor - Create/Edit Role

┌───────────────────────────────────────────────────────────────────────┐
│  Create New Role                                        [Cancel] [Save]│
│  ═══════════════════════════════════════════════════════════════════  │
│                                                                        │
│  Basic Information                                                     │
│  ─────────────────                                                     │
│                                                                        │
│  Role Name *                                                           │
│  ┌──────────────────────────────────────────────────────────────────┐ │
│  │ data-analyst                                                     │ │
│  └──────────────────────────────────────────────────────────────────┘ │
│  Lowercase, alphanumeric, dashes only                                 │
│                                                                        │
│  Display Name *                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐ │
│  │ Data Analyst                                                     │ │
│  └──────────────────────────────────────────────────────────────────┘ │
│                                                                        │
│  Description                                                           │
│  ┌──────────────────────────────────────────────────────────────────┐ │
│  │ Access to view and analyze application data with reporting       │ │
│  │ capabilities. Cannot modify data or system configuration.        │ │
│  └──────────────────────────────────────────────────────────────────┘ │
│                                                                        │
│  ☐ Set as default role for new users                                  │
│                                                                        │
│  ─────────────────────────────────────────────────────────────────── │
│                                                                        │
│  Capabilities                                       [Expand All]       │
│  ────────────                                                          │
│                                                                        │
│  Select the permissions this role should have:                        │
│                                                                        │
│  ▼ Application Management                          4 of 6 selected    │
│     ☑ application:read          View applications                     │
│     ☑ application:access        Use applications                      │
│     ☐ application:create        Create applications                   │
│     ☐ application:update        Modify applications                   │
│     ☐ application:delete        Delete applications                   │
│     ☑ application:publish       Publish app versions                  │
│                                                                        │
│  ▼ User Management                                 2 of 6 selected    │
│     ☑ user:read                 View users                            │
│     ☐ user:create               Create users                          │
│     ☐ user:update               Modify users                          │
│     ☐ user:delete               Delete users                          │
│     ☐ user:assign-role          Assign roles                          │
│     ☐ user:revoke-role          Remove roles                          │
│                                                                        │
│  ▶ Role Management                                 0 of 6 selected    │
│                                                                        │
│  ▼ Data Access                                     5 of 5 selected    │
│     ☑ data:read                 Read data                             │
│     ☑ data:export               Export data                           │
│     ☑ data:query                Run queries                           │
│     ☑ data:report               Generate reports                      │
│     ☑ data:analyze              Perform analysis                      │
│                                                                        │
│  ▶ Configuration Management                        0 of 4 selected    │
│  ▶ Audit & Monitoring                             0 of 4 selected    │
│                                                                        │
│  ─────────────────────────────────────────────────────────────────── │
│                                                                        │
│  Summary: 11 capabilities selected across 3 categories                │
│                                                                        │
│                                         [Cancel]  [Save Role]         │
└───────────────────────────────────────────────────────────────────────┘

User Role Assignment View

┌───────────────────────────────────────────────────────────────────────┐
│  User: Sarah Johnson (sarah.johnson@example.com)                      │
│  ═══════════════════════════════════════════════════════════════════  │
│                                                                        │
│  👤 Profile    🔐 Roles & Permissions    📊 Activity    ⚙️ Settings   │
│  ─────────────────────────────────────────────────────────────────── │
│                                                                        │
│  Assigned Roles                                      [+ Assign Role]  │
│  ──────────────                                                        │
│                                                                        │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │ Role               Assigned        Expires      Actions         │  │
│  ├────────────────────────────────────────────────────────────────┤  │
│  │ 📋 Data Analyst    2026-01-15     Never        [Remove]         │  │
│  │    • 11 capabilities                           [View Details]   │  │
│  │                                                                  │  │
│  │ 📋 Viewer          2026-01-20     Never        [Remove]         │  │
│  │    • 8 capabilities                            [View Details]   │  │
│  └────────────────────────────────────────────────────────────────┘  │
│                                                                        │
│  Effective Capabilities (Combined from all roles)                     │
│  ──────────────────────────────────────────────────────────────────  │
│                                                                        │
│  Total: 15 unique capabilities                                        │
│                                                                        │
│  ▼ Application Management (4)                                         │
│     ✓ application:read                                                │
│     ✓ application:access                                              │
│     ✓ application:publish                                             │
│                                                                        │
│  ▼ User Management (2)                                                │
│     ✓ user:read                                                       │
│                                                                        │
│  ▼ Data Access (5)                                                    │
│     ✓ data:read, data:export, data:query, data:report, data:analyze  │
│                                                                        │
│  ▼ Audit & Monitoring (2)                                             │
│     ✓ audit:read, metric:read                                         │
│                                                                        │
│  [View Full Capability List]                                          │
│                                                                        │
│  ─────────────────────────────────────────────────────────────────── │
│                                                                        │
│  Role Assignment History                                              │
│  ──────────────────────────                                           │
│                                                                        │
│  • Data Analyst assigned by Admin on 2026-01-15 at 10:30 AM          │
│  • Viewer assigned by Admin on 2026-01-20 at 2:15 PM                 │
│  • Operator role removed by Admin on 2026-01-18 at 4:45 PM           │
│                                                                        │
└───────────────────────────────────────────────────────────────────────┘

Assign Role to User Dialog

┌─────────────────────────────────────────────────────┐
│  Assign Role to User                                │
│  ══════════════════════════════════════════════════ │
│                                                     │
│  User: Sarah Johnson                                │
│  Email: sarah.johnson@example.com                   │
│                                                     │
│  Select Role *                                      │
│  ┌───────────────────────────────────────────────┐ │
│  │ Data Analyst                               ▾  │ │
│  └───────────────────────────────────────────────┘ │
│                                                     │
│  Role Details:                                      │
│  • 11 capabilities                                  │
│  • Categories: Application, User, Data Access      │
│                                                     │
│  [View Full Capabilities]                           │
│                                                     │
│  Assignment Duration                                │
│  ○ Permanent                                        │
│  ○ Temporary (expires on specific date)             │
│                                                     │
│  Notification                                       │
│  ☑ Send email notification to user                 │
│                                                     │
│  ──────────────────────────────────────────────── │
│                                                     │
│                           [Cancel]  [Assign Role]  │
└─────────────────────────────────────────────────────┘

Add Users to Role Dialog

┌──────────────────────────────────────────────────────────────────┐
│  Add Users to Role: Data Analyst                                 │
│  ════════════════════════════════════════════════════════════════│
│                                                                   │
│  Select Users *                                                   │
│                                                                   │
│  Search: [________________________] 🔍                           │
│                                                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ ☐ Select All (8 users eligible)                         │   │
│  │ ─────────────────────────────────────────────────────────│   │
│  │ ☑ John Doe                                               │   │
│  │   john.doe@example.com                                   │   │
│  │   Current roles: Viewer (1)                              │   │
│  │                                                           │   │
│  │ ☑ Jane Smith                                             │   │
│  │   jane.smith@example.com                                 │   │
│  │   Current roles: Operator, Viewer (2)                    │   │
│  │                                                           │   │
│  │ ☐ Bob Johnson                                            │   │
│  │   bob.johnson@example.com                                │   │
│  │   Current roles: Data Analyst, Viewer (2)                │   │
│  │   ⚠️ Already has this role                               │   │
│  │                                                           │   │
│  │ ☐ Alice Williams                                         │   │
│  │   alice.williams@example.com                             │   │
│  │   Current roles: None (0)                                │   │
│  │                                                           │   │
│  │ ☐ Michael Chen                                           │   │
│  │   michael.chen@example.com                               │   │
│  │   Current roles: Operator (1)                            │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                   │
│  Selected: 2 users                                                │
│                                                                   │
│  Assignment Duration                                              │
│  ○ Permanent                                                      │
│  ○ Temporary (expires on specific date)                           │
│    [____________________] 📅                                     │
│                                                                   │
│  Notification                                                     │
│  ☑ Send email notification to assigned users                     │
│                                                                   │
│  ──────────────────────────────────────────────────────────────  │
│                                                                   │
│                              [Cancel]  [Add Users to Role]       │
└──────────────────────────────────────────────────────────────────┘

API Endpoints

Role Management

List All Roles

Endpoint: GET /api/v1/roles

Authentication: Required (role:read capability)

Query Parameters:

  • organizationId (optional): Filter by organization
  • includeBuiltIn (default: true): Include built-in roles
  • isActive (default: true): Filter by active status
  • page (default: 1): Page number
  • pageSize (default: 50): Items per page

Success Response: 200 OK

{
  "roles": [
    {
      "id": "role-123",
      "name": "data-analyst",
      "displayName": "Data Analyst",
      "description": "Access to view and analyze data",
      "isBuiltIn": false,
      "isDefault": false,
      "isActive": true,
      "capabilityCount": 11,
      "userCount": 18,
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-20T14:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalItems": 12,
    "totalPages": 1
  }
}

Create Role

Endpoint: POST /api/v1/roles

Authentication: Required (role:create capability)

Request Body:

{
  "name": "data-analyst",
  "displayName": "Data Analyst",
  "description": "Access to view and analyze application data",
  "organizationId": "org-456",
  "isDefault": false,
  "capabilityIds": [
    "cap-app-read",
    "cap-app-access",
    "cap-data-read",
    "cap-data-export",
    "cap-data-query"
  ]
}

Success Response: 201 Created

{
  "id": "role-123",
  "name": "data-analyst",
  "displayName": "Data Analyst",
  "description": "Access to view and analyze application data",
  "organizationId": "org-456",
  "isBuiltIn": false,
  "isDefault": false,
  "isActive": true,
  "capabilities": [
    {
      "id": "cap-app-read",
      "name": "application:read",
      "displayName": "View Applications"
    },
    {
      "id": "cap-data-read",
      "name": "data:read",
      "displayName": "Read Data"
    }
  ],
  "createdBy": "admin-user-id",
  "createdAt": "2026-01-30T10:30:00Z"
}

Error Responses:

400 Bad Request - Validation error

{
  "error": "ValidationError",
  "message": "Role validation failed",
  "errors": {
    "name": ["Role name must be unique"],
    "capabilityIds": ["Capability 'cap-xyz' does not exist"]
  }
}

409 Conflict - Duplicate role name

{
  "error": "DuplicateRoleName",
  "message": "A role with name 'data-analyst' already exists"
}

Get Role Details

Endpoint: GET /api/v1/roles/{roleId}

Authentication: Required (role:read capability)

Success Response: 200 OK

{
  "id": "role-123",
  "name": "data-analyst",
  "displayName": "Data Analyst",
  "description": "Access to view and analyze application data",
  "organizationId": "org-456",
  "isBuiltIn": false,
  "isDefault": false,
  "isActive": true,
  "capabilities": [
    {
      "id": "cap-app-read",
      "name": "application:read",
      "displayName": "View Applications",
      "category": "Application Management",
      "grantedAt": "2026-01-30T10:30:00Z",
      "grantedBy": "admin-user-id"
    }
  ],
  "userCount": 18,
  "users": [
    {
      "userId": "user-789",
      "fullName": "Sarah Johnson",
      "email": "sarah.johnson@example.com",
      "assignedAt": "2026-01-15T10:30:00Z",
      "assignedBy": "admin-user-id",
      "expiresAt": null
    }
  ],
  "createdBy": "admin-user-id",
  "createdAt": "2026-01-30T10:30:00Z",
  "updatedAt": "2026-01-30T10:30:00Z"
}

Update Role

Endpoint: PUT /api/v1/roles/{roleId}

Authentication: Required (role:update capability)

Request Body:

{
  "displayName": "Senior Data Analyst",
  "description": "Enhanced data analysis and reporting access",
  "isDefault": false,
  "capabilityIds": [
    "cap-app-read",
    "cap-data-read",
    "cap-data-export",
    "cap-data-report"
  ]
}

Success Response: 200 OK

{
  "id": "role-123",
  "name": "data-analyst",
  "displayName": "Senior Data Analyst",
  "description": "Enhanced data analysis and reporting access",
  "capabilities": [...],
  "updatedAt": "2026-01-30T11:45:00Z"
}

Error Response: 403 Forbidden - Built-in role protection

{
  "error": "BuiltInRoleProtection",
  "message": "Built-in roles cannot be modified. Create a custom role instead."
}

Delete Role

Endpoint: DELETE /api/v1/roles/{roleId}

Authentication: Required (role:delete capability)

Query Parameters:

  • force (default: false): Force delete even if users assigned

Success Response: 204 No Content

Error Response: 409 Conflict - Role in use

{
  "error": "RoleInUse",
  "message": "Cannot delete role 'data-analyst' - 18 users are assigned",
  "affectedUsers": 18,
  "suggestion": "Remove role from all users first, or use force=true"
}

Capability Management

List All Capabilities

Endpoint: GET /api/v1/capabilities

Authentication: Required (role:read capability)

Query Parameters:

  • category (optional): Filter by category
  • search (optional): Search by name or description

Success Response: 200 OK

{
  "capabilities": [
    {
      "id": "cap-app-read",
      "name": "application:read",
      "displayName": "View Applications",
      "description": "Permission to view application details",
      "category": "Application Management",
      "isSystemCapability": false,
      "requiresElevation": false
    },
    {
      "id": "cap-user-delete",
      "name": "user:delete",
      "displayName": "Delete Users",
      "description": "Permission to permanently delete users",
      "category": "User Management",
      "isSystemCapability": true,
      "requiresElevation": true
    }
  ],
  "categories": [
    {
      "name": "Application Management",
      "capabilityCount": 6
    },
    {
      "name": "User Management",
      "capabilityCount": 6
    },
    {
      "name": "Role Management",
      "capabilityCount": 6
    }
  ]
}

User Role Assignment

Assign Role to User

Endpoint: POST /api/v1/users/{userId}/roles

Authentication: Required (user:assign-role capability)

Request Body:

{
  "roleId": "role-123",
  "expiresAt": "2026-12-31T23:59:59Z",
  "sendNotification": true
}

Success Response: 200 OK

{
  "userId": "user-789",
  "roleAssignment": {
    "id": "assignment-456",
    "roleId": "role-123",
    "roleName": "data-analyst",
    "roleDisplayName": "Data Analyst",
    "assignedAt": "2026-01-30T10:30:00Z",
    "assignedBy": "admin-user-id",
    "expiresAt": "2026-12-31T23:59:59Z",
    "isRevoked": false
  },
  "effectiveCapabilities": [
    "application:read",
    "data:read",
    "data:export"
  ]
}

Remove Role from User

Endpoint: DELETE /api/v1/users/{userId}/roles/{roleId}

Authentication: Required (user:revoke-role capability)

Success Response: 204 No Content

Get User's Roles and Capabilities

Endpoint: GET /api/v1/users/{userId}/roles

Authentication: Required (user:read capability)

Success Response: 200 OK

{
  "userId": "user-789",
  "fullName": "Sarah Johnson",
  "email": "sarah.johnson@example.com",
  "roles": [
    {
      "roleId": "role-123",
      "roleName": "data-analyst",
      "roleDisplayName": "Data Analyst",
      "assignedAt": "2026-01-15T10:30:00Z",
      "assignedBy": "admin-user-id",
      "expiresAt": null,
      "capabilityCount": 11
    }
  ],
  "effectiveCapabilities": [
    {
      "name": "application:read",
      "displayName": "View Applications",
      "sourceRoles": ["data-analyst", "viewer"]
    },
    {
      "name": "data:read",
      "displayName": "Read Data",
      "sourceRoles": ["data-analyst"]
    }
  ],
  "uniqueCapabilityCount": 15
}

Role-Centric User Management

Add Users to Role (Bulk Assignment)

Endpoint: POST /api/v1/roles/{roleId}/users

Authentication: Required (role:assign capability)

Description: Assign multiple users to a role at once (role-centric view). Useful for bulk provisioning team members with the same role.

Request Body:

{
  "userIds": [
    "user-123",
    "user-456",
    "user-789"
  ],
  "expiresAt": "2026-12-31T23:59:59Z",
  "sendNotification": true
}

Success Response: 200 OK

{
  "roleId": "role-abc",
  "roleName": "data-analyst",
  "roleDisplayName": "Data Analyst",
  "summary": {
    "totalRequested": 3,
    "successfullyAssigned": 2,
    "skipped": 1,
    "failed": 0
  },
  "results": [
    {
      "userId": "user-123",
      "fullName": "John Doe",
      "email": "john.doe@example.com",
      "status": "assigned",
      "assignmentId": "assignment-111",
      "assignedAt": "2026-01-30T14:22:00Z"
    },
    {
      "userId": "user-456",
      "fullName": "Jane Smith",
      "email": "jane.smith@example.com",
      "status": "assigned",
      "assignmentId": "assignment-222",
      "assignedAt": "2026-01-30T14:22:00Z"
    },
    {
      "userId": "user-789",
      "fullName": "Bob Johnson",
      "email": "bob.johnson@example.com",
      "status": "skipped",
      "reason": "User already has this role",
      "existingAssignmentId": "assignment-existing"
    }
  ]
}

Error Response: 400 Bad Request (if no valid user IDs provided)

{
  "error": "InvalidRequest",
  "message": "At least one valid user ID must be provided",
  "details": {
    "invalidUserIds": ["invalid-id-1"],
    "validUserIds": []
  }
}

Get Users Assigned to Role

Endpoint: GET /api/v1/roles/{roleId}/users

Authentication: Required (role:read capability)

Query Parameters:

  • page - Page number (default: 1)
  • pageSize - Items per page (default: 50, max: 200)
  • search - Filter by user name or email
  • includeExpired - Include expired assignments (default: false)

Success Response: 200 OK

{
  "roleId": "role-abc",
  "roleName": "data-analyst",
  "roleDisplayName": "Data Analyst",
  "totalUsers": 15,
  "page": 1,
  "pageSize": 50,
  "users": [
    {
      "userId": "user-123",
      "fullName": "Sarah Johnson",
      "email": "sarah.johnson@example.com",
      "assignmentId": "assignment-456",
      "assignedAt": "2026-01-15T10:30:00Z",
      "assignedBy": "admin-user-id",
      "assignedByName": "Admin User",
      "expiresAt": null,
      "isActive": true
    },
    {
      "userId": "user-789",
      "fullName": "Michael Chen",
      "email": "michael.chen@example.com",
      "assignmentId": "assignment-789",
      "assignedAt": "2026-01-20T09:15:00Z",
      "assignedBy": "admin-user-id",
      "assignedByName": "Admin User",
      "expiresAt": "2026-06-30T23:59:59Z",
      "isActive": true
    }
  ]
}

Remove Users from Role (Bulk Revocation)

Endpoint: DELETE /api/v1/roles/{roleId}/users

Authentication: Required (role:revoke capability)

Request Body:

{
  "userIds": [
    "user-123",
    "user-456"
  ]
}

Success Response: 200 OK

{
  "roleId": "role-abc",
  "summary": {
    "totalRequested": 2,
    "successfullyRevoked": 2,
    "notFound": 0,
    "failed": 0
  },
  "results": [
    {
      "userId": "user-123",
      "status": "revoked",
      "revokedAt": "2026-01-30T14:30:00Z"
    },
    {
      "userId": "user-456",
      "status": "revoked",
      "revokedAt": "2026-01-30T14:30:00Z"
    }
  ]
}

Permission Checking

Check User Permission

Endpoint: POST /api/v1/authorization/check

Authentication: Required

Request Body:

{
  "userId": "user-789",
  "capability": "application:create"
}

Success Response: 200 OK

{
  "userId": "user-789",
  "capability": "application:create",
  "hasPermission": false,
  "reason": "User lacks required capability",
  "evaluatedAt": "2026-01-30T10:30:00Z",
  "sourceRoles": [],
  "suggestedRoles": ["admin", "app-developer"]
}

Get Current User's Permissions

Endpoint: GET /api/v1/authorization/me

Authentication: Required (current user's session)

Success Response: 200 OK

{
  "userId": "user-789",
  "roles": ["data-analyst", "viewer"],
  "capabilities": [
    "application:read",
    "application:access",
    "data:read",
    "data:export",
    "user:read"
  ],
  "computedAt": "2026-01-30T10:30:00Z"
}

Performance Requirements

Metric Target Critical Threshold
Role creation/update time < 500ms < 2 seconds
Permission check (cached) < 10ms < 50ms
Permission check (uncached) < 100ms < 500ms
Permission cache hit rate > 90% > 75%
User capability list computation < 200ms < 1 second
Role list page load < 1 second < 3 seconds
User role assignment < 300ms < 1 second
Concurrent permission checks 10,000/second 5,000/second
Cache invalidation propagation < 1 second < 5 seconds

Security Considerations

Principle of Least Privilege

  • Users granted only minimum capabilities needed for their role
  • Default deny policy: require explicit capability grants
  • Regular audit of role assignments and capability usage
  • Temporary role assignments with automatic expiration
  • Remove inactive user's roles after 90 days of no activity

Capability Granularity

  • Fine-grained capabilities preferred over coarse permissions
  • Avoid wildcard capabilities except for super admin
  • Separate read and write capabilities for sensitive resources
  • Capabilities follow resource:action naming convention
  • Dangerous capabilities require MFA (RequiresElevation flag)

Role Hierarchy and Separation

  • Built-in roles protected from modification/deletion
  • Custom roles scoped to organizations when applicable
  • Avoid role inheritance to reduce complexity
  • Multiple roles = union of capabilities (additive)
  • Explicit deny rules can be implemented if needed

Audit and Compliance

  • All role/capability changes logged with actor and timestamp
  • Permission denial attempts logged for security monitoring
  • Audit logs immutable and retained per compliance requirements
  • Regular access reviews: who has what roles and why
  • Alert on unusual permission patterns (privilege escalation)

Token and Session Security

  • Permission cache invalidated immediately on role changes
  • Session tokens re-validated against current capabilities
  • Cache TTL kept short (5 minutes) for security/freshness balance
  • Distributed cache invalidation across all application instances
  • Support for forced logout on critical permission changes

Protection Against Abuse

  • Rate limiting on role management operations
  • Prevent single point of failure: require multiple admins
  • Cannot remove Admin role from last administrator
  • Role deletion requires confirmation and audit trail
  • Sensitive operations require re-authentication

Testing Scenarios

Test Case 1: Create Custom Role

Given: Administrator with role:create capability
When: Administrator creates role "Data Analyst" with 11 capabilities
Then: Role created, capabilities assigned, audit logged
Verify: Role queryable, capabilities correct, users can be assigned

Test Case 2: Assign Role to User

Given: Active user and active role exist
When: Administrator assigns "Data Analyst" role to user
Then: User-role assignment created, cache invalidated
Verify: User can now perform actions granted by role capabilities

Test Case 3: Permission Check - Granted

Given: User has role with "application:read" capability
When: User requests GET /api/v1/applications
Then: Permission check succeeds, request processed
Verify: Audit log shows successful authorization

Test Case 4: Permission Check - Denied

Given: User lacks "application:delete" capability
When: User attempts DELETE /api/v1/applications/
Then: 403 Forbidden returned, request blocked
Verify: Audit log shows denied access attempt with details

Test Case 5: Multiple Roles - Union of Capabilities

Given: User has both "Viewer" and "Data Analyst" roles
When: System computes effective capabilities
Then: User has union of all capabilities from both roles
Verify: User can perform actions from either role

Test Case 6: Role Deletion with Active Users

Given: Role "Analyst" assigned to 15 users
When: Administrator attempts to delete role without force flag
Then: 409 Conflict returned, deletion prevented
Verify: Role and assignments remain intact

Test Case 7: Built-in Role Protection

Given: Built-in "Admin" role exists
When: Administrator attempts to modify or delete Admin role
Then: 403 Forbidden returned, operation blocked
Verify: Built-in role unchanged

Test Case 8: Permission Cache Performance

Given: User's permissions cached
When: User makes multiple requests requiring same capability
Then: Permission check completes in < 10ms (cache hit)
Verify: Database not queried repeatedly, cache hit logged

Test Case 9: Cache Invalidation on Role Change

Given: User has cached permissions
When: Administrator adds new capability to user's role
Then: User's cache invalidated within 1 second
Verify: Next permission check reflects new capability

Test Case 10: Expired Role Assignment Cleanup

Given: User has role with ExpiresAt in the past
When: Background cleanup job runs
Then: Expired role assignment removed
Verify: User no longer has capabilities from expired role

Monitoring and Analytics

Key Metrics to Track

  • Role Assignment Rate: Assignments per day/week/month
  • Permission Check Volume: Checks per second/minute/hour
  • Permission Denial Rate: Denied checks / Total checks
  • Cache Hit Rate: Cached checks / Total checks
  • Most Used Capabilities: Track which capabilities are most frequently checked
  • Unused Capabilities: Identify capabilities that are never used
  • Role Assignment Distribution: Users per role histogram
  • Average Capabilities per Role: Complexity metric
  • Custom Role Growth: New roles created over time

Performance Metrics

  • Permission Check Latency (p50, p95, p99): Response time distribution
  • Cache Miss Penalty: Latency difference cached vs uncached
  • Database Query Time: Role/capability lookup performance
  • API Endpoint Response Times: Role management operations

Security Metrics

  • Failed Authorization Attempts: Track potential unauthorized access
  • Privilege Escalation Attempts: Users trying to exceed their permissions
  • Admin Activity: Track all admin actions on roles/capabilities
  • Role Modification Frequency: High churn may indicate issues
  • Orphaned Role Assignments: Users with roles but no org/app access

Alerts

  • Permission denial rate > 10% (misconfigured roles or attack)
  • Cache hit rate < 75% (cache not working effectively)
  • Permission check latency p95 > 500ms (performance degradation)
  • Multiple failed permission checks for same user (investigate)
  • Built-in role modification attempt (should never happen)
  • Last admin role removal attempt (critical security alert)
  • Unusual spike in role assignments (potential compromise)

Dashboards

  • Role Management Overview: Total roles, capabilities, assignments
  • Permission Health: Check volume, denials, latency, cache performance
  • User Access Matrix: Users × Roles × Capabilities visualization
  • Security Dashboard: Failed auth attempts, privilege escalation, admin actions
  • Capability Usage Heatmap: Which capabilities are frequently checked
  • UC-001: Trial User Self-Registration and Access (trial users get TrialUser role)
  • UC-002: User Authentication and Session Management (session validates roles)
  • UC-003: Application Access Control (checks user capabilities for app access)
  • UC-004: Organization Management (organization-scoped roles)
  • UC-005: User Profile Management (users view/update their assigned roles)
  • UC-007: Audit Log and Compliance Reporting (all RBAC changes logged)
  • UC-008: System Administration Dashboard (admin manages roles/capabilities)
  • UC-009: API Token Management (API tokens inherit user's capabilities)
  • UC-010: Multi-Factor Authentication (MFA required for elevated capabilities)

Notes and Assumptions

  1. Union Strategy: Multiple roles grant union of capabilities (additive permissions model)
  2. No Role Hierarchy: Roles are flat; inheritance not currently implemented
  3. Organization Scope: Custom roles can be scoped to specific organizations
  4. Built-in Role Stability: Built-in roles have fixed names and IDs across deployments
  5. Wildcard Capabilities: Support for resource:* and *:* wildcard patterns
  6. Caching Strategy: Redis-backed permission cache with 5-minute TTL
  7. Eventual Consistency: Cache invalidation may take up to 1 second to propagate
  8. MFA for Dangerous Operations: Some capabilities require MFA re-authentication
  9. Audit Retention: RBAC audit logs retained for 365 days minimum
  10. API vs UI Permissions: Same capability model enforced for both API and UI
  11. Service Accounts: Future enhancement for non-human identity roles
  12. Dynamic Capabilities: Capabilities are seeded at deployment, not user-creatable
  13. Explicit Deny: Not currently implemented; may be added in future version
  14. Role Templates: Future enhancement for quick role creation from templates

Revision History

Version Date Author Changes
1.0 2026-01-30 System Analyst Initial use case documentation

Document Owner: Platform Architecture Team
Stakeholders: Security Team, Engineering, Product Management, Compliance
Review Cycle: Quarterly or as needed for security/compliance changes