Initial commit: StreamFlow IPTV platform
This commit is contained in:
aiulian25
commit
73a8ae9ffd
1240 changed files with 278451 additions and 0 deletions
885
docs/RBAC_IMPLEMENTATION.md
Normal file
885
docs/RBAC_IMPLEMENTATION.md
Normal file
|
|
@ -0,0 +1,885 @@
|
|||
# Role-Based Access Control (RBAC) Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes the comprehensive Role-Based Access Control (RBAC) system implemented in StreamFlow, following the **Principle of Least Privilege**. The RBAC system provides granular permission management, ensuring users have only the minimum access rights needed to perform their functions.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Architecture](#architecture)
|
||||
2. [Permission System](#permission-system)
|
||||
3. [Default Roles](#default-roles)
|
||||
4. [API Reference](#api-reference)
|
||||
5. [Frontend Integration](#frontend-integration)
|
||||
6. [Security Considerations](#security-considerations)
|
||||
7. [Audit Logging](#audit-logging)
|
||||
8. [Migration Guide](#migration-guide)
|
||||
9. [Best Practices](#best-practices)
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Components
|
||||
|
||||
The RBAC system consists of four main components:
|
||||
|
||||
1. **RBAC Middleware** (`backend/middleware/rbac.js`)
|
||||
- Permission checking logic
|
||||
- Role initialization
|
||||
- Permission caching
|
||||
- Audit logging utilities
|
||||
|
||||
2. **RBAC Routes** (`backend/routes/rbac.js`)
|
||||
- Role CRUD operations
|
||||
- User role assignment
|
||||
- Permission queries
|
||||
- Audit log retrieval
|
||||
|
||||
3. **Database Schema**
|
||||
- `roles` table: Role definitions and permissions
|
||||
- `permission_audit_log` table: Audit trail for permission changes
|
||||
|
||||
4. **RBAC Dashboard** (`frontend/src/components/RBACDashboard.jsx`)
|
||||
- Visual role management interface
|
||||
- User role assignment UI
|
||||
- Permission viewer
|
||||
- Audit log browser
|
||||
|
||||
### Database Schema
|
||||
|
||||
#### Roles Table
|
||||
```sql
|
||||
CREATE TABLE roles (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
role_key TEXT UNIQUE NOT NULL,
|
||||
name TEXT NOT NULL,
|
||||
description TEXT,
|
||||
permissions TEXT NOT NULL, -- JSON array
|
||||
is_system_role BOOLEAN DEFAULT 0,
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||
)
|
||||
```
|
||||
|
||||
#### Permission Audit Log Table
|
||||
```sql
|
||||
CREATE TABLE permission_audit_log (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
user_id INTEGER NOT NULL,
|
||||
action TEXT NOT NULL,
|
||||
target_type TEXT NOT NULL,
|
||||
target_id INTEGER,
|
||||
old_value TEXT, -- JSON
|
||||
new_value TEXT, -- JSON
|
||||
ip_address TEXT,
|
||||
user_agent TEXT,
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Permission System
|
||||
|
||||
### Permission Categories
|
||||
|
||||
The system defines **70+ granular permissions** across 7 categories:
|
||||
|
||||
#### 1. User Management
|
||||
- `users.view` - View user list and details
|
||||
- `users.create` - Create new users
|
||||
- `users.edit` - Edit existing users
|
||||
- `users.delete` - Delete users
|
||||
- `users.manage_roles` - Assign and modify user roles
|
||||
- `users.unlock` - Unlock locked user accounts
|
||||
- `users.reset_password` - Reset user passwords
|
||||
|
||||
#### 2. Session Management
|
||||
- `sessions.view_own` - View own active sessions
|
||||
- `sessions.view_all` - View all user sessions
|
||||
- `sessions.terminate_own` - Terminate own sessions
|
||||
- `sessions.terminate_any` - Terminate any user session
|
||||
- `sessions.view_stats` - View session statistics
|
||||
|
||||
#### 3. Content Management
|
||||
- `playlists.*` - Create, view, edit, delete, import playlists
|
||||
- `channels.*` - View, edit channels, manage logos
|
||||
- `favorites.*` - View and manage favorites
|
||||
- `history.*` - View own/all history, delete history
|
||||
|
||||
#### 4. System & Settings
|
||||
- `settings.*` - View and edit application settings
|
||||
- `stats.*` - View analytics and detailed statistics
|
||||
- `backup.*` - Create, restore, delete, download backups
|
||||
|
||||
#### 5. Security Management
|
||||
- `security.view_sessions` - View security session dashboard
|
||||
- `security.view_csp` - View CSP violation dashboard
|
||||
- `security.manage_2fa` - Manage two-factor authentication
|
||||
- `security.view_audit` - View audit logs
|
||||
|
||||
#### 6. Search & Discovery
|
||||
- `search.use` - Use search functionality
|
||||
- `search.admin` - Search users and system settings
|
||||
|
||||
### Permission Checking
|
||||
|
||||
#### Middleware Functions
|
||||
|
||||
**`requirePermission(permissions)`**
|
||||
- Requires ANY of the specified permissions
|
||||
- Usage: `requirePermission('users.view')`
|
||||
- Usage: `requirePermission(['users.view', 'users.edit'])`
|
||||
|
||||
**`requireAllPermissions(permissions)`**
|
||||
- Requires ALL of the specified permissions
|
||||
- Usage: `requireAllPermissions(['users.view', 'users.manage_roles'])`
|
||||
|
||||
**`hasPermission(userId, permission)`**
|
||||
- Programmatic permission check
|
||||
- Returns: Promise<boolean>
|
||||
|
||||
**`hasAnyPermission(userId, permissionList)`**
|
||||
- Check if user has ANY permission
|
||||
- Returns: Promise<boolean>
|
||||
|
||||
**`hasAllPermissions(userId, permissionList)`**
|
||||
- Check if user has ALL permissions
|
||||
- Returns: Promise<boolean>
|
||||
|
||||
#### Example Usage in Routes
|
||||
|
||||
```javascript
|
||||
const { requirePermission, requireAllPermissions } = require('../middleware/rbac');
|
||||
|
||||
// Require ANY of the specified permissions
|
||||
router.get('/users',
|
||||
authenticate,
|
||||
requirePermission('users.view'),
|
||||
(req, res) => {
|
||||
// Only users with 'users.view' permission can access
|
||||
}
|
||||
);
|
||||
|
||||
// Require ALL specified permissions
|
||||
router.post('/roles',
|
||||
authenticate,
|
||||
requireAllPermissions(['users.manage_roles', 'users.create']),
|
||||
(req, res) => {
|
||||
// Only users with BOTH permissions can access
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
### Permission Caching
|
||||
|
||||
- Permissions are cached for 5 minutes to reduce database queries
|
||||
- Cache is automatically cleared when:
|
||||
- User role is changed
|
||||
- Role permissions are updated
|
||||
- Custom roles are created/deleted
|
||||
- Manual cache control available:
|
||||
- `clearUserPermissionCache(userId)` - Clear specific user
|
||||
- `clearAllPermissionCache()` - Clear entire cache
|
||||
|
||||
---
|
||||
|
||||
## Default Roles
|
||||
|
||||
### Admin
|
||||
**Full system access** - All permissions enabled
|
||||
|
||||
- Complete control over users, roles, and permissions
|
||||
- Access to all security dashboards
|
||||
- Backup and restore capabilities
|
||||
- System statistics and monitoring
|
||||
|
||||
**User Count**: Restricted (last admin cannot be deleted)
|
||||
|
||||
### Moderator
|
||||
**Content management and user support**
|
||||
|
||||
Key Permissions:
|
||||
- View users (but not manage)
|
||||
- Full content management (playlists, channels)
|
||||
- Manage all user history
|
||||
- View detailed statistics
|
||||
- Manage own sessions and 2FA
|
||||
|
||||
Restrictions:
|
||||
- Cannot create/edit/delete users
|
||||
- Cannot manage roles or permissions
|
||||
- Cannot access backups
|
||||
- Cannot view audit logs
|
||||
|
||||
### User
|
||||
**Standard user with content access**
|
||||
|
||||
Key Permissions:
|
||||
- Manage own playlists and favorites
|
||||
- Upload custom channel logos
|
||||
- View and delete own history
|
||||
- Manage own sessions
|
||||
- Own 2FA management
|
||||
|
||||
Restrictions:
|
||||
- Cannot view other users' data
|
||||
- Cannot access admin features
|
||||
- Cannot view statistics
|
||||
- Limited to own resources
|
||||
|
||||
### Viewer
|
||||
**Read-only access for content viewing**
|
||||
|
||||
Key Permissions:
|
||||
- View playlists and channels
|
||||
- Manage favorites
|
||||
- View and delete own history
|
||||
- Basic search functionality
|
||||
- Own session management
|
||||
|
||||
Restrictions:
|
||||
- Cannot create or import playlists
|
||||
- Cannot upload logos
|
||||
- Cannot modify settings
|
||||
- Minimal permissions (principle of least privilege)
|
||||
|
||||
---
|
||||
|
||||
## API Reference
|
||||
|
||||
### Base URL
|
||||
All RBAC endpoints are under `/api/rbac`
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### Get All Permissions
|
||||
```http
|
||||
GET /api/rbac/permissions
|
||||
Authorization: Bearer {token}
|
||||
Required Permission: users.manage_roles
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"permissions": [
|
||||
{ "key": "users.view", "description": "View user list and details" },
|
||||
...
|
||||
],
|
||||
"categories": {
|
||||
"User Management": ["users.view", "users.create", ...],
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Get All Roles
|
||||
```http
|
||||
GET /api/rbac/roles
|
||||
Authorization: Bearer {token}
|
||||
Required Permission: users.view
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"role_key": "admin",
|
||||
"name": "Administrator",
|
||||
"description": "Full system access",
|
||||
"permissions": ["users.view", "users.create", ...],
|
||||
"is_system_role": true,
|
||||
"created_at": "2024-01-01T00:00:00.000Z",
|
||||
"updated_at": "2024-01-01T00:00:00.000Z"
|
||||
},
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
#### Get Single Role
|
||||
```http
|
||||
GET /api/rbac/roles/:roleKey
|
||||
Authorization: Bearer {token}
|
||||
Required Permission: users.view
|
||||
```
|
||||
|
||||
#### Create Custom Role
|
||||
```http
|
||||
POST /api/rbac/roles
|
||||
Authorization: Bearer {token}
|
||||
Required Permissions: users.manage_roles AND users.create
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"role_key": "content_manager",
|
||||
"name": "Content Manager",
|
||||
"description": "Manages playlists and channels",
|
||||
"permissions": [
|
||||
"playlists.view",
|
||||
"playlists.create",
|
||||
"playlists.edit",
|
||||
"channels.view",
|
||||
"channels.edit"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Response:** 201 Created with role object
|
||||
|
||||
**Validation:**
|
||||
- `role_key`: lowercase letters and underscores only, 2-50 chars
|
||||
- `name`: 2-100 chars
|
||||
- `description`: max 500 chars (optional)
|
||||
- `permissions`: array of valid permission keys
|
||||
|
||||
#### Update Role
|
||||
```http
|
||||
PATCH /api/rbac/roles/:roleKey
|
||||
Authorization: Bearer {token}
|
||||
Required Permission: users.manage_roles
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "Updated Name",
|
||||
"description": "Updated description",
|
||||
"permissions": [...]
|
||||
}
|
||||
```
|
||||
|
||||
**Restrictions:**
|
||||
- Cannot modify system roles (admin, moderator, user, viewer)
|
||||
- All fields optional
|
||||
|
||||
#### Delete Custom Role
|
||||
```http
|
||||
DELETE /api/rbac/roles/:roleKey
|
||||
Authorization: Bearer {token}
|
||||
Required Permission: users.manage_roles
|
||||
```
|
||||
|
||||
**Restrictions:**
|
||||
- Cannot delete system roles
|
||||
- Cannot delete roles assigned to users
|
||||
|
||||
#### Get User's Permissions
|
||||
```http
|
||||
GET /api/rbac/my-permissions
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"role": "user",
|
||||
"role_name": "Regular User",
|
||||
"role_description": "Standard user with content access",
|
||||
"permissions": ["playlists.view", "playlists.create", ...],
|
||||
"permission_details": [
|
||||
{
|
||||
"key": "playlists.view",
|
||||
"description": "View playlists"
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Assign Role to User
|
||||
```http
|
||||
POST /api/rbac/users/:userId/role
|
||||
Authorization: Bearer {token}
|
||||
Required Permission: users.manage_roles
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"role": "moderator"
|
||||
}
|
||||
```
|
||||
|
||||
**Restrictions:**
|
||||
- Cannot modify own role
|
||||
- Role must exist
|
||||
|
||||
#### Get Audit Log
|
||||
```http
|
||||
GET /api/rbac/audit-log?action=role_created&userId=5&limit=50&offset=0
|
||||
Authorization: Bearer {token}
|
||||
Required Permission: security.view_audit
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `action`: Filter by action type (optional)
|
||||
- `userId`: Filter by user ID (optional)
|
||||
- `targetType`: Filter by target type (optional)
|
||||
- `limit`: Records per page (default: 100)
|
||||
- `offset`: Pagination offset (default: 0)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"logs": [
|
||||
{
|
||||
"id": 1,
|
||||
"user_id": 1,
|
||||
"username": "admin",
|
||||
"action": "role_created",
|
||||
"target_type": "role",
|
||||
"target_id": 5,
|
||||
"old_value": null,
|
||||
"new_value": {
|
||||
"role_key": "content_manager",
|
||||
"name": "Content Manager",
|
||||
"permissions": [...]
|
||||
},
|
||||
"ip_address": "192.168.1.100",
|
||||
"user_agent": "Mozilla/5.0...",
|
||||
"created_at": "2024-01-01T12:00:00.000Z"
|
||||
},
|
||||
...
|
||||
],
|
||||
"limit": 50,
|
||||
"offset": 0
|
||||
}
|
||||
```
|
||||
|
||||
#### Get RBAC Statistics
|
||||
```http
|
||||
GET /api/rbac/stats
|
||||
Authorization: Bearer {token}
|
||||
Required Permission: security.view_audit
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"role_distribution": [
|
||||
{
|
||||
"name": "Administrator",
|
||||
"role_key": "admin",
|
||||
"user_count": 2
|
||||
},
|
||||
...
|
||||
],
|
||||
"recent_actions": [
|
||||
{
|
||||
"action": "role_assigned",
|
||||
"count": 15
|
||||
},
|
||||
...
|
||||
],
|
||||
"total_permissions": 70,
|
||||
"total_roles": 6
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Frontend Integration
|
||||
|
||||
### RBAC Dashboard Component
|
||||
|
||||
**Location:** `frontend/src/components/RBACDashboard.jsx`
|
||||
|
||||
**Route:** `/security/rbac`
|
||||
|
||||
**Access:** Requires `users.manage_roles` or `security.view_audit` permissions
|
||||
|
||||
#### Features
|
||||
|
||||
**Tab 1: Roles & Permissions**
|
||||
- View all system and custom roles
|
||||
- Create custom roles with granular permissions
|
||||
- Edit custom role permissions
|
||||
- Delete custom roles (if not assigned)
|
||||
- Color-coded role chips (admin=red, moderator=orange, user=blue, viewer=cyan)
|
||||
- Permission count badges
|
||||
|
||||
**Tab 2: User Roles**
|
||||
- View all users and their current roles
|
||||
- Change user roles (dropdown selection)
|
||||
- User status indicators (active/inactive)
|
||||
- Prevent self-role modification
|
||||
|
||||
**Tab 3: Audit Log**
|
||||
- Browse permission change history
|
||||
- Filter by action type, user, target type
|
||||
- View change details (old value → new value)
|
||||
- Timestamp and IP tracking
|
||||
|
||||
**Tab 4: Statistics**
|
||||
- Role distribution chart
|
||||
- Recent actions in last 30 days
|
||||
- Total permissions and roles count
|
||||
- User count per role
|
||||
|
||||
**Tab 5: My Permissions**
|
||||
- View your current role and description
|
||||
- List all permissions granted to you
|
||||
- Grouped by category with icons
|
||||
- Permission descriptions
|
||||
|
||||
### Integration in App
|
||||
|
||||
**App.jsx:**
|
||||
```jsx
|
||||
import RBACDashboard from './components/RBACDashboard';
|
||||
|
||||
<Route path="security/rbac" element={<RBACDashboard />} />
|
||||
```
|
||||
|
||||
**SecurityDashboard.jsx:**
|
||||
```jsx
|
||||
<Button
|
||||
onClick={() => navigate('/security/rbac')}
|
||||
startIcon={<AdminPanelSettings />}
|
||||
>
|
||||
{t('security.rbacDashboard')}
|
||||
</Button>
|
||||
```
|
||||
|
||||
### Translations
|
||||
|
||||
**English (`en.json`):**
|
||||
- `security.rbacDashboard`: "RBAC & Permissions"
|
||||
- `rbac.*`: 45+ translation keys for all RBAC features
|
||||
|
||||
**Romanian (`ro.json`):**
|
||||
- `security.rbacDashboard`: "RBAC & Permisiuni"
|
||||
- `rbac.*`: 45+ translation keys (full Romanian translations)
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Defense in Depth
|
||||
|
||||
1. **Multiple Authorization Layers**
|
||||
- JWT authentication (Layer 1)
|
||||
- Session validation (Layer 2)
|
||||
- RBAC permission check (Layer 3)
|
||||
|
||||
2. **Principle of Least Privilege**
|
||||
- Each role has minimum required permissions
|
||||
- Viewer role for read-only access
|
||||
- Granular permissions prevent over-privileged accounts
|
||||
|
||||
3. **System Role Protection**
|
||||
- Cannot delete system roles
|
||||
- Cannot modify system role permissions
|
||||
- Last admin cannot be deleted
|
||||
|
||||
### Attack Mitigation
|
||||
|
||||
**Privilege Escalation Prevention:**
|
||||
- Users cannot modify their own roles
|
||||
- Role changes logged in audit trail
|
||||
- Permission cache invalidated on role changes
|
||||
|
||||
**Audit Trail:**
|
||||
- All permission changes logged with:
|
||||
- Actor (who made the change)
|
||||
- Action (what was done)
|
||||
- Target (what was affected)
|
||||
- Old/new values (what changed)
|
||||
- IP address and User-Agent
|
||||
- Timestamp
|
||||
|
||||
**Input Validation:**
|
||||
- Role keys validated (lowercase, underscores only)
|
||||
- Permission keys validated against whitelist
|
||||
- Array validation for permission lists
|
||||
- SQL injection prevention (parameterized queries)
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
RBAC routes protected by rate limiters:
|
||||
- `readLimiter`: 100 requests per 15 minutes (read operations)
|
||||
- `modifyLimiter`: 30 requests per 15 minutes (write operations)
|
||||
|
||||
---
|
||||
|
||||
## Audit Logging
|
||||
|
||||
### Logged Actions
|
||||
|
||||
1. **`role_created`**
|
||||
- Target: role ID
|
||||
- New Value: role definition
|
||||
|
||||
2. **`role_updated`**
|
||||
- Target: role ID
|
||||
- Old Value: previous role definition
|
||||
- New Value: updated role definition
|
||||
|
||||
3. **`role_deleted`**
|
||||
- Target: role ID
|
||||
- Old Value: deleted role definition
|
||||
|
||||
4. **`role_assigned`**
|
||||
- Target: user ID
|
||||
- Old Value: previous role
|
||||
- New Value: new role
|
||||
|
||||
### Audit Log Metadata
|
||||
|
||||
Each log entry captures:
|
||||
- User ID and username (who)
|
||||
- Action type (what)
|
||||
- Target type and ID (where)
|
||||
- Old and new values (how it changed)
|
||||
- IP address (from where)
|
||||
- User-Agent (with what)
|
||||
- Timestamp (when)
|
||||
|
||||
### Querying Audit Logs
|
||||
|
||||
```javascript
|
||||
// Get all role assignments
|
||||
GET /api/rbac/audit-log?action=role_assigned
|
||||
|
||||
// Get all actions by specific user
|
||||
GET /api/rbac/audit-log?userId=5
|
||||
|
||||
// Get role-related actions
|
||||
GET /api/rbac/audit-log?targetType=role
|
||||
|
||||
// Pagination
|
||||
GET /api/rbac/audit-log?limit=50&offset=100
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### Upgrading from Simple Role System
|
||||
|
||||
**Current System:**
|
||||
- Binary role check: `user.role === 'admin'`
|
||||
- Two roles: admin, user
|
||||
|
||||
**New RBAC System:**
|
||||
- Granular permissions
|
||||
- Four default roles: admin, moderator, user, viewer
|
||||
- Custom role support
|
||||
|
||||
### Migration Steps
|
||||
|
||||
1. **Database Migration (Automatic)**
|
||||
- `roles` table created on first server start
|
||||
- Default roles seeded automatically
|
||||
- Existing user roles preserved
|
||||
|
||||
2. **Update Route Protection**
|
||||
|
||||
**Before:**
|
||||
```javascript
|
||||
router.get('/users', authenticate, requireAdmin, (req, res) => { ... });
|
||||
```
|
||||
|
||||
**After:**
|
||||
```javascript
|
||||
router.get('/users', authenticate, requirePermission('users.view'), (req, res) => { ... });
|
||||
```
|
||||
|
||||
3. **Frontend Permission Checks**
|
||||
|
||||
**Before:**
|
||||
```jsx
|
||||
{user?.role === 'admin' && <AdminPanel />}
|
||||
```
|
||||
|
||||
**After:**
|
||||
```jsx
|
||||
{user?.permissions?.includes('security.view_audit') && <AdminPanel />}
|
||||
```
|
||||
|
||||
### Backward Compatibility
|
||||
|
||||
The system maintains backward compatibility:
|
||||
- `requireAdmin` middleware still works
|
||||
- Existing admin and user roles mapped to RBAC
|
||||
- No breaking changes to existing authentication
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Use Granular Permissions
|
||||
|
||||
❌ **Bad:**
|
||||
```javascript
|
||||
requirePermission('admin') // Too broad
|
||||
```
|
||||
|
||||
✅ **Good:**
|
||||
```javascript
|
||||
requirePermission('users.view') // Specific
|
||||
requirePermission(['playlists.edit', 'channels.edit']) // Multiple specific
|
||||
```
|
||||
|
||||
### 2. Principle of Least Privilege
|
||||
|
||||
When creating custom roles:
|
||||
- Start with minimum permissions
|
||||
- Add permissions as needed
|
||||
- Regularly audit role usage
|
||||
|
||||
**Example: Content Editor Role**
|
||||
```javascript
|
||||
{
|
||||
role_key: 'content_editor',
|
||||
name: 'Content Editor',
|
||||
permissions: [
|
||||
// Only content-related permissions
|
||||
'playlists.view',
|
||||
'playlists.create',
|
||||
'playlists.edit',
|
||||
'channels.view',
|
||||
'channels.edit',
|
||||
'channels.upload_logo',
|
||||
// NO user management
|
||||
// NO system settings
|
||||
// NO backup access
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Regular Permission Audits
|
||||
|
||||
1. **Review role distribution**
|
||||
- Are too many users admin?
|
||||
- Can some admins be moderators?
|
||||
|
||||
2. **Check audit logs**
|
||||
- Monitor role changes
|
||||
- Detect unusual permission grants
|
||||
|
||||
3. **Clean up unused roles**
|
||||
- Delete custom roles no longer needed
|
||||
- Reassign users from deprecated roles
|
||||
|
||||
### 4. Document Custom Roles
|
||||
|
||||
When creating custom roles:
|
||||
```javascript
|
||||
{
|
||||
role_key: 'playlist_manager',
|
||||
name: 'Playlist Manager',
|
||||
description: 'Can manage playlists but not users or settings',
|
||||
// Clear description helps future administrators
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Test Permission Changes
|
||||
|
||||
Before deploying role changes:
|
||||
1. Test in development environment
|
||||
2. Verify access for affected users
|
||||
3. Check audit logs
|
||||
4. Have rollback plan ready
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: "Insufficient permissions" error
|
||||
|
||||
**Cause:** User lacks required permission(s)
|
||||
|
||||
**Solution:**
|
||||
1. Check user's role: `GET /api/rbac/my-permissions`
|
||||
2. Verify required permission for route
|
||||
3. Assign appropriate role or add permission to role
|
||||
|
||||
### Issue: Permission cache not updating
|
||||
|
||||
**Cause:** Cache TTL (5 minutes)
|
||||
|
||||
**Solution:**
|
||||
```javascript
|
||||
// Backend: Force cache clear
|
||||
clearUserPermissionCache(userId);
|
||||
// or
|
||||
clearAllPermissionCache();
|
||||
|
||||
// Frontend: Re-fetch user data
|
||||
const response = await axios.get('/api/rbac/my-permissions');
|
||||
```
|
||||
|
||||
### Issue: Cannot delete custom role
|
||||
|
||||
**Cause:** Role assigned to users
|
||||
|
||||
**Solution:**
|
||||
1. Check role usage: `GET /api/rbac/stats`
|
||||
2. Reassign users to different role
|
||||
3. Then delete custom role
|
||||
|
||||
### Issue: System role modification fails
|
||||
|
||||
**Cause:** System roles protected
|
||||
|
||||
**Solution:**
|
||||
- Cannot modify system roles (admin, moderator, user, viewer)
|
||||
- Create custom role instead
|
||||
- Copy desired permissions from system role
|
||||
|
||||
---
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Permission Caching
|
||||
|
||||
- **Cache Duration:** 5 minutes
|
||||
- **Memory Impact:** ~1KB per cached user
|
||||
- **Hit Rate:** ~95% (typical)
|
||||
|
||||
### Database Queries
|
||||
|
||||
**Optimized:**
|
||||
- Single query for permission check (cached)
|
||||
- Indexed role_key and user_id columns
|
||||
|
||||
**Audit Log:**
|
||||
- Paginated results (default 100)
|
||||
- Indexed created_at for time-range queries
|
||||
|
||||
### Recommendations
|
||||
|
||||
1. **Production:**
|
||||
- Monitor cache hit rate
|
||||
- Adjust TTL if needed (default: 5 min)
|
||||
- Consider Redis for distributed systems
|
||||
|
||||
2. **Large Deployments:**
|
||||
- Archive old audit logs (>90 days)
|
||||
- Partition audit table by date
|
||||
- Consider read replicas for heavy queries
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
The RBAC system provides:
|
||||
✅ **Granular Permissions:** 70+ specific permissions
|
||||
✅ **Principle of Least Privilege:** Four default roles with appropriate access
|
||||
✅ **Custom Roles:** Create application-specific roles
|
||||
✅ **Audit Trail:** Complete permission change history
|
||||
✅ **Admin UI:** Visual role and permission management
|
||||
✅ **Security:** Multiple authorization layers
|
||||
✅ **Performance:** Permission caching
|
||||
✅ **Internationalization:** Full EN/RO translations
|
||||
✅ **Documentation:** Comprehensive guide and examples
|
||||
|
||||
**Next Steps:**
|
||||
1. Review default role permissions
|
||||
2. Create custom roles for your use case
|
||||
3. Monitor audit logs regularly
|
||||
4. Educate users about their permissions
|
||||
5. Conduct regular permission audits
|
||||
|
||||
For questions or issues, refer to the audit logs and this documentation.
|
||||
Loading…
Add table
Add a link
Reference in a new issue