5-Tier RBAC System

Date: 2025-11-15
Status: ✅ Complete

📋 Overview

TelemetryFlow implements a 5-tier Role-Based Access Control (RBAC) system with hierarchical permissions and organizational scoping. This document provides comprehensive visualization and comparison of all roles, permissions, and access patterns.

🎯 Role Hierarchy

Visual Hierarchy

graph TD
    A[Tier 1: Super Administrator] --> B[Tier 2: Administrator]
    B --> C[Tier 3: Developer]
    C --> D[Tier 4: Viewer]
    C --> E[Tier 5: Demo]

    A1[Global Scope<br/>All Organizations<br/>All Regions] -.-> A
    B1[Organization Scope<br/>Single Organization<br/>Multiple Regions] -.-> B
    C1[Organization Scope<br/>Single Organization] -.-> C
    D1[Organization Scope<br/>Read-Only] -.-> D
    E1[Demo Org Only<br/>Auto-cleanup 6h] -.-> E

    style A fill:#ff6b6b,stroke:#c92a2a,stroke-width:3px,color:#fff
    style B fill:#fa5252,stroke:#e03131,stroke-width:2px,color:#fff
    style C fill:#ffd43b,stroke:#fab005,stroke-width:2px,color:#000
    style D fill:#51cf66,stroke:#37b24d,stroke-width:2px,color:#fff
    style E fill:#74c0fc,stroke:#339af0,stroke-width:2px,color:#fff

🔐 Role Details

mindmap
  root((5-Tier RBAC))
    Super Admin
      Global Scope
      Platform Management
      All Permissions
      System Admin
    Administrator
      Organization Scope
      Full CRUD
      User Management
      No Platform Access
    Developer
      Organization Scope
      Create/Read/Update
      No Delete
      No User Management
    Viewer
      Organization Scope
      Read-Only
      No Modifications
      Audit Access
    Demo
      Demo Org Only
      Developer Access
      Auto-Cleanup
      Isolated Data

Tier 1: Super Administrator

Attribute	Details
Scope	Global (all organizations, regions, workspaces, tenants)
Description	Can manage all the SaaS Platform across all organizations and regions
Permission Count	60+
Key Permissions	• Platform management • All IAM operations • System administration • Audit log access
Use Cases	• Platform administrators • DevOps team managing infrastructure • System maintenance
Restrictions	None

Tier 2: Administrator

Attribute	Details
Scope	Organization-scoped (single organization, multiple regions)
Description	Can manage all permissions within their organization across multiple regions
Permission Count	55+
Key Permissions	• Organization read/update • Full user management (CRUD) • Full role management (CRUD) • Full tenant/workspace management • Audit log read/export
Use Cases	• Organization administrators • Team leads • Department managers
Restrictions	• No platform management • No system administration • Cannot create/delete organizations

Tier 3: Developer

Attribute	Details
Scope	Organization-scoped (single organization)
Description	Can create and update resources within their organization, but cannot delete
Permission Count	40+
Key Permissions	• User create/read/update • Tenant/workspace create/read/update • Dashboard/alert create/read/update • Agent management • Audit log read-only
Use Cases	• Software developers • DevOps engineers • QA engineers
Restrictions	• No delete operations • No user/role management • No export operations • Read-only for roles/permissions

Tier 4: Viewer

Attribute	Details
Scope	Organization-scoped (single organization)
Description	Read-only access to resources within their organization
Permission Count	17
Key Permissions	• All resources read-only • Audit log read-only • Uptime check access
Use Cases	• Business analysts • Stakeholders • External auditors • Read-only monitoring
Restrictions	• No write operations • No create/update/delete operations

Tier 5: Demo

Attribute	Details
Scope	Demo Organization ONLY (org-demo, ws-demo, tn-demo)
Description	Developer access limited to Demo Organization, Demo Workspace, and Demo Tenant only
Permission Count	40+ (same as Developer)
Key Permissions	• All Developer permissions • User create/read/update • Dashboard/alert create/read/update • Agent management
Use Cases	• Product demonstrations • Trial accounts • Training environments • Customer evaluations
Restrictions	• Limited to Demo Organization only • Cannot access production data • Data auto-deleted every 6 hours • No delete operations

📋 IAM Permissions List

User Management

iam:users:read - View users
iam:users:create - Create users
iam:users:update - Update users
iam:users:delete - Delete users

Role Management

iam:roles:read - View roles
iam:roles:create - Create roles
iam:roles:update - Update roles
iam:roles:delete - Delete roles

Permission Management

iam:permissions:read - View permissions

Organization Management

iam:organizations:read - View organizations
iam:organizations:create - Create organizations
iam:organizations:update - Update organizations
iam:organizations:delete - Delete organizations

Tenant Management

iam:tenants:read - View tenants
iam:tenants:create - Create tenants
iam:tenants:update - Update tenants
iam:tenants:delete - Delete tenants

Workspace Management

iam:workspaces:read - View workspaces
iam:workspaces:create - Create workspaces
iam:workspaces:update - Update workspaces
iam:workspaces:delete - Delete workspaces

Region Management

