RBAC Role Hierarchy

Overview

ASCEND implements a 6-level Role-Based Access Control (RBAC) hierarchy designed for enterprise security requirements. Each level inherits permissions from lower levels and adds additional capabilities, creating a clear escalation path from basic users to executives.

Why It Matters

A well-defined role hierarchy ensures:

Least Privilege: Users receive only the permissions they need
Clear Escalation: Defined path for privilege elevation requests
Audit Trail: Role-based access is easy to track and audit
Compliance: Meets SOC 2, HIPAA, and PCI-DSS access control requirements
Operational Efficiency: Reduces permission management overhead

Architecture

Role Hierarchy Diagram

                    ┌─────────────────────────────────────────┐
                    │         LEVEL 5: EXECUTIVE              │
                    │                                         │
                    │  All privileges + critical overrides    │
                    │  Emergency override capability          │
                    │  Delete audit logs                      │
                    │  System backup/maintenance              │
                    └────────────────────┬────────────────────┘
                                         │
                    ┌────────────────────┴────────────────────┐
                    │           LEVEL 4: ADMIN                │
                    │                                         │
                    │  Full system access                     │
                    │  Approve HIGH risk (70-89)              │
                    │  User management                        │
                    │  System configuration                   │
                    └────────────────────┬────────────────────┘
                                         │
                    ┌────────────────────┴────────────────────┐
                    │          LEVEL 3: MANAGER               │
                    │                                         │
                    │  Authorization capabilities             │
                    │  Approve LOW/MEDIUM risk (0-69)         │
                    │  View audit logs                        │
                    │  Analytics reports                      │
                    └────────────────────┬────────────────────┘
                                         │
                    ┌────────────────────┴────────────────────┐
                    │           LEVEL 2: POWER                │
                    │                                         │
                    │  Analytics access                       │
                    │  Alert management                       │
                    │  Dashboard export                       │
                    └────────────────────┬────────────────────┘
                                         │
                    ┌────────────────────┴────────────────────┐
                    │           LEVEL 1: BASIC                │
                    │                                         │
                    │  Dashboard view only                    │
                    │  Read-only access                       │
                    └────────────────────┬────────────────────┘
                                         │
                    ┌────────────────────┴────────────────────┐
                    │         LEVEL 0: RESTRICTED             │
                    │                                         │
                    │  No permissions                         │
                    │  Suspended/probationary accounts        │
                    └─────────────────────────────────────────┘

Role Definitions

Level 0: RESTRICTED

Purpose: Suspended or probationary accounts with no access.

Property	Value
Access Level	0
Permissions	None
Use Case	Suspended accounts, pending verification
Can Approve	Nothing

When to Use:

Account under investigation
Terminated employee (pending deletion)
New account pending verification
Security incident response (immediate suspension)

Level 1: BASIC

Purpose: Standard users with dashboard view access only.

Property	Value
Access Level	1
Permissions	`dashboard.view`
Use Case	View-only stakeholders
Can Approve	Nothing

Permissions:

{
    Permission.DASHBOARD_VIEW
}

When to Use:

External auditors (read-only access)
Stakeholders needing visibility
New employees during onboarding
Limited-access contractors

Level 2: POWER

Purpose: Power users with analytics and alert management capabilities.

Property	Value
Access Level	2
Permissions	5 permissions
Use Case	Analysts, operators
Can Approve	Nothing

Permissions:

{
    Permission.DASHBOARD_VIEW,
    Permission.DASHBOARD_EXPORT,
    Permission.ANALYTICS_VIEW,
    Permission.ALERTS_VIEW,
    Permission.ALERTS_ACKNOWLEDGE
}

When to Use:

Security analysts
Operations team members
Support engineers
Data analysts

Level 3: MANAGER

Purpose: Managers with authorization capabilities for low/medium risk actions.

Property	Value
Access Level	3
Permissions	12 permissions
Use Case	Team leads, managers
Can Approve	LOW (0-49), MEDIUM (50-69)

Permissions:

{
    Permission.DASHBOARD_VIEW,
    Permission.DASHBOARD_EXPORT,
    Permission.ANALYTICS_VIEW,
    Permission.ANALYTICS_REPORTS,
    Permission.ANALYTICS_EXPORT,
    Permission.ALERTS_VIEW,
    Permission.ALERTS_ACKNOWLEDGE,
    Permission.ALERTS_CORRELATE,
    Permission.AUTH_VIEW_PENDING,
    Permission.AUTH_APPROVE_LOW,
    Permission.AUTH_APPROVE_MEDIUM,
    Permission.AUDIT_VIEW
}

When to Use:

Team leads
Department managers
Senior analysts
Compliance officers (review only)

Level 4: ADMIN

Purpose: Administrators with full system access except critical overrides.

Property	Value
Access Level	4
Permissions	22 permissions
Use Case	System administrators
Can Approve	LOW, MEDIUM, HIGH (70-89)

Permissions:

