RBAC Overview

Overview

The Partners app uses Role-Based Access Control (RBAC) to manage user permissions and access levels. RBAC ensures that users can only access and modify data they're authorized to work with, maintaining security and data integrity.

What is RBAC?

RBAC is a security model where access permissions are assigned based on roles rather than individual users. This approach makes it easier to manage permissions for large teams and ensures consistent access control.

Key Concepts

Roles:

Named positions with specific responsibilities (e.g., "Partner Lead", "Campus Coordinator")
Have defined access levels (0-100)
Can be assigned specific permissions

Permissions:

Specific actions allowed on resources (e.g., "read:partners", "write:donations")
Defined by resource (what) and action (how)
Granular control over system features

User Access:

Users are assigned roles
Roles can be scoped to specific contexts (campus, event, event edition)
Temporary or permanent assignments

How RBAC Works

Two-Level Access System

The Partners app uses a two-tier access control system:

1. Organization-Level Access (Better-Auth)

Purpose: Base organizational membership and broad access level

Roles:

Guest - Read-only access
Partner - Standard user access
Admin - Administrative access
Superadmin - Full system access

Characteristics:

Organization-wide access
Managed through Better-Auth authentication
Applies to the entire RHEMA NIGERIA PARTNERS organization

2. Custom RBAC (Granular Permissions)

Purpose: Fine-grained, scoped permissions for specific contexts

Features:

Role-based permissions
Context-specific scoping (campus, event, event edition)
Temporary or permanent assignments
Detailed audit trail

Use Cases:

Campus Coordinator for Lagos campus only
Event Lead for Summer Retreat event
Volunteer Coordinator for specific event edition

Permission Model

Permissions follow the format: action:resource

Common Actions:

read - View data
write - Create and update data
delete - Remove data
manage - Full control (all actions)

Common Resources:

partners - Partner records
donations - Donation data
events - Event management
reports - Reporting features
settings - System configuration

Permission Examples:

read:partners - Can view partner information
write:donations - Can create and edit donations
delete:events - Can remove events
manage:settings - Full control over settings

RBAC Components

Roles Management

Create and manage roles with specific access levels and permissions.

Key Features:

Role naming and description
Access level (0-100, higher = more access)
Active/inactive status
Permission assignments

Learn more about Roles →

Permissions Management

Define specific actions users can perform on resources.

Key Features:

Resource and action definition
Permission naming (action:resource format)
Permission descriptions
Role assignments

Learn more about Permissions →

Role-Permission Assignments

Connect roles with specific permissions.

Key Features:

Assign permissions to roles
Batch permission assignment
View role-permission relationships
Remove permissions from roles

Learn more about Role-Permissions →

User Assignment Management

The system provides FOUR interfaces for assigning roles to users:

RBAC Admins

Unified interface for complete user setup (organization + optional custom RBAC).

Key Features:

Organization role assignment (Guest, Partner, Admin, Superadmin)
Optional custom RBAC with scope selector
Complete user onboarding in one place

Learn more →

User-Campus-Roles

Dedicated interface for campus-specific role assignments.

Key Features:

Assign users to specific campuses
Multiple campus assignments per user
Campus team management

Learn more →

User-Event-Roles

Dedicated interface for event-specific role assignments (all editions).

Key Features:

Assign users to specific events
Ongoing event responsibilities across all years
Event team management

Learn more →

User-Event-Edition-Roles

Dedicated interface for event edition-specific assignments (year-specific).

Key Features:

Assign users to specific event editions/years
Temporary, seasonal assignments
Year-specific access control

Learn more →

Access Scopes

Custom RBAC roles can be scoped to specific contexts:

Campus Scope

Purpose: Limit access to specific campus locations

Use Case:

Campus Coordinator manages only Lagos campus partners
Campus volunteers can only log calls for their campus

Example:

User: Jane Doe
Role: Campus Coordinator
Scope: Lagos Campus, Abuja Campus
Result: Can manage partners for Lagos and Abuja only

Event Scope

Purpose: Limit access to specific events

Use Case:

Event Lead manages only Summer Retreat event
Event volunteers handle only their assigned event

Example:

User: John Smith
Role: Event Lead
Scope: Summer Retreat, Harvest Festival
Result: Can manage these two events only

Event Edition Scope

Purpose: Limit access to specific event editions (years)

Use Case:

Temporary coordinator for 2024 edition only
Historical access to specific past editions

Example:

User: Sarah Johnson
Role: Event Coordinator
Scope: Summer Retreat 2024
Result: Can manage only 2024 edition of Summer Retreat

Who Can Manage RBAC?

RBAC management is typically restricted to:

