Skip to content

Roles & Permissions

Comprehensive guide to managing roles and permissions in Champa Intelligence.

Overview

The Role-Based Access Control (RBAC) system provides granular control over feature access. Administrators can create custom roles with specific permission sets tailored to organizational needs.

Required Permission: manage_roles

Navigation: Admin → Roles & Permissions

Understanding RBAC

Concepts

Role: A named collection of permissions representing a job function (e.g., "Process Analyst", "Operations Manager")

Permission: A specific right to access a feature or perform an action (e.g., portfolio_data, manage_users)

User Assignment: Each user is assigned to exactly one role, which determines their access rights

System Roles

Four pre-configured roles that cannot be deleted or renamed:

Administrator

Description: Complete system access with all privileges

Permissions: - full_access - Unrestricted access to all features

Use Cases: - Platform administrators - System configuration - User and role management - Security administration

Process Analyst

Description: Strategic and analytical access for business process experts

Permissions: - portfolio_data - Portfolio Dashboard - extended_dashboard_data - Process Intelligence Dashboard - ai_analysis_data - AI-Powered Analysis - journey_analysis_data - Journey Monitoring - bpmn_analysis_data - BPMN Analytics Viewer - dmn_analysis_data - DMN Analytics

Use Cases: - Business process analysts - Process improvement teams - Management reporting - Strategic planning

Process Operator

Description: Technical and operational access for day-to-day process management

Permissions: - health_monitor_data - Health Monitoring - diff_tool_data - BPMN Diff Tool - model_validation_data - Model Validator (Linter)

Use Cases: - Operations teams - Technical support - DevOps engineers - Process maintenance

Viewer

Description: Read-only access for monitoring and validation

Permissions: - health_monitor_data - Health Monitoring - model_validation_data - Model Validator (Linter)

Use Cases: - Stakeholders - Audit teams - Read-only monitoring - Compliance verification

Custom Roles

Creating a Custom Role

  1. Navigate to Admin → Roles & Permissions
  2. Click "Create New Role"
  3. Fill in the form:
Field Required Description
Name Yes Internal role identifier (lowercase, underscores)
Display Name Yes Human-readable name shown in UI
Description No Role purpose and intended users
Permissions Yes Select at least one permission
  1. Click "Create Role"

Example:

Name: operations_manager
Display Name: Operations Manager
Description: Manages operations with analytical oversight
Permissions:
  ✓ portfolio_data
  ✓ extended_dashboard_data
  ✓ health_monitor_data
  ✓ journey_analysis_data

Editing a Custom Role

  1. Find role in the list
  2. Click "Edit" button
  3. Modify display name, description, or permissions
  4. Click "Save Changes"

Note: Role name (internal identifier) cannot be changed after creation.

Deleting a Custom Role

Prerequisites: - No users assigned to the role - Role is not a system role

Steps:

  1. Find role in the list
  2. Verify user count is 0
  3. Click "Delete" button
  4. Confirm deletion

⚠️ Warning: Deletion is permanent and cannot be undone.

Permission Reference

Administrative Permissions

Permission Description Typical Roles
full_access Unrestricted system access Administrator
manage_users Create, edit, delete users Administrator
manage_roles Manage roles and permissions Administrator

Feature Permissions

Permission Feature Description
portfolio_data Portfolio Dashboard Executive-level KPIs and trends
extended_dashboard_data Process Intelligence Detailed process analytics
ai_analysis_data AI Analysis AI-powered insights
health_monitor_data Health Monitoring Cluster health and metrics
journey_analysis_data Journey Monitoring End-to-end journey tracking
diff_tool_data BPMN Diff Tool Version comparison
model_validation_data Model Validator BPMN/DMN quality checks
bpmn_analysis_data BPMN Analytics Process model analytics
dmn_analysis_data DMN Analytics Decision table analytics
api_access API Access Programmatic access (required for API users)

Role Assignment

Assigning Roles to Users

Roles are assigned during user creation or via user editing:

  1. Navigate to Admin → User Management
  2. Create or edit a user
  3. Select role from dropdown
  4. Save changes

Role changes take effect: - Immediately for web interface users (on next request) - Immediately for API users (JWT validation on each call)

Permission Management

Permission Inheritance

full_access Permission: - Grants access to ALL features automatically - Bypasses individual permission checks - Only assigned to Administrator role by default

Combining Permissions: - Users can have multiple permissions via their role - Permissions are additive (no negative permissions) - Most restrictive permission wins (if conflicts exist)

Permission Scoping

Some permissions affect API vs. UI access differently:

api_access Permission: - Required for all API users - Checked in addition to feature permissions - API calls without this permission return 403 Forbidden

Example:

{
  "role": "api_analyst",
  "permissions": [
    "api_access",           // Required for API calls
    "portfolio_data",       // Allows access to portfolio endpoints
    "health_monitor_data"   // Allows access to health endpoints
  ]
}

Best Practices

1. Principle of Least Privilege

Grant only the minimum permissions needed:

Good: 

Role: Report Viewer
Permissions: portfolio_data

Bad: 

Role: Report Viewer
Permissions: full_access  // Too broad!

2. Role Naming Conventions

Use clear, descriptive names:

Good: - operations_manager - process_improvement_lead - read_only_auditor

Bad: - role1 - temp_user - john_role

3. Regular Access Reviews

Schedule periodic reviews:

  • Monthly: Review custom role assignments
  • Quarterly: Audit permission assignments
  • Annually: Reassess role definitions

4. Separation of Duties

Avoid combining conflicting permissions:

Conflicting Permissions: - User management + operational access - Read-only roles + write permissions

Example of Proper Separation:

Role: Security Auditor
Permissions:
  ✓ portfolio_data (read-only analytics)
  ✗ manage_users (should not modify what they audit)

5. Document Custom Roles

Maintain documentation for custom roles:

## Custom Role: Operations Manager

**Purpose:** Oversee daily operations with analytical capabilities

**Target Users:**
- Operations team leads
- Shift supervisors

**Permissions:**
- portfolio_data
- extended_dashboard_data
- health_monitor_data
- journey_analysis_data

**Review Date:** 2025-Q1
**Owner:** IT Security Team

Troubleshooting

User Can't Access Feature

Checklist:

  1. Verify user's role has required permission
  2. Check if role is system role (may have restrictions)
  3. Review audit log for permission denials
  4. Confirm user session is valid

Debugging:

from db.auth import user_has_permission

# Check if user has specific permission
has_access = user_has_permission(user_id, 'portfolio_data')
print(f"User {user_id} has portfolio_data: {has_access}")

Permission Changes Not Taking Effect

Possible Causes:

  1. Session cache: User's session still has old permissions

  2. Solution: User must log out and log back in

  3. API token: JWT contains old permission set

  4. Solution: Regenerate API token

  5. Redis cache: Cached session data outdated

  6. Solution: Clear cache or wait for TTL expiration

Force Permission Refresh:

# Clear all sessions for a user (admin action)
curl -X POST http://localhost:8088/auth/api/users/{user_id}/revoke-sessions \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Role Deletion Fails

Error: "Cannot delete role. N user(s) are assigned to this role"

Solution:

  1. Identify users with this role: 

    from db.auth import get_all_users

users_with_role = [u for u in get_all_users() if u['role'] == 'role_name']
print(f"Users to reassign: {[u['username'] for u in users_with_role]}")

  2. Reassign users to different role

  3. Retry deletion

Next Steps

Support

For role and permission questions: