User Roles and Permissions

User Roles & Permissions Guide

This comprehensive guide explains the Role-Based Access Control (RBAC) system implemented in the Flux Gate, including roles, permissions, and access patterns.

🎯 Overview

The Flux Gate implements a sophisticated RBAC system that controls access to different features and actions based on user roles. The system uses JWT tokens to manage authentication and authorization, with roles embedded in the token payload.

🏷️ Available Roles

1. Admin Role

Full system access with all permissions

Capabilities:

• ✅ Complete user management (create, edit, delete users)
• ✅ Team management (create, edit teams)
• ✅ Environment management (all environments)
• ✅ Feature toggle management (all features)
• ✅ Pipeline management (all pipelines)
• ✅ Context management (all contexts)
• ✅ Client management (all clients)
• ✅ Role assignment and management
• ✅ System configuration
• ✅ Request and approve stage changes

Access Control:

• Settings Menu: Full access to all settings
• Teams Menu: Full visibility and management
• Feature Management: All features across all teams
• Deployment Control: Can request and approve deployments

2. Team Admin Role

Team and user management capabilities

Capabilities:

• ✅ User management within team scope
• ✅ Team management (create, edit teams)
• ✅ View team members and roles
• ✅ Assign users to teams
• ✅ Manage team-specific resources
• ⚠️ Limited to team-scoped operations

Access Control:

• Settings → Teams: Visible and accessible
• Settings → Users: Visible and accessible
• Team Features: Can manage features within assigned teams
• User Assignment: Can assign users to their teams

3. Approver Role

Deployment approval and rejection capabilities

Capabilities:

• ✅ Approve deployment requests (DEPLOYMENT_REQUESTED → DEPLOYED)
• ✅ Reject deployment requests (DEPLOYMENT_REQUESTED → DEPLOYMENT_REJECTED)
• ✅ Approve rollback requests (ROLLBACK_REQUESTED → ROLLBACKED)
• ✅ Reject rollback requests (ROLLBACK_REQUESTED → ROLLBACK_REJECTED)
• ✅ View feature status and deployment history
• ❌ Cannot initiate deployment requests

Workflow Actions:

• Deployment Approval: Review and approve deployment requests
• Deployment Rejection: Reject inappropriate deployment requests
• Rollback Approval: Approve rollback requests when issues occur
• Rollback Rejection: Reject unnecessary rollback requests

4. Requester Role

Deployment and rollback request capabilities

Capabilities:

• ✅ Request deployment (NOT_DEPLOYED → DEPLOYMENT_REQUESTED)
• ✅ Request rollback (DEPLOYED → ROLLBACK_REQUESTED)
• ✅ View feature status and deployment pipeline
• ❌ Cannot approve or reject requests

Workflow Actions:

• Request Deployment: Initiate deployment requests for features
• Request Rollback: Request rollback when issues are detected
• Status Monitoring: Monitor deployment status and pipeline progress

🔐 Admin Flag System

Admin Flag (is_admin)

In addition to role-based permissions, the system includes an is_admin boolean flag in JWT tokens:

Properties:

• JWT Field: is_admin: boolean
• Purpose: Grants admin-level access regardless of assigned roles
• Priority: Takes precedence over role-based permissions
• Fallback: Provides admin access even without explicit Admin role

Usage Example:

{
  "sub": "user123",
  "username": "john.doe", 
  "roles": ["Requester"],
  "is_admin": true,
  "exp": 1672531200,
  "iat": 1672444800
}

In this example, even though the user only has "Requester" role, the is_admin: true flag grants full admin access.

🔄 Stage Change Workflow

The system implements a structured approval workflow for feature deployments:

Request Phase (Requester Role Required)

1. Initiate Request: User with Requester role submits deployment/rollback request
2. Status Change: Stage status changes to DEPLOYMENT_REQUESTED or ROLLBACK_REQUESTED
3. Notification: Request appears in approver queues

Approval Phase (Approver Role Required)

1. Review Request: Approver reviews the deployment request
2. Decision: Approver chooses to approve or reject
3. Status Change: Stage status changes to final state (DEPLOYED, ROLLBACKED, etc.)
4. Notification: Requester notified of decision

Status Flow Diagram

NOT_DEPLOYED ──[Requester]──→ DEPLOYMENT_REQUESTED
     ↑                              ↓
     │                         [Approver]
     │                              ↓
     └────── DEPLOYMENT_REJECTED ←──┴──→ DEPLOYED
                                         │
                                    [Requester]
                                         ↓
                                  ROLLBACK_REQUESTED
                                         ↓
                                    [Approver]
                                         ↓
                              ROLLBACK_REJECTED ←──→ ROLLBACKED

