RBAC Overview

Overview

SSAdmin 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 across all campuses and academic operations.

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 administrators across multiple campuses and ensures consistent access control.

Key Concepts

Roles:

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

Permissions:

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

User Access:

Users are assigned roles
Roles can be scoped to specific campuses
Permanent or time-limited assignments

How RBAC Works

Two-Level Access System

SSAdmin 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
Member - Standard user access
Admin - Administrative access
Superadmin - Full system access

Characteristics:

Organization-wide access
Managed through Better-Auth authentication
Applies to the entire SSAdmin organization

2. Custom RBAC (Granular Permissions)

Purpose: Fine-grained, scoped permissions for specific contexts

Features:

Role-based permissions
Campus-specific scoping
Permanent or time-limited assignments
Detailed audit trail

Use Cases:

Campus Admin for Lagos campus only
HQ Admin with access to all campuses
Academic Coordinator for specific campus

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:

students - Student records
courses - Course management
sessions - Academic sessions
intakes - Student intakes
campuses - Campus information
reports - Reporting features
settings - System configuration

Permission Examples:

read:students - Can view student information
write:courses - Can create and edit courses
delete:intakes - Can remove intakes
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

SSAdmin provides interfaces for assigning roles to users:

RBAC Admins

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

Key Features:

Organization role assignment (Guest, Member, Admin, Superadmin)
Optional custom RBAC with campus 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

Access Scopes

Custom RBAC roles are scoped to specific campuses:

Campus Scope

Purpose: Limit access to specific campus locations

Use Case:

Campus Admin manages only their assigned campus
Campus staff can only view/edit data for their campus

Example:

User: Jane Doe
Role: Campus Admin
Scope: Lagos Campus, Abuja Campus
Result: Can manage students, courses, and operations for Lagos and Abuja only

HQ (Global) Scope

Purpose: Full access across all campuses

Use Case:

HQ Admin needs visibility and control over all campuses
System-wide reporting and configuration

Example:

User: John Smith
Role: HQ Admin
Scope: All Campuses
Result: Can manage all campus operations, view system-wide reports

Who Can Manage RBAC?

RBAC management is typically restricted to:

HQ Administrators:

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

Campus Administrators (Limited):

Can view their campus team members
May have limited user management capabilities within their campus

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 Roles by Function:
- Define roles based on job functions, not individuals
- Examples: "Campus Admin", "Academic Coordinator", "Registrar"
Use Hierarchical Levels:
- Assign access levels to reflect organizational hierarchy
- Higher levels for HQ 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 campus scoping to limit access geographically
- HQ scope for headquarters staff only
Set Expiration Dates:
- For temporary assignments (visiting staff, contractors)
- 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 Admin

Situation: Hiring an administrator for a specific campus.

Steps:

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

Temporary Staff Member

Situation: Contract staff helping with registration for a semester.

Steps:

Ensure appropriate role exists (e.g., "Registration Assistant")
Create user access assignment
Set organization role to "Member"
Enable custom RBAC
Select the role
Set scope type to "campus"
Select the specific campus
Set "Valid Until" to contract end date
Add assignment reason (e.g., "Contract staff for Fall 2024 registration")

Promoting a User

Situation: User promoted from Campus Admin to HQ Admin.

Steps:

Edit existing user access assignment
Update role from "Campus Admin" to "HQ Admin"
Update scope to cover all campuses (or remove campus restriction)
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, campus-scoped permissions for specific contexts. 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 campus 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 basic staff, 26-50 for coordinators, 51-75 for campus admins, 76-100 for HQ 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