System Administrators:

Full access to all RBAC features
Create roles and permissions
Assign user access
View audit trails

Organization Admins (Better-Auth level):

Can assign organization roles
May have limited RBAC management capabilities

Regular Users:

Cannot manage RBAC
Can view their own permissions and roles
Work within their assigned permissions

Only trusted administrators should have RBAC management access. Incorrect permission configuration can compromise system security.

Best Practices

Role Design

Create Role by Function:
- Define roles based on job functions, not individuals
- Examples: "Partner Coordinator", "Call Center Lead", "Campus Manager"
Use Hierarchical Levels:
- Assign access levels to reflect organizational hierarchy
- Higher levels for senior positions
- Enables permission checks based on level
Keep Roles Focused:
- Each role should have a clear purpose
- Avoid creating too many similar roles
- Use scoping instead of creating campus-specific roles

Permission Strategy

Principle of Least Privilege:
- Grant only permissions necessary for the job
- Start with minimal access, add as needed
- Regularly review and remove unnecessary permissions
Group Related Permissions:
- Create permission sets for common workflows
- Assign multiple permissions to roles in batches
- Maintain consistency across similar roles
Use Clear Naming:
- Follow action:resource format consistently
- Use descriptive action and resource names
- Document what each permission allows

User Access Management

Scope Appropriately:
- Use scoping to limit access geographically or functionally
- Campus scope for location-based roles
- Event scope for time-limited projects
Set Expiration Dates:
- For temporary assignments (volunteers, seasonal staff)
- Automatically removes access after date
- Prevents lingering permissions
Document Assignments:
- Always provide assignment reasons
- Helps with audits and reviews
- Explains why access was granted
Regular Audits:
- Quarterly review of user access
- Remove inactive users
- Update roles for position changes
- Verify scoping is still appropriate

Common Scenarios

New Campus Coordinator

Situation: Hiring a campus coordinator for a specific campus.

Steps:

Ensure "Campus Coordinator" role exists with appropriate permissions
Create user access assignment
Set organization role to "partner" or "admin"
Enable custom RBAC
Select "Campus Coordinator" role
Set scope type to "campus"
Select the specific campus
Add assignment reason
Leave "Valid Until" empty for permanent access

Temporary Event Volunteer

Situation: Volunteer helping with a specific event edition.

Steps:

Ensure "Event Volunteer" role exists
Create user access assignment
Set organization role to "guest" or "partner"
Enable custom RBAC
Select "Event Volunteer" role
Set scope type to "eventEdition"
Select the specific event edition (e.g., Summer Retreat 2024)
Set "Valid Until" to event end date
Add assignment reason (e.g., "Volunteer for Summer Retreat 2024")

Promoting a User

Situation: User promoted from volunteer to team lead.

Steps:

Edit existing user access assignment
Update role from "Volunteer" to "Team Lead"
Update scope if needed (may now cover multiple campuses/events)
Add note in assignment reason about the promotion
Adjust "Valid Until" if moving from temporary to permanent

Security Considerations

Protect Sensitive Permissions:
- Limit who can delete data
- Restrict settings management
- Control export capabilities
Monitor Permission Changes:
- Track who creates/modifies roles
- Log permission assignments
- Review access regularly
Separate Duties:
- Different users for data entry vs. deletion
- Separate reporting access from data modification
- Financial permissions limited to specific users
Test Permission Changes:
- Before deploying new roles, test thoroughly
- Verify users can access what they need
- Ensure restrictions work as intended

Common Questions

Q: What's the difference between Organization Role and Custom RBAC?

A: Organization Role (Better-Auth) provides broad, organization-wide access. Custom RBAC provides granular, scoped permissions for specific contexts (campus, event). Most users will have both.

Q: Can a user have multiple roles?

A: Yes, a user can have one Organization Role and multiple Custom RBAC role assignments with different scopes.

Q: What happens when a custom RBAC assignment expires?

A: The user loses the scoped permissions but retains their Organization Role access. The assignment can be viewed in history.

Q: How do I know what permissions a role has?

A: View the role in Roles Management to see all assigned permissions. Use the Role-Permissions feature to manage the assignments.

Q: Can permissions overlap or conflict?

A: Permissions are additive. If a user has multiple roles with different permissions, they get the combined set of all permissions.

Q: What access level should I assign to new roles?

A: Use 0-25 for volunteers, 26-50 for coordinators, 51-75 for team leads, 76-100 for administrators. Adjust based on your organizational structure.

Roles Management - Create and manage roles
Permissions Management - Define system permissions
Role-Permissions - Assign permissions to roles
User Access - Assign roles to users

RBAC Overview

On this page