iam:regions:read - View regions
iam:regions:create - Create regions
iam:regions:update - Update regions
iam:regions:delete - Delete regions

Group Management

iam:groups:read - View groups
iam:groups:create - Create groups
iam:groups:update - Update groups
iam:groups:delete - Delete groups

Platform & System

platform:manage - Platform management (Super Admin only)
system:admin - System administration (Super Admin only)

📊 Permission Comparison Matrix

Quick Reference

Permission Category	Super Admin	Administrator	Developer	Viewer	Demo
Scope	🌍 Global	🏢 Organization	🏢 Organization	🏢 Organization	🎭 Demo Org
Permission Count	60+	55+	40+	17	40+
Platform Management	✅	❌	❌	❌	❌
System Admin	✅	❌	❌	❌	❌
Delete Operations	✅	✅	❌	❌	❌
Data Retention	♾️ Permanent	♾️ Permanent	♾️ Permanent	♾️ Permanent	⏱️ 6 hours

Detailed Permissions

Resource	Super Admin	Administrator	Developer	Viewer	Demo
Organizations	🔴 CRUD	🟡 R/U	🟢 R	🟢 R	🟢 R
Users	🔴 CRUD	🔴 CRUD	🟡 CRU	🟢 R	🟡 CRU
Roles	🔴 CRUD	🔴 CRUD	🟢 R	🟢 R	🟢 R
Permissions	🔴 CRUD	🟢 R	🟢 R	🟢 R	🟢 R
Tenants	🔴 CRUD	🔴 CRUD	🟡 CRU	🟢 R	🟡 CRU
Workspaces	🔴 CRUD	🔴 CRUD	🟡 CRU	🟢 R	🟡 CRU
Regions	🔴 CRUD	🟢 R	🟢 R	🟢 R	🟢 R
Groups	🔴 CRUD	🔴 CRUD	🟡 CRU	🟢 R	🟡 CRU
Audit Logs	🔴 R/Export	🔴 R/Export	🟢 R	🟢 R	🟢 R

Legend:

🔴 CRUD = Create, Read, Update, Delete (Full Access)
🟡 CRU = Create, Read, Update (No Delete)
🟡 R/U = Read, Update (No Create/Delete)
🟢 R = Read Only
🔴 R/Export = Read + Export capabilities

🔄 Role Assignment

Default Users

User	Email	Password	Role	Organization	Tenant
Super Administrator	superadmin.telemetryflow@telemetryflow.id	SuperAdmin@123456	super_administrator	All	All
Administrator TelemetryFlow	administrator.telemetryflow@telemetryflow.id	Admin@123456	administrator	TelemetryFlow	TelemetryFlow
Developer TelemetryFlow	developer.telemetryflow@telemetryflow.id	Developer@123456	developer	TelemetryFlow	TelemetryFlow
Viewer TelemetryFlow	viewer.telemetryflow@telemetryflow.id	Viewer@123456	viewer	TelemetryFlow	TelemetryFlow
Demo TelemetryFlow	demo.telemetryflow@telemetryflow.id	Demo@123456	demo	Demo Org	Demo Tenant

🛡️ Security Features

graph LR
    A[Request] --> B{Authentication}
    B -->|Valid JWT| C{Authorization}
    B -->|Invalid| X[401 Unauthorized]

    C --> D{Role Check}
    D -->|Has Role| E{Permission Check}
    D -->|No Role| Y[403 Forbidden]

    E -->|Has Permission| F{Scope Check}
    E -->|No Permission| Y

    F -->|Organization Match| G{Tenant Filter}
    F -->|No Match| Y

    G -->|Allowed| H[Execute Query]
    G -->|Denied| Y

    H --> I[Audit Log]
    I --> J[Response]

    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#fff3e0
    style D fill:#f3e5f5
    style E fill:#f3e5f5
    style F fill:#e8f5e9
    style G fill:#e8f5e9
    style H fill:#e1f5fe
    style I fill:#fce4ec
    style J fill:#e8f5e9
    style X fill:#ffebee
    style Y fill:#ffebee

Multi-Tenancy Isolation

Feature	Description	Implementation
Organization-level	Data isolated by organization	Query filters: `WHERE organizationId = :orgId`
Tenant-level	Query filtering per tenant	Automatic tenant scoping in repositories
Workspace-level	Resource scoping per workspace	Workspace-based access control
Demo isolation	Complete separation from production	Separate organization with auto-cleanup

Demo Environment Protection

Feature	Description	Status
Auto-cleanup	Data deleted every 6 hours	✅ Implemented
Production isolation	Cannot access production orgs	✅ Enforced
Workspace isolation	Cannot access production workspaces	✅ Enforced
Tenant isolation	Cannot access production tenants	✅ Enforced
Separate domain	`demo.telemetryflow.id`	✅ Configured

Permission Enforcement

Layer	Mechanism	Description
Authentication	JWT tokens	Validates user identity
Authorization	`@RequirePermissions()` decorator	Checks user permissions before execution
Scoping	Query filters	Automatically filters by organization/tenant
Audit	ClickHouse audit_logs	Logs all actions with user context
Validation	Guards & Interceptors	Validates request data and permissions

