Permissions Management

Overview

The Permissions module provides a comprehensive view of all permissions available in the admin panel. Permissions are the building blocks of the access control system - they define specific actions that can be performed throughout the application. This module allows you to browse permissions, understand what they control, see which roles have them, and synchronize system permissions.

Accessing Permissions Management

Navigation: Dashboard > Users > Roles & Permissions > View Permissions

Required Permission: permissions.view

Key Features

• Browse All Permissions: View complete list of system permissions
• Category Organization: Permissions grouped by functional area
• Role Assignments: See which roles have each permission
• Permission Details: View descriptions and usage information
• Synchronization: Sync permissions with system-defined permissions
• Search and Filter: Find specific permissions quickly

Main Interface

List View

The permissions list displays all permissions organized by category in an accordion-style interface:

Statistics Dashboard:
At the top of the page, you'll see summary cards showing:

• Total Permissions: Count of all permissions in the system
• Categories: Number of permission categories
• Roles Using: Number of roles that use permissions
• Last Synced: When permissions were last synchronized

Permission Display:

• Permissions are grouped by category (collapsible sections)
• Each permission shows:
  • Permission Name: Technical identifier (e.g., users.create)
  • Description: Human-readable explanation of what it controls
  • Roles: Badges showing which roles have this permission
  • View Details: Link to see more information

Available Filters:

• Search: Filter by permission name or description
• Category Filter: Show only permissions from a specific category
• Role Filter: Show only permissions assigned to a specific role

Permission Categories

Permissions are organized into the following categories:

Users

• User account management permissions
• Examples: users.view, users.create, users.edit, users.delete, users.manage_roles

Roles

• Role and permission management
• Examples: roles.view, roles.create, roles.edit, roles.delete

Permissions

• Permission system management
• Examples: permissions.view, permissions.manage, permissions.sync

Pages

• Content page management
• Examples: pages.view, pages.create, pages.edit, pages.delete, pages.publish

Media

• Media library access and management
• Examples: media.view, media.upload, media.delete, media.manage

Settings

• System configuration and settings
• Examples: settings.view, settings.edit, settings.mail, settings.general

Security

• Security features and audit logs
• Examples: security.view, security.manage, audit_logs.view, security_events.view

SEO

• SEO and sitemap management
• Examples: seo.view, seo.edit, sitemaps.view, sitemaps.generate

Content

• General content management
• Examples: landing_page.edit, footer.edit, navigation.manage, about_us.edit

Communication

• Contact messages and notifications
• Examples: contact_messages.view, contact_messages.reply, notifications.send

Maintenance

• System maintenance and backups
• Examples: backups.view, backups.create, backups.restore, backups.download

Common Tasks

Viewing All Permissions

1. Navigate to the Permissions page
2. Permissions are displayed grouped by category
3. Click on a category to expand and see its permissions
4. Each permission shows its name, description, and assigned roles

Searching for Permissions

1. Use the search box at the top of the page
2. Type part of the permission name or description
3. Results filter automatically as you type
4. Search looks in both permission names and descriptions

Example Searches:

• "create" - finds all permissions related to creating items
• "user" - finds all user-related permissions
• "edit" - finds all editing permissions

Filtering by Category

1. Use the "Category" dropdown filter
2. Select a specific category (e.g., "Users", "Pages", "Security")
3. Only permissions from that category will be displayed
4. Clear the filter to see all categories again

Viewing Permission Details

1. Click on a permission name or the "View Details" link
2. The details page shows:
   • Permission Information: Name, category, description
   • Roles with Permission: List of all roles that have this permission
   • Roles without Permission: List of roles that don't have it
   • Users with Permission: All users who have this permission (through their roles)
   • Usage Statistics: How many roles and users have this permission

Understanding Permission Naming

Permissions follow a consistent naming convention:

Format: category.action

Examples:

• users.view - View users
• users.create - Create new users
• users.edit - Edit existing users
• users.delete - Delete users
• users.manage_roles - Assign/remove roles from users

Common Actions:

• view - Read/view access
• create - Create new items
• edit - Modify existing items
• delete - Remove items
• manage - Full management access
• publish - Publish/unpublish content

Assigning Permissions to Roles

Permissions cannot be assigned directly from this module. To assign permissions:

