262 lines
9.0 KiB
Markdown
262 lines
9.0 KiB
Markdown
# c77_rbac Usage Guide - Part 1: Core Concepts and Basic Usage
|
|
|
|
This is Part 1 of the comprehensive c77_rbac usage guide. This part covers the fundamental concepts and basic usage patterns.
|
|
|
|
**Complete Guide Structure:**
|
|
- **Part 1: Core Concepts and Basic Usage** (this document)
|
|
- Part 2: Advanced Usage Scenarios and Time-Based Permissions
|
|
- Part 3: Framework Integration (Laravel, Django, Rails)
|
|
- Part 4: Real-World Examples and Performance Optimization
|
|
- Part 5: Security Best Practices and Troubleshooting
|
|
|
|
## Table of Contents
|
|
|
|
1. [Understanding c77_rbac Concepts](#understanding-c77_rbac-concepts)
|
|
2. [Basic Usage Patterns](#basic-usage-patterns)
|
|
|
|
## Understanding c77_rbac Concepts
|
|
|
|
### What is Database-Level Authorization?
|
|
|
|
Traditional application authorization happens in your code:
|
|
|
|
```php
|
|
// Traditional approach - authorization in application
|
|
if ($user->role === 'admin' || $user->department === $post->department) {
|
|
return Post::all(); // Returns ALL posts, then filters in PHP
|
|
}
|
|
```
|
|
|
|
With c77_rbac, authorization happens at the database level:
|
|
|
|
```php
|
|
// c77_rbac approach - authorization in database
|
|
return Post::all(); // Database automatically returns only allowed posts
|
|
```
|
|
|
|
### Core Architecture
|
|
|
|
```
|
|
Application User (external_id: '123')
|
|
↓
|
|
Subject (database record linking external_id to internal ID)
|
|
↓
|
|
Subject_Roles (user has roles with specific scopes)
|
|
↓
|
|
Role_Features (roles have specific permissions/features)
|
|
↓
|
|
RLS Policies (database automatically filters data)
|
|
```
|
|
|
|
### Key Components Explained
|
|
|
|
#### 1. Subjects (Users)
|
|
```sql
|
|
-- Subjects link your application users to RBAC
|
|
INSERT INTO c77_rbac_subjects (external_id) VALUES ('user_123');
|
|
|
|
-- External ID should match your application's user identifier
|
|
-- Usually: Laravel User ID, Django user.id, Rails user.id, etc.
|
|
```
|
|
|
|
#### 2. Roles
|
|
```sql
|
|
-- Roles are named collections of permissions
|
|
-- Examples: 'admin', 'manager', 'employee', 'customer', 'guest'
|
|
|
|
-- Roles get meaning through the features they're granted
|
|
SELECT public.c77_rbac_grant_feature('manager', 'approve_requests');
|
|
SELECT public.c77_rbac_grant_feature('manager', 'view_team_reports');
|
|
```
|
|
|
|
#### 3. Features (Permissions)
|
|
```sql
|
|
-- Features are specific permissions that can be checked
|
|
-- Good naming convention: action_object
|
|
-- Examples:
|
|
SELECT public.c77_rbac_grant_feature('editor', 'view_posts');
|
|
SELECT public.c77_rbac_grant_feature('editor', 'create_posts');
|
|
SELECT public.c77_rbac_grant_feature('editor', 'edit_posts');
|
|
SELECT public.c77_rbac_grant_feature('moderator', 'delete_posts');
|
|
SELECT public.c77_rbac_grant_feature('admin', 'manage_users');
|
|
```
|
|
|
|
#### 4. Scopes (Context)
|
|
```sql
|
|
-- Scopes define WHERE a role applies
|
|
-- Format: scope_type/scope_id
|
|
|
|
-- Examples:
|
|
'global/all' -- Global access to everything
|
|
'department/engineering' -- Only engineering department
|
|
'region/north_america' -- Only North America region
|
|
'project/apollo_mission' -- Only Apollo project
|
|
'customer/enterprise_client' -- Only enterprise client data
|
|
'tenant/company_abc' -- Multi-tenant: only company ABC
|
|
```
|
|
|
|
#### 5. Row-Level Security Policies
|
|
```sql
|
|
-- Policies automatically filter database queries
|
|
-- Applied to tables to enforce permissions
|
|
|
|
-- Example: Users can only see posts in their department
|
|
SELECT public.c77_rbac_apply_policy(
|
|
'posts', -- table name
|
|
'view_posts', -- required feature
|
|
'department', -- scope type
|
|
'department_id' -- column containing department ID
|
|
);
|
|
```
|
|
|
|
## Basic Usage Patterns
|
|
|
|
### Pattern 1: Simple Role-Based Access
|
|
|
|
Perfect for basic applications with clear role hierarchies.
|
|
|
|
```sql
|
|
-- Step 1: Define roles and their capabilities
|
|
SELECT public.c77_rbac_grant_feature('admin', 'manage_users');
|
|
SELECT public.c77_rbac_grant_feature('admin', 'view_all_data');
|
|
SELECT public.c77_rbac_grant_feature('admin', 'edit_all_data');
|
|
|
|
SELECT public.c77_rbac_grant_feature('manager', 'view_reports');
|
|
SELECT public.c77_rbac_grant_feature('manager', 'approve_requests');
|
|
|
|
SELECT public.c77_rbac_grant_feature('employee', 'view_own_data');
|
|
SELECT public.c77_rbac_grant_feature('employee', 'submit_requests');
|
|
|
|
-- Step 2: Assign users to roles
|
|
SELECT public.c77_rbac_assign_subject('1', 'admin', 'global', 'all');
|
|
SELECT public.c77_rbac_assign_subject('101', 'manager', 'global', 'all');
|
|
SELECT public.c77_rbac_assign_subject('201', 'employee', 'global', 'all');
|
|
|
|
-- Step 3: Apply policies to tables
|
|
SELECT public.c77_rbac_apply_policy(
|
|
'user_profiles', 'view_own_data', 'user', 'user_id'
|
|
);
|
|
|
|
-- Step 4: Use in your application
|
|
-- Set user context
|
|
SET "c77_rbac.external_id" TO '201';
|
|
|
|
-- Query automatically filtered
|
|
SELECT * FROM user_profiles; -- Only returns data for user 201
|
|
```
|
|
|
|
### Pattern 2: Department-Based Access
|
|
|
|
Common in organizations with department isolation.
|
|
|
|
```sql
|
|
-- Step 1: Create department-specific roles
|
|
SELECT public.c77_rbac_grant_feature('dept_admin', 'manage_dept_users');
|
|
SELECT public.c77_rbac_grant_feature('dept_admin', 'view_dept_data');
|
|
SELECT public.c77_rbac_grant_feature('dept_admin', 'edit_dept_data');
|
|
|
|
SELECT public.c77_rbac_grant_feature('dept_member', 'view_dept_data');
|
|
SELECT public.c77_rbac_grant_feature('dept_member', 'create_requests');
|
|
|
|
-- Step 2: Assign users to departments
|
|
SELECT public.c77_rbac_assign_subject('101', 'dept_admin', 'department', 'engineering');
|
|
SELECT public.c77_rbac_assign_subject('102', 'dept_member', 'department', 'engineering');
|
|
SELECT public.c77_rbac_assign_subject('201', 'dept_admin', 'department', 'marketing');
|
|
|
|
-- Step 3: Apply department-based policies
|
|
SELECT public.c77_rbac_apply_policy(
|
|
'projects', 'view_dept_data', 'department', 'owning_department'
|
|
);
|
|
|
|
SELECT public.c77_rbac_apply_policy(
|
|
'expenses', 'view_dept_data', 'department', 'department_code'
|
|
);
|
|
|
|
-- Step 4: Test department isolation
|
|
SET "c77_rbac.external_id" TO '102'; -- Engineering member
|
|
SELECT * FROM projects; -- Only engineering projects
|
|
SELECT * FROM expenses; -- Only engineering expenses
|
|
```
|
|
|
|
### Pattern 3: Multi-Tenant Applications
|
|
|
|
Perfect for SaaS applications serving multiple clients.
|
|
|
|
```sql
|
|
-- Step 1: Define tenant-scoped roles
|
|
SELECT public.c77_rbac_grant_feature('tenant_admin', 'manage_tenant_users');
|
|
SELECT public.c77_rbac_grant_feature('tenant_admin', 'view_tenant_data');
|
|
SELECT public.c77_rbac_grant_feature('tenant_admin', 'configure_tenant');
|
|
|
|
SELECT public.c77_rbac_grant_feature('tenant_user', 'view_tenant_data');
|
|
SELECT public.c77_rbac_grant_feature('tenant_user', 'edit_own_data');
|
|
|
|
-- Step 2: Assign users to tenants
|
|
SELECT public.c77_rbac_assign_subject('1001', 'tenant_admin', 'tenant', 'company_a');
|
|
SELECT public.c77_rbac_assign_subject('1002', 'tenant_user', 'tenant', 'company_a');
|
|
SELECT public.c77_rbac_assign_subject('2001', 'tenant_admin', 'tenant', 'company_b');
|
|
|
|
-- Step 3: Apply tenant isolation policies
|
|
SELECT public.c77_rbac_apply_policy(
|
|
'accounts', 'view_tenant_data', 'tenant', 'tenant_id'
|
|
);
|
|
|
|
SELECT public.c77_rbac_apply_policy(
|
|
'invoices', 'view_tenant_data', 'tenant', 'tenant_id'
|
|
);
|
|
|
|
SELECT public.c77_rbac_apply_policy(
|
|
'users', 'view_tenant_data', 'tenant', 'tenant_id'
|
|
);
|
|
|
|
-- Step 4: Perfect tenant isolation
|
|
SET "c77_rbac.external_id" TO '1002'; -- Company A user
|
|
SELECT * FROM accounts; -- Only Company A accounts
|
|
SELECT * FROM invoices; -- Only Company A invoices
|
|
```
|
|
|
|
### Pattern 4: Hierarchical Organizations
|
|
|
|
For complex organizational structures with multiple levels.
|
|
|
|
```sql
|
|
-- Step 1: Define hierarchical roles
|
|
-- Global level
|
|
SELECT public.c77_rbac_grant_feature('global_admin', 'manage_everything');
|
|
SELECT public.c77_rbac_grant_feature('global_admin', 'view_all_regions');
|
|
|
|
-- Regional level
|
|
SELECT public.c77_rbac_grant_feature('regional_manager', 'manage_region');
|
|
SELECT public.c77_rbac_grant_feature('regional_manager', 'view_region_data');
|
|
|
|
-- Branch level
|
|
SELECT public.c77_rbac_grant_feature('branch_manager', 'manage_branch');
|
|
SELECT public.c77_rbac_grant_feature('branch_manager', 'view_branch_data');
|
|
|
|
-- Store level
|
|
SELECT public.c77_rbac_grant_feature('store_manager', 'manage_store');
|
|
SELECT public.c77_rbac_grant_feature('store_manager', 'view_store_data');
|
|
|
|
-- Step 2: Assign users to hierarchy levels
|
|
SELECT public.c77_rbac_assign_subject('1', 'global_admin', 'global', 'all');
|
|
SELECT public.c77_rbac_assign_subject('101', 'regional_manager', 'region', 'west_coast');
|
|
SELECT public.c77_rbac_assign_subject('201', 'branch_manager', 'branch', 'west_coast_sf');
|
|
SELECT public.c77_rbac_assign_subject('301', 'store_manager', 'store', 'sf_downtown');
|
|
|
|
-- Step 3: Apply hierarchical policies
|
|
SELECT public.c77_rbac_apply_policy(
|
|
'sales_data', 'view_store_data', 'store', 'store_code'
|
|
);
|
|
|
|
SELECT public.c77_rbac_apply_policy(
|
|
'inventory', 'view_branch_data', 'branch', 'branch_code'
|
|
);
|
|
|
|
-- Step 4: Each level sees appropriate data
|
|
SET "c77_rbac.external_id" TO '301'; -- Store manager
|
|
SELECT * FROM sales_data; -- Only their store's data
|
|
```
|
|
|
|
---
|
|
|
|
**Continue to [Part 2: Advanced Usage Scenarios](USAGE-Part2.md)** for time-based permissions, conditional permissions, dynamic role assignment, and bulk operations. |