{
    # All MANAGER permissions plus:
    Permission.ALERTS_DISMISS,
    Permission.RULES_VIEW,
    Permission.RULES_CREATE,
    Permission.RULES_MODIFY,
    Permission.RULES_DELETE,
    Permission.AUTH_APPROVE_HIGH,
    Permission.USERS_VIEW,
    Permission.USERS_CREATE,
    Permission.USERS_MODIFY,
    Permission.USERS_RESET_PASSWORD,
    Permission.AUDIT_EXPORT,
    Permission.SYSTEM_CONFIG
}

When to Use:

IT administrators
Security administrators
DevOps engineers
Platform engineers

Level 5: EXECUTIVE

Purpose: Executives with all privileges including critical overrides.

Property	Value
Access Level	5
Permissions	All 23+ permissions
Use Case	C-level, senior leadership
Can Approve	ALL including CRITICAL (90-100)

Permissions:

{
    # All ADMIN permissions plus:
    Permission.AUTH_APPROVE_CRITICAL,
    Permission.AUTH_EMERGENCY_OVERRIDE,
    Permission.USERS_DELETE,
    Permission.USERS_MANAGE_ROLES,
    Permission.AUDIT_DELETE,
    Permission.SYSTEM_BACKUP,
    Permission.SYSTEM_MAINTENANCE
}

When to Use:

CISO / CSO
CTO / CIO
VP of Engineering
Director of Security

Risk-Based Approval Matrix

Approval Requirements by Risk Score

Risk Score	Risk Level	Required Role	SoD Requirement
0-49	Low	MANAGER (3)	Single approver
50-69	Medium	MANAGER (3)	Single approver
70-89	High	ADMIN (4)	Dual approval (2 ADMINs)
90-100	Critical	EXECUTIVE (5)	Dual approval (2 EXECUTIVEs, different depts)

Approval Check Implementation

def can_approve_risk_level(self, user_access_level: int, risk_score: int) -> bool:
    """Check if user can approve actions with specific risk score."""

    if risk_score < 50:
        return self.has_permission(user_access_level, Permission.AUTH_APPROVE_LOW)
    elif risk_score < 70:
        return self.has_permission(user_access_level, Permission.AUTH_APPROVE_MEDIUM)
    elif risk_score < 90:
        return self.has_permission(user_access_level, Permission.AUTH_APPROVE_HIGH)
    else:
        return self.has_permission(user_access_level, Permission.AUTH_APPROVE_CRITICAL)

Separation of Duties (SoD)

High-Risk Approval (70-89)

{
    "description": "High-risk actions require dual approval",
    "risk_threshold": 70,
    "required_approvers": 2,
    "required_levels": [AccessLevel.ADMIN, AccessLevel.EXECUTIVE],
    "cannot_approve_own": True
}

Requirements:

2 separate approvers required
Both must be ADMIN (4) or higher
Cannot approve your own request
Logged with both approver IDs

Critical Risk Approval (90-100)

{
    "description": "Critical actions require executive + admin approval",
    "risk_threshold": 90,
    "required_approvers": 2,
    "required_levels": [AccessLevel.EXECUTIVE],
    "required_different_departments": True,
    "cannot_approve_own": True
}

Requirements:

2 EXECUTIVE approvers required
Must be from different departments
Cannot approve your own request
Immediate audit notification
Mandatory justification

User Role Changes

{
    "description": "User role changes require manager + admin",
    "required_approvers": 2,
    "required_levels": [AccessLevel.MANAGER, AccessLevel.ADMIN],
    "cannot_approve_own": True
}

Requirements:

MANAGER and ADMIN approval required
Cannot approve your own role change
Logged with change details

Emergency Override

{
    "description": "Emergency overrides require dual executive approval",
    "required_approvers": 2,
    "required_levels": [AccessLevel.EXECUTIVE],
    "required_justification": True,
    "audit_immediately": True
}

Requirements:

2 EXECUTIVE approvers required
Written justification mandatory
Immediate audit log entry
Security team notification

Configuration

Environment Variables

# Default role for new users
DEFAULT_USER_ROLE=basic

# SoD thresholds
SOD_HIGH_RISK_THRESHOLD=70
SOD_CRITICAL_RISK_THRESHOLD=90

# Require SoD for high-risk actions
REQUIRE_SOD_FOR_HIGH_RISK=true

Database Schema

