Skip to content

Roles and Permissions

The Role and Permission system in bPass provides fine-grained access control to manage what users can and cannot do within the application. This system is built on top of the Laravel Spatie Permission package and provides a flexible, hierarchical permission structure.

Overview

The role and permission system consists of:

  • Roles: Named collections of permissions that can be assigned to users
  • Permissions: Individual capabilities that grant access to specific features or actions
  • Permission Groups: Organized categories of related permissions
  • Default Roles: Automatically assigned roles for new users

Role Management

Viewing Roles

Navigate to Settings → Roles to view all available roles in your system. The role list displays:

  • Role Name: The display name of the role
  • Guard Name: The authentication guard (typically 'sanctum')
  • Default Status: Whether this role is automatically assigned to new users
  • Creation/Update Dates: When the role was created and last modified
  • Permission Count: Number of permissions assigned to the role

Role Details

Each role card shows: - Role Icon: Visual identifier with colored gradient background - Role Metadata: Name, guard, and default status - Action Buttons: Edit and Delete options - Expandable Permissions: Click to view all assigned permissions

Creating a New Role

  1. Access Role Creation
  2. Navigate to Settings → Roles

  3. Click the "New Role" button

  4. Fill Role Information

  5. Role Name: Enter a descriptive name for the role

  6. Is Default: Check this option if you want this role automatically assigned to new users > Note: Only one role should be marked as default at a time

  7. Assign Permissions

  8. Select individual permissions or entire permission groups
  9. Use category checkboxes to select/deselect all permissions in a group

  10. Individual permissions can be toggled independently

  11. Save the Role

  12. Click Save to create the role
  13. The system will validate permissions and create the role

Editing Roles

  1. Access Role Editor
  2. From the role list, click the Edit button (pencil icon)

  3. Or click on the role name

  4. Modify Role Properties

  5. Update the role name if needed
  6. Change default status

  7. Add or remove permissions

  8. Permission Management

  9. Add Permissions: Check additional permission boxes
  10. Remove Permissions: Uncheck permission boxes

  11. Group Selection: Use category headers to manage permission groups

  12. Save Changes

  13. Click Save to apply changes
  14. All users with this role will immediately receive updated permissions

Deleting Roles

  1. Access Delete Option

  2. From the role list, click the Delete button (trash icon)

  3. Confirm Deletion

  4. Confirm the deletion in the popup dialog

  5. Warning: This action cannot be undone

  6. Restrictions

  7. Default roles cannot be deleted
  8. Roles assigned to users should be carefully considered before deletion

Permission System

Permission Structure

Permissions are organized into logical groups for better management:

Core Permission Groups

  1. User Management
  2. show user: View user listings
  3. create user: Create new users
  4. update user: Modify user information

  5. delete user: Remove users from system

  6. Role Management

  7. show role: View roles and permissions
  8. create role: Create new roles
  9. update role: Modify existing roles

  10. delete role: Delete roles

  11. Vault Management

  12. show vault: View vault entries
  13. create vault: Create new vault entries
  14. update vault: Modify vault entries

  15. delete vault: Delete vault entries

  16. Folder Management

  17. show folder: View folders
  18. create folder: Create new folders
  19. update folder: Modify folders

  20. delete folder: Delete folders

  21. Import/Export

  22. import-vault: Import vault data

  23. export-vault: Export vault data

  24. Settings

  25. general-settings: Manage application settings

Permission Hierarchy

The permission system supports hierarchical access:

  • Administrative Permissions: Full system access
  • Management Permissions: Resource-specific management
  • User Permissions: Basic user functionality
  • Read-Only Permissions: View-only access

Permission Assignment

Individual Assignment

  • Select specific permissions for granular control
  • Mix and match permissions from different groups
  • Fine-tune access based on role requirements

Group Assignment

  • Select entire permission groups for broad access
  • Use intermediate state when some (but not all) permissions are selected
  • Quickly assign related permissions together

Default Role System

First User Registration

When the very first user registers in the system: - They are automatically assigned the "Super Admin" role - This ensures system administration capabilities are available

Subsequent User Registration

For all other user registrations: - Users receive the role marked as "Default" - Only one role should be marked as default - If no default role exists, users get no initial role

Changing Default Roles

  1. Edit the desired role
  2. Check the "Is Default" option
  3. Ensure other roles have this option unchecked
  4. Save the changes

Best Practices

Role Design

  • Principle of Least Privilege: Grant only necessary permissions
  • Role-Based Access: Create roles based on job functions
  • Clear Naming: Use descriptive role names
  • Regular Review: Periodically audit role permissions

Permission Management

  • Group Related Permissions: Use permission groups for easier management
  • Document Changes: Keep track of permission modifications
  • Test Thoroughly: Verify permission changes work as expected
  • Backup Roles: Export role configurations before major changes

Security Considerations

  • Protect Admin Roles: Limit super admin role assignments
  • Default Role Security: Ensure default roles have appropriate minimal permissions
  • Regular Audits: Review user role assignments periodically
  • Permission Validation: Test permission restrictions regularly

Troubleshooting

Common Issues

Users Cannot Access Features

  • Check Role Assignment: Verify user has appropriate role
  • Verify Permissions: Ensure role has required permissions
  • Clear Cache: Clear application cache if using cached permissions

Permission Changes Not Taking Effect

  • Logout/Login: Users may need to re-authenticate
  • Clear Session: Clear user sessions
  • Check Middleware: Verify permission middleware is applied

Default Role Issues

  • Multiple Defaults: Ensure only one role is marked as default
  • No Default Role: Create and mark a role as default for new users
  • Default Role Permissions: Verify default role has appropriate permissions

Error Messages

"Permission Denied"

  • User lacks required permission for the action
  • Check user's role and role's permissions

"Role Cannot Be Deleted"

  • Default roles cannot be deleted
  • Remove default status first, then delete

"Permission Not Found"

  • Permission may have been removed or renamed
  • Update role permissions accordingly

Technical Details

Database Structure

  • Roles Table: Stores role information
  • Permissions Table: Stores permission definitions
  • Role_has_permissions: Links roles to permissions
  • Model_has_roles: Links users to roles

API Endpoints

  • GET /roles: List all roles
  • GET /permissions: List all permissions (with grouping)
  • POST /role: Create new role
  • PUT /role/{id}: Update existing role
  • DELETE /role/{id}: Delete role

Frontend Components

  • RoleList.vue: Displays role listing with expandable permissions
  • RoleForm.vue: Creates and edits roles
  • PermissionField.vue: Manages permission selection with group support

This role and permission system provides the foundation for secure, scalable access control in your bPass installation.