1. Go to the Roles module
2. Edit the role you want to modify
3. Check the boxes for permissions you want to assign
4. Save the role

Alternatively:

1. View a permission's details page
2. See which roles don't have it
3. Click on a role to edit it
4. Assign the permission

Assigning Permissions Directly to Users

While possible, direct permission assignment to users is not recommended. Instead:

1. Create or modify a role with the needed permissions
2. Assign that role to the user
3. This makes permission management much easier long-term

For direct assignment (advanced use only):

• This requires custom code or database access
• Not available through the standard UI
• Should only be used for exceptional cases

Synchronizing Permissions

The sync function updates the database with any new permissions defined in the code:

1. Click the "Sync Permissions" button
2. The system will:
   • Add any new permissions defined in code
   • Update descriptions for existing permissions
   • Preserve all existing role assignments
3. A success message shows how many permissions were created or updated
4. All changes are logged in the audit system

When to Sync:

• After updating the application code
• When new features are added
• If permissions seem to be missing
• After installing new modules or plugins

What Happens:

• New permissions are added to the database
• Existing permissions are updated if their definitions changed
• No permissions are deleted (to preserve role assignments)
• Permission caches are cleared

Settings and Options

Search Field

• Type: Text input
• Description: Filters permissions by name or description
• Behavior: Real-time filtering as you type

Category Filter

• Type: Dropdown select
• Options: All available permission categories
• Description: Shows only permissions from the selected category

Role Filter

• Type: Dropdown select
• Options: All available roles
• Description: Shows only permissions assigned to the selected role

Permissions

The following permissions control access to the Permissions module:

• permissions.view: Can view the permissions list and permission details
• permissions.manage: Can synchronize permissions with the system
• permissions.sync: Can trigger permission synchronization (same as manage)

Permission Hierarchy:

• Viewing permissions is the base permission
• Managing/syncing requires elevated access
• Super admins have all permissions by default

Tips and Best Practices

• Understand Before Assigning: Read permission descriptions carefully before assigning them to roles
• Use Categories: Think in terms of categories when designing roles (e.g., a Content Editor needs all "Pages" and "Media" permissions)
• Follow Naming Conventions: When requesting new permissions, follow the category.action format
• Regular Syncs: Sync permissions after each application update to ensure all new permissions are available
• Document Custom Permissions: If adding custom permissions, document what they control
• Test Permission Changes: Use impersonation to test permission configurations before deploying to users
• Avoid Direct User Permissions: Always use roles instead of assigning permissions directly to users
• Review Regularly: Periodically review which permissions exist and whether they're all still needed

Troubleshooting

Problem: Permission Not Showing in List

Solution:

• Try syncing permissions using the "Sync Permissions" button
• The permission might be defined in code but not yet in the database
• Check if you're filtering by category or search term
• Clear all filters and search again

Problem: Cannot Sync Permissions

Solution:

• Verify you have the permissions.manage or permissions.sync permission
• Check server logs for any errors during sync
• Ensure the database is accessible and writable
• Contact a developer if the issue persists

Problem: Permission Exists But Doesn't Work

Solution:

• Verify the permission is assigned to the user's role
• Check if the user has the role that includes this permission
• Use the user's permissions view to see their effective permissions
• Clear permission caches (may require developer assistance)
• Check if the feature is properly checking for this permission in code

Problem: Too Many Permissions to Browse

Solution:

• Use the search function to find specific permissions
• Filter by category to narrow down the list
• Use the role filter to see only permissions relevant to a specific role
• Collapse categories you're not interested in

Problem: Don't Know Which Permission Controls a Feature

Solution:

• Check the feature's page or button for permission requirements
• Look in the relevant category (e.g., user features are in "Users" category)
• Search for keywords related to the feature
• Check the audit logs to see which permission was checked
• Ask a developer or check the documentation

Problem: Permission Descriptions Are Unclear

Solution:

• View the permission details to see which roles have it
• Check which users have the permission to understand its scope
• Test the permission using impersonation
• Refer to module-specific documentation
• Contact support for clarification

Related Modules

• Roles: Assign permissions to roles for easier management
• Users: View which users have specific permissions through their roles
• Impersonation: Test permission configurations by impersonating users
• Audit Logs: Review permission-related activities and changes
• Security Settings: Configure additional security requirements