-- Users table role configuration
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    role VARCHAR(50) NOT NULL DEFAULT 'basic',
    access_level INTEGER NOT NULL DEFAULT 1,
    organization_id INTEGER NOT NULL,
    is_active BOOLEAN DEFAULT TRUE,
    department VARCHAR(100),  -- For SoD department checks
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Role change audit log
CREATE TABLE role_change_audit (
    id SERIAL PRIMARY KEY,
    user_id INTEGER NOT NULL,
    old_role VARCHAR(50),
    new_role VARCHAR(50),
    changed_by INTEGER NOT NULL,
    approved_by INTEGER,  -- Second approver if required
    reason TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Usage

Check User Role

from rbac_manager import enterprise_rbac, AccessLevel

# Get role summary
role_info = enterprise_rbac.get_role_summary(user.access_level)
print(role_info)
# {
#     "access_level": 4,
#     "role_name": "Administrator",
#     "permissions": [...],
#     "permission_count": 22,
#     "can_approve_low": True,
#     "can_approve_medium": True,
#     "can_approve_high": True,
#     "can_approve_critical": False,
#     "requires_sod_for_high_risk": True
# }

Enforce Minimum Level

from rbac_manager import require_minimum_level, AccessLevel

@require_minimum_level(AccessLevel.MANAGER)
async def approve_action(current_user: dict, action_id: int):
    # Only MANAGER (3) or higher can access
    pass

Check SoD Requirement

from rbac_manager import enterprise_rbac

sod = enterprise_rbac.requires_separation_of_duties(
    action_type="approval",
    risk_score=85
)

if sod:
    print(f"Requires {sod['required_approvers']} approvers")
    print(f"Required levels: {sod['required_levels']}")

API Endpoints

Get Role Information

curl -X GET https://api.ascend.io/v1/auth/role \
  -H "Authorization: Bearer $TOKEN"

# Response
{
  "access_level": 4,
  "role_name": "Administrator",
  "permissions": ["dashboard.view", "dashboard.export", ...],
  "permission_count": 22,
  "can_approve": {
    "low": true,
    "medium": true,
    "high": true,
    "critical": false
  }
}

Change User Role (Requires SoD)

# Request role change (first approval)
curl -X POST https://api.ascend.io/v1/users/123/role-change \
  -H "Authorization: Bearer $MANAGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "new_role": "admin",
    "reason": "Promotion to security administrator"
  }'

# Response
{
  "change_id": 456,
  "status": "pending_second_approval",
  "required_approver_level": "admin",
  "requested_by": "manager@example.com",
  "requested_at": "2026-01-20T10:00:00Z"
}

# Second approval (by ADMIN)
curl -X POST https://api.ascend.io/v1/role-changes/456/approve \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "approved": true,
    "reason": "Verified promotion request"
  }'

Compliance Mapping

Framework	Control	Implementation
SOC 2	CC6.1	Role-based access control
SOC 2	CC6.2	Separation of duties enforcement
SOC 2	CC6.3	Role-based authorization
HIPAA	164.312(a)(1)	Access control mechanisms
PCI-DSS	Req 7.1	Need-to-know access restriction
PCI-DSS	Req 7.2	Access control system coverage
NIST 800-53	AC-2	Account management
NIST 800-53	AC-3	Access enforcement
NIST 800-53	AC-5	Separation of duties
NIST 800-53	AC-6	Least privilege

Verification

Test Role Hierarchy

# As BASIC user, try to access analytics
curl -X GET https://api.ascend.io/v1/analytics/reports \
  -H "Authorization: Bearer $BASIC_TOKEN"

# Expected: 403 Forbidden
{
  "detail": "Insufficient access level. Required: 2, Current: 1"
}

# As POWER user, same request succeeds
curl -X GET https://api.ascend.io/v1/analytics/reports \
  -H "Authorization: Bearer $POWER_TOKEN"

# Expected: 200 OK

Test SoD Enforcement

# Try to approve high-risk action as single ADMIN
curl -X POST https://api.ascend.io/v1/actions/123/approve \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"approved": true}'

# Expected: Pending second approval
{
  "status": "pending_second_approval",
  "risk_score": 85,
  "sod_requirement": {
    "required_approvers": 2,
    "current_approvers": 1,
    "first_approver": "admin@example.com"
  }
}

Next Steps

Permissions Reference - All 23+ permissions
AI Security Overview - AI-specific security
Compliance Overview - Framework mapping

Overview​

Why It Matters​

Architecture​

Role Hierarchy Diagram​

Role Definitions​

Level 0: RESTRICTED​

Level 1: BASIC​

Level 2: POWER​

Level 3: MANAGER​

Level 4: ADMIN​

Level 5: EXECUTIVE​

Risk-Based Approval Matrix​

Approval Requirements by Risk Score​

Approval Check Implementation​

Separation of Duties (SoD)​

High-Risk Approval (70-89)​

Critical Risk Approval (90-100)​

User Role Changes​

Emergency Override​

Configuration​

Environment Variables​

Database Schema​

Usage​

Check User Role​

Enforce Minimum Level​

Check SoD Requirement​

API Endpoints​

Get Role Information​

Change User Role (Requires SoD)​

Compliance Mapping​

Verification​

Test Role Hierarchy​

Test SoD Enforcement​

Next Steps​

Overview

Why It Matters

Architecture

Role Hierarchy Diagram

Role Definitions

Level 0: RESTRICTED

Level 1: BASIC

Level 2: POWER

Level 3: MANAGER

Level 4: ADMIN

Level 5: EXECUTIVE

Risk-Based Approval Matrix

Approval Requirements by Risk Score

Approval Check Implementation

Separation of Duties (SoD)

High-Risk Approval (70-89)

Critical Risk Approval (90-100)

User Role Changes

Emergency Override

Configuration

Environment Variables

Database Schema

Usage

Check User Role

Enforce Minimum Level

Check SoD Requirement

API Endpoints

Get Role Information

Change User Role (Requires SoD)

Compliance Mapping

Verification

Test Role Hierarchy

Test SoD Enforcement

Next Steps