Role Management

Complete guide to RBAC system with Filament Shield

Role Management

The role management system allows you to control access to Zuora Workflow Manager functionalities through a Role-Based Access Control (RBAC) approach.

Overview

What is RBAC?

Role-Based Access Control (RBAC) is a system that:

• Assigns permissions to roles
• Assigns roles to users
• Users inherit permissions from assigned roles

Permissions ← Roles ← Users

Filament Shield

Zuora Workflow Manager uses Filament Shield for:

• Automatically generating permissions for each Resource
• Managing roles and assignments
• Integrating with Laravel Policies
• Providing UI for permission management

Predefined Roles

Super Admin

Property	Value
Name	super_admin
Description	Administrator with full access
Permissions	All available permissions
Access to	All sections of the admin panel

Who should have it:

• System administrators
• Lead developers
• Only 1-3 users per organization

Workflow User

Property	Value
Name	workflow_user
Description	User who views workflows and tasks
Permissions	View access to Workflows and Tasks
Access to	Workflows, Tasks

Specific permissions:

ViewAny:Workflow
View:Workflow
ViewAny:Task
View:Task

Who should have it:

• Business analyst
• Users who need to analyze workflows
• Report viewers

Panel User

Property	Value
Name	panel_user
Description	Base user with limited access
Permissions	Minimum panel access
Access to	Limited dashboard

Who should have it:

• Users in onboarding phase
• Temporary users
• Starting role for new users

Creating a Role

Step 1: Navigate to Roles

1. Login to admin panel as super_admin
2. Click Roles in sidebar under Shield

Step 2: Create New Role

1. Click New Role button in top right
2. Fill out the form:

Form Fields

Field	Description	Required
Name	Role name (snake_case)	Yes
Guard Name	Authentication guard	No (default: web)

Step 3: Select Permissions

In the Permissions section, you’ll see permissions organized by Resource:

├─ Customer Resource
│   ├─ ViewAny
│   ├─ View
│   ├─ Create
│   ├─ Update
│   └─ Delete
├─ Workflow Resource
│   ├─ ViewAny
│   ├─ View
│   ├─ ...
├─ Task Resource
│   ├─ ...
└─ ...

For each Resource you can:

• Select All: Select all permissions for the Resource
• Select individually: Click on each permission

Permissions are automatically generated by Filament Shield based on defined Resources.

Step 4: Save the Role

Click Create to save the new role.

Use descriptive names in snake_case: sales_manager, report_viewer, api_user.

Editing a Role

Step 1: Select the Role

1. Navigate to Roles list
2. Click on the role to edit

Step 2: Edit Permissions

1. Select/deselect necessary permissions
2. You can also modify the role name

Step 3: Save Changes

Click Save to apply the changes.

Permission changes are immediate for all users with that role.

Viewing Roles

Roles List

The Roles table shows:

Column	Description
Name	Role name (Headline format)
Guard Name	Authentication guard
Team	Associated team (if multi-tenancy enabled)
Permissions	Number of assigned permissions (badge)
Updated At	Last update date
Actions	Available actions

Role Details

Click on a role to see:

• General information: Name, guard
• Assigned permissions: Complete list organized by Resource
• Assigned users: List of users with this role

Available Permissions

Permissions per Resource

Each Resource has the following standard permissions:

Permission	Description	When to use
ViewAny:{Resource}	View records list	Read-only list
View:{Resource}	View record details	Read details
Create:{Resource}	Create new record	Creation
Update:{Resource}	Modify existing record	Modification
Delete:{Resource}	Delete record	Deletion
Restore:{Resource}	Restore deleted record (soft delete)	Restore
ForceDelete:{Resource}	Permanent deletion (hard delete)	Hard delete

Permissions by Resource

Customer Resource

ViewAny:Customer
View:Customer
Create:Customer
Update:Customer
Delete:Customer

Workflow Resource

ViewAny:Workflow
View:Workflow
// Note: Workflows are synchronized, not created manually

Task Resource

ViewAny:Task
View:Task
// Note: Tasks are extracted from workflows, not created manually

User Resource

ViewAny:User
View:User
Create:User
Update:User
Delete:User