📝 Implementation Notes

flowchart TB
    subgraph Database["Database Layer"]
        PG[("PostgreSQL IAM Data")]
        CH[("ClickHouse Audit Logs")]
    end

    subgraph Seeds["Seed Data"]
        S1["1. IAM Roles & Permissions"]
        S2["2. Auth Test Users"]
        S3["3. Groups"]
    end

    subgraph Application["Application Layer"]
        G1["Guards RequirePermissions"]
        D1["Decorators CurrentUser"]
        R1["Repositories Auto-scoping"]
    end

    Seeds --> PG
    PG --> Application
    Application --> CH

    S1 --> S2
    S2 --> S3

    style PG fill:#4dabf7
    style CH fill:#ffd43b
    style S1 fill:#51cf66
    style S2 fill:#51cf66
    style S3 fill:#51cf66
    style G1 fill:#ff6b6b
    style D1 fill:#ff6b6b
    style R1 fill:#ff6b6b

Database Structure

Database	Purpose	Tables
PostgreSQL	IAM data storage	users, roles, permissions, role_permissions, user_roles, organizations, tenants, workspaces, regions, groups
ClickHouse	Audit log storage	audit_logs, audit_logs_stats, audit_logs_user_activity

Seed Files

Order	File	Purpose	Records
1	`1704240000001-seed-iam-roles-permissions.ts`	Create 5 roles with explicit permissions	5 roles, 22+ permissions
2	`1704240000002-seed-auth-test-users.ts`	Create test users for each role	5 users
3	`1704240000003-seed-groups.ts`	Create user groups	4 groups

Permission Enforcement

Component	Location	Purpose
Guards	`@RequirePermissions()` decorator	Checks user permissions before controller execution
Decorators	`@CurrentUser()`	Extracts authenticated user from request
Repositories	Auto-scoping queries	Automatically filters by organization/tenant
Audit	ClickHouse service	Logs all actions to audit_logs table

Multi-Tenancy Implementation

Level	Implementation	Example
Organization	Query filter	`WHERE organizationId = :orgId`
Tenant	Repository scoping	`findByTenant(tenantId)`
Workspace	Resource filtering	`WHERE workspaceId = :wsId`
Demo	Separate organization	`organizationId = 'org-demo'`

🚀 Usage

Login Credentials

# Super Administrator
Email: superadmin.telemetryflow@telemetryflow.id
Password: SuperAdmin@123456

# Administrator
Email: administrator.telemetryflow@telemetryflow.id
Password: Admin@123456

# Developer
Email: developer.telemetryflow@telemetryflow.id
Password: Developer@123456

# Viewer
Email: viewer.telemetryflow@telemetryflow.id
Password: Viewer@123456

# Demo
Email: demo.telemetryflow@telemetryflow.id
Password: Demo@123456

API Access

All users can access the API at: http://localhost:3000/api

Use Swagger UI to test different permission levels and see which endpoints are accessible for each role.

Testing Permissions

Login with different roles to see permission differences
Try CRUD operations to verify access control
Check Swagger UI for available endpoints per role
Review audit logs to track all actions

Seeding RBAC System

The 5-tier RBAC system is automatically seeded when running:

# Seed IAM data only
pnpm db:seed:iam

# Seed all data (PostgreSQL + ClickHouse)
pnpm db:seed

# Run migrations + seeds
pnpm db:migrate:seed

# Full bootstrap (dependencies, Docker, migrations, seeds)
bash scripts/bootstrap.sh --dev

🎯 Best Practices

Principle of Least Privilege: Assign minimum required permissions
Role Separation: Use appropriate role for each user type
Demo Isolation: Keep demo users in demo organization only
Regular Audits: Review role assignments periodically
Password Security: Enforce strong passwords (12+ chars, uppercase, special char)
MFA Enforcement: Enable MFA for Super Admin and Administrator roles

📚 Related Documentation

Last Updated: 2025-12-05
Status: ✅ 5-Tier RBAC System Complete

FilesExpand file tree

5_TIER_RBAC_SYSTEM_CORE.md

Latest commit

History

5_TIER_RBAC_SYSTEM_CORE.md

File metadata and controls

5-Tier RBAC System

📋 Overview

🎯 Role Hierarchy

Visual Hierarchy

🔐 Role Details

Tier 1: Super Administrator

Tier 2: Administrator

Tier 3: Developer

Tier 4: Viewer

Tier 5: Demo

📋 IAM Permissions List

User Management

Role Management

Permission Management

Organization Management

Tenant Management

Workspace Management

Region Management

Group Management

Platform & System

📊 Permission Comparison Matrix

Quick Reference

Detailed Permissions

🔄 Role Assignment

Default Users

🛡️ Security Features

Multi-Tenancy Isolation

Demo Environment Protection

Permission Enforcement

📝 Implementation Notes

Database Structure

Seed Files

Permission Enforcement

Multi-Tenancy Implementation

🚀 Usage

Login Credentials

API Access

Testing Permissions

Seeding RBAC System

🎯 Best Practices

📚 Related Documentation