RBAC System

Purpose and Scope

This document provides an overview of the Role-Based Access Control (RBAC) system in the Light framework, which governs authorization across the entire application. The RBAC system manages role hierarchies, permission assignments, and authorization checks at multiple levels including GraphQL fields, controller methods, and menu items.

For authentication mechanisms and user session management, see Authentication Architecture. For detailed implementation of permission checking annotations and enforcement mechanisms, see Permission Checking.

System Overview

The RBAC system is implemented through the Light\Rbac\Rbac class and initialized during application bootstrap. It provides a hierarchical role model where permissions cascade through parent-child role relationships, with support for user-specific permission overrides. The system aggregates permissions from multiple sources and enforces them through GraphQL annotations, controller middleware, and menu filtering.

Diagram: RBAC System Architecture and Data Flow

Sources: src/App.php306-366 src/App.php392-472 permissions.yml1-16 menus.yml1-171

Built-in Role Hierarchy

The system defines four built-in roles with hierarchical inheritance. Each child role inherits all permissions from its parent roles, creating a cascading permission structure.

Diagram: Built-in Role Hierarchy

Each role receives a special permission prefixed with # (hash) that identifies members of that role. For example, users in the "Administrators" role automatically receive the #administrators permission. The Administrators role also receives the wildcard permission *, which grants access to all operations in the system.

Sources: src/App.php308-323

Permission Sources

The RBAC system aggregates permissions from six distinct sources, each serving different use cases:

Source	File/Location	Purpose	Example
Static YAML	permissions.yml	Version-controlled role definitions	Administrators: ['*']
Database Roles	Role model	Dynamic parent-child role relationships	Role hierarchy stored in DB
Database Permissions	Permission model	Runtime permission assignments to roles/users	User-specific grants
User Roles	UserRole model	Many-to-many user-role mapping	Assigning users to roles
Menu Permissions	menus.yml	Navigation authorization requirements	permission: user.list
Annotations	@Right attributes	Code-declared permission requirements	#[Right("user.add")]

Sources: src/App.php338-356 permissions.yml1-16 menus.yml1-171

Permission Format and Conventions

Permissions follow a hierarchical dot-notation format that mirrors the resource and action structure:

• Resource-based: {resource}.{action} (e.g., user.add, role.list, user.changePassword)
• Namespace-based: {namespace}.{resource}.{action} (e.g., system.database.table, filesystem.list)
• Wildcard: * grants all permissions (reserved for Administrators)
• Role markers: #{rolename} identifies role membership (e.g., #administrators, #users)

The system discovers permissions dynamically by scanning for @Right annotations across multiple namespaces:

Diagram: Permission Discovery Process

Sources: src/App.php392-472

RBAC Initialization Sequence

The RBAC system is initialized during application bootstrap through the App constructor. The initialization process loads permissions from all sources and builds the complete authorization model:

Diagram: RBAC Initialization Sequence

The initialization follows a specific order to ensure proper inheritance:

1. Built-in roles establish the base hierarchy
2. Database roles extend the hierarchy with custom roles
3. Static YAML permissions assign bulk permissions to roles
4. Dynamic database permissions provide granular overrides
5. User-role assignments map users to their roles

Sources: src/App.php306-366

Authorization Enforcement

The RBAC system enforces authorization through multiple integration points across the application:

GraphQL Schema Factory Integration

The Auth\Service is registered as both the authentication and authorization service for the GraphQL schema factory. This enables automatic permission checking on GraphQL fields decorated with @Right annotations:

Diagram: GraphQL Authorization Flow

Sources: src/App.php500-537 src/App.php529-530

Permission Discovery and Registration

The system discovers all permissions at runtime by scanning PHP attributes across the codebase. This ensures that permissions declared in code through @Right annotations are available for assignment and checking:

Scan Target	Purpose	Method
Light\Controller\*	GraphQL mutation permissions	Reflection on controller methods
Light\Model\*	Model method permissions	Reflection on model methods
Light\Type\*	GraphQL query permissions	Reflection on type methods
Light\Database\*	Database operation permissions	Reflection on database classes
Controller\* (external)	Extension controller permissions	ComposerFinder namespace scan
Model\* (external)	Extension model permissions	ComposerFinder namespace scan
menus.yml	Navigation permissions	YAML parsing

Sources: src/App.php392-472

Role and User Permission Models

The system uses three database models to persist dynamic authorization data:

Role Model: Stores parent-child relationships between roles, allowing hierarchical role structures beyond the four built-in roles. Each record represents an inheritance relationship where the name column is the parent role and child column is the child role.

Permission Model: Stores individual permission grants that can be assigned to either roles (via role column) or specific users (via user_id column). The value column contains the permission string (e.g., user.add). This model enables runtime permission adjustments without code changes.

UserRole Model: Maps users to roles through a many-to-many relationship. Each record assigns a user (via user_id) to a role (via role column), enabling users to hold multiple roles simultaneously.

Sources: src/App.php325-363

Integration with Application Core

The RBAC system is tightly integrated with the App class, which serves as the central orchestrator:

Diagram: RBAC Integration with App Core

The App class exposes several methods for RBAC operations:

• loadRbac(): Initializes the RBAC system from all sources src/App.php306-366
• addRolePermissions(string $role, array $permissions): Adds multiple permissions to a role src/App.php294-304
• getPermissions(): Discovers all permissions across the codebase src/App.php392-472
• getRbac(): Returns the RBAC instance for direct access src/App.php480-483

Sources: src/App.php49 src/App.php128-129 src/App.php294-304 src/App.php306-366 src/App.php392-472 src/App.php480-483

Static Permission Configuration

The permissions.yml file defines baseline permissions for built-in roles using YAML syntax:

Key characteristics:

• The Administrators role uses the wildcard * to grant all permissions
• The Power Users role explicitly lists user and role management permissions
• These permissions are loaded during RBAC initialization via Yaml::parseFile() src/App.php338
• Static permissions serve as the baseline; database permissions can extend or override them

Sources: permissions.yml1-16 src/App.php338-343

Menu-Based Permissions

The menu system integrates with RBAC to control navigation access. Menu items in menus.yml can specify required permissions, which are extracted and added to the RBAC system during initialization:

Menu permission features:

• Single permission: permission: user.list
• Multiple permissions: permission: [permission.list, permission.add, permission:remove]
• Nested menus inherit permission requirements from parent items
• The App.getMenusPermission() method recursively extracts permissions from the menu tree src/App.php368-390
• All menu permissions are added to the RBAC system's permission registry

Sources: menus.yml4-15 src/App.php368-390 src/App.php453-455

Summary

The RBAC system provides comprehensive authorization control through:

1. Hierarchical Roles: Built-in role inheritance with support for custom roles
2. Multiple Permission Sources: YAML files, database records, code annotations, and menu definitions
3. Dynamic Discovery: Automatic permission detection through reflection scanning
4. Flexible Assignment: Permissions can be assigned to roles or individual users
5. Deep Integration: Authorization enforced at GraphQL field level, controller methods, and menu items
6. Wildcard Support: Administrators receive full system access via the * permission

The system is initialized during application bootstrap and integrates with the authentication service to provide seamless authorization throughout the request lifecycle.

Sources: src/App.php38-940 permissions.yml1-16 menus.yml1-171