Role Resource

ViewAny:Role
View:Role
Create:Role
Update:Role
Delete:Role

Special Permissions

Some additional permissions can be defined:

• Access Settings: Access to Settings (super_admin only)
• Manage Jobs: Manage system jobs
• View Reports: View reports

Assigning Roles to Users

Assignment from User Resource

1. Navigate to Users
2. Click on the user to modify
3. In the Roles section, select the roles to assign
4. Click Save

Multiple Assignment

A user can have multiple roles:

// Example: user with multiple roles
$roles = ['super_admin', 'workflow_user'];

// Permissions are combined (OR)
$user->hasRole('super_admin');           // true
$user->hasRole('workflow_user');        // true
$user->hasAllRoles(['super_admin']);    // true

If a user has multiple roles, permissions are combined. If one of the roles has a permission, the user has that permission.

Assignment via CLI

# Assign role to user via tinker
lando artisan tinker

>>> $user = User::where('email', '[e-mail]')->first()
>>> $user->assignRole('workflow_user')
>>> $user->assignRole(['workflow_user', 'panel_user']) // Multiple roles
>>> $user->syncRoles(['super_admin']) // Replaces all roles

Removing Role

1. Edit user
2. Deselect the role to remove
3. Click Save

Or via CLI:

>>> $user = User::where('email', '[e-mail]')->first()
>>> $user->removeRole('workflow_user')
>>> $user->removeRole(['workflow_user', 'panel_user']) // Remove multiple
>>> $user->syncRoles([]) // Remove all roles

Viewing Users by Role

From Roles

1. Click on a role
2. Scroll to the Users section
3. See all users with that role assigned

From Users

1. The Roles column in the Users table shows each user’s roles as badges
2. You can filter by role if necessary

Deleting a Role

Warning

Deleting a role:

• Removes assignment from all users
• Doesn’t delete the users
• Is irreversible

Ensure that users with the role have alternative roles before deleting.

Procedure

1. Click on the role to delete
2. Click Delete in the top right corner
3. Confirm deletion in the modal

Best Practices

RBAC Principles

Separation of concerns:

✅ Good practices:

• Separate responsibilities in distinct roles
• Avoid giving all permissions to a single role (except super_admin)
• Create specific roles for specific tasks

❌ Avoid:

• Creating a “generic user” role with too many permissions
• Assigning super_admin to all users
• Mixing responsibilities in a single role

Role Names

Conventions:

✅ Good names:

• sales_manager
• report_viewer
• workflow_analyst
• customer_support

❌ Names to avoid:

• role1, role2
• user, admin (too generic)
• full_access (use super_admin)

Always use snake_case for role names.

Minimal Permissions

Principle of least privilege:

1. Define the task first:

   • What does the user need to do?
   • What data do they need to see?
   • What actions do they need to perform?

2. Assign only necessary permissions:

   • If they only need to view → View:Resource
   • If they need to modify → Add Update:Resource
   • Don’t give permissions “just in case”

3. Review periodically:

   • Are permissions still necessary?
   • Are there unused permissions?
   • Does the role have unused permissions?

Custom Role Examples

Sales Manager

// Role for sales people who see customers
$role = 'sales_manager';

// Permissions
ViewAny:Customer
View:Customer
ViewAny:Workflow
View:Workflow
ViewAny:Task
View:Task

Report Analyst

// Role for report analysts
$role = 'report_analyst';

// Permissions (read only)
ViewAny:Customer
ViewAny:Workflow
ViewAny:Task
ViewAny:User

Customer Support

// Role for customer support
$role = 'customer_support';

// Permissions (read customers/workflows)
ViewAny:Customer
View:Customer
ViewAny:Workflow
View:Workflow

Periodic Review

Recommendation: Review roles and permissions every 6 months

Process:

1. Analysis:

   • What roles exist?
   • How many users have each role?
   • Are permissions still appropriate?

2. Validation:

   • Ask team responsibles
   • Verify current requirements
   • Identify unnecessary permissions

3. Update:

   • Remove obsolete permissions
   • Add missing permissions
   • Rename roles for clarity