🎛️ Permission Matrix

Feature Access Control

Action	Admin	Team Admin	Approver	Requester
Create Features	✅	✅ (Team)	❌	❌
Edit Features	✅	✅ (Team)	❌	❌
View Features	✅	✅ (Team)	✅ (Team)	✅ (Team)
Delete Features	✅	✅ (Team)	❌	❌

Deployment Control

Action	Admin	Team Admin	Approver	Requester
Request Deployment	✅	✅	❌	✅
Approve Deployment	✅	❌	✅	❌
Request Rollback	✅	✅	❌	✅
Approve Rollback	✅	❌	✅	❌

Administrative Functions

Function	Admin	Team Admin	Approver	Requester
User Management	✅	✅	❌	❌
Team Management	✅	✅	❌	❌
Environment Management	✅	❌	❌	❌
System Configuration	✅	❌	❌	❌

🔍 Role Checking Implementation

Frontend Role Checking

The system provides utilities for checking user permissions:

Using the Auth Hook

import { useAuth } from '@/hooks/useAuth';

const MyComponent = () => {
  const { 
    canRequestStageChange,
    canApproveStageChange, 
    canAccessTeamsManagement,
    isAdmin
  } = useAuth();

  return (
    <div>
      {canRequestStageChange && (
        <button>Request Deployment</button>
      )}
      {canApproveStageChange && (
        <button>Approve Request</button>
      )}
      {isAdmin && (
        <button>Admin Panel</button>
      )}
    </div>
  );
};

Manual Role Checking

import { hasRole, ROLES, getCurrentUser } from '@/utils/auth';

// Check specific role
if (hasRole(ROLES.REQUESTER)) {
  console.log('User can request stage changes');
}

// Check admin status (role OR flag)
if (hasRole(ROLES.ADMIN) || isAdmin()) {
  console.log('User has admin access');
}

// Get complete user info
const user = getCurrentUser();
console.log('User roles:', user?.roles);

🔐 JWT Token Structure

Standard JWT Payload

{
  "sub": "user123",
  "username": "john.doe",
  "roles": ["Team Admin", "Requester"],
  "is_admin": false,
  "exp": 1672531200,
  "iat": 1672444800
}

Admin User Example

{
  "sub": "admin123",
  "username": "admin.user", 
  "roles": ["Admin"],
  "is_admin": true,
  "exp": 1672531200,
  "iat": 1672444800
}

🎨 UI Role Indicators

The system provides visual indicators for user roles:

Header Role Display

• 🔴 Admin (red indicator)
• 🔵 Approver (blue indicator)
• 🟢 Requester (green indicator)
• 🟣 Team Admin (purple indicator)

Permission Hints

When users lack permissions, the UI shows helpful messages:

• "Requester role required to make requests"
• "Approver role required to review requests"
• "Team Admin privileges needed to access this page"

🚨 Security Considerations

Client-Side vs Server-Side

⚠️ Important: The role checking described here is client-side only and provides UI-level access control.

Security Requirements:

1. Server Validation: All role checks must be validated on the backend
2. JWT Verification: Server must verify JWT tokens and roles
3. API Protection: All API endpoints must implement proper authorization
4. Token Security: Use secure token storage and transmission

Best Practices

1. Principle of Least Privilege: Assign minimum necessary roles
2. Role Auditing: Regularly review user role assignments
3. Token Expiration: Implement reasonable token expiration times
4. Secure Storage: Store JWT tokens securely (localStorage with proper domain restrictions)

🔧 Role Management

Assigning Roles

Roles are assigned through the user management interface:

1. Edit User: Access user editing mode
2. Roles Tab: Navigate to roles section
3. Select Roles: Choose appropriate roles
4. Multiple Roles: Users can have multiple roles
5. Save Changes: Apply role assignments

Role Combinations

Common role combinations:

Combination	Use Case
Requester + Approver	Developer who can request and approve own work
Team Admin + Approver	Team lead with approval authority
Admin	System administrator (has all permissions)

🔗 Related Documentation

• User Management - Creating and managing users
• Team Management - Team organization and management
• Stage Approval Workflow - Detailed workflow documentation
• Authentication & Login - Login and session management

---

Need help? Check the Troubleshooting guide or create an issue in the project repository.