4. Communication:

   • Notify users of changes
   • Explain reasons for modifications
   • Provide training if necessary

Policies and RBAC

Integration with Policies

Filament Shield integrates with Laravel Policies:

// CustomerPolicy.php
public function view(User $user, Customer $customer): bool
{
    // Check if user has the permission
    return $user->can('view', $customer);
}

Access Control

In code, you can check permissions:

// In a controller or service
if ($user->can('ViewAny:Customer')) {
    // User can see customers list
}

if ($user->hasRole('super_admin')) {
    // User is super admin
}

// In a Policy
public function update(User $user, Customer $customer): bool
{
    return $user->hasRole('super_admin');
}

Visual Filters

In Filament, you can hide elements based on roles:

// In a Resource
public static function canViewAny(): bool
{
    return auth()->user()->can('ViewAny:Customer');
}

protected static function shouldRegisterNavigation(): bool
{
    return auth()->user()?->hasRole('super_admin');
}

Troubleshooting

User Doesn’t See Section

Symptom: User cannot access Customers/Workflows/etc.

Solutions:

1. Verify roles:

   >>> $user = User::where('email', '[e-mail]')->first()
   >>> $user->roles // Collection of Role
   

2. Verify permissions:

   >>> $user->getAllPermissions() // All permissions
   >>> $user->hasPermissionTo('ViewAny:Customer')
   

3. Check Resource visibility:

   • Resources automatically hide if user doesn’t have ViewAny:Resource
   • Verify role has correct permissions

4. Cache:

   lando artisan cache:clear
   lando artisan permission:cache-reset
   

Permissions Not Working

Symptom: Permission assigned but user cannot perform action

Possible causes:

1. Policy override:

   • The Policy might be denying the permission
   • Check the specific Resource’s Policy

2. Multiple guards:

   • If using multiple guards, verify which guard the user uses
   • The role must be on the same guard

3. Permission cache:

   lando artisan permission:cache-reset
   

4. Filament caching:

   • Clear Filament cache
   • Logout and re-login

Role Deleted, Users Without Roles

Symptom: You deleted a role and now users have no roles

Solution:

1. Assign new roles to affected users
2. Create a base role (e.g., panel_user) and assign to users with no roles

API Reference

Role Model

// Create role
$role = Role::create(['name' => 'analyst']);

// Assign permissions
$role->givePermissionTo('ViewAny:Customer');
$role->givePermissionTo(['ViewAny:Workflow', 'ViewAny:Task']);

// Remove permissions
$role->revokePermissionTo('ViewAny:Customer');

// Sync permissions (replaces all)
$role->syncPermissions(['ViewAny:Customer', 'View:Customer']);

// Verify permissions
$role->hasPermissionTo('ViewAny:Customer'); // true/false
$role->hasAllPermissions(['ViewAny:Customer', 'View:Customer']); // true/false

// Get users with this role
$role->users; // Collection of User

Permission Model

// Create permission
$permission = Permission::create(['name' => 'Custom:Action']);

// Assign to role
$role->givePermissionTo($permission);

// Get roles with this permission
$permission->roles; // Collection of Role

User Model

// Assign roles
$user->assignRole('analyst');
$user->assignRole(['analyst', 'report_viewer']);

// Sync roles
$user->syncRoles(['analyst', 'super_admin']);

// Remove roles
$user->removeRole('analyst');
$user->removeRole(['analyst', 'report_viewer']);

// Verify roles
$user->hasRole('super_admin'); // true/false
$user->hasAllRoles(['analyst', 'report_viewer']); // true/false
$user->hasAnyRole(['analyst', 'super_admin']); // true/false

// Get roles
$user->roles; // Collection of Role
$user->getRoleNames(); // Collection of strings
$user->getDirectPermissions(); // Direct permissions (not from roles)
$user->getAllPermissions(); // All permissions (from roles + direct)

// Verify permissions
$user->can('ViewAny:Customer'); // Policy check
$user->hasPermissionTo('ViewAny:Customer'); // Permission check

Next Steps

After configuring roles:

User Management

Assign roles to users

OAuth Management

Configure OAuth authentication

RBAC Architecture

Deep dive into access control system

Security

Security best practices