Custom Permissions
config_perms
A lightweight module that allows site administrators to create custom permissions and map them to specific Drupal routes, enabling granular access control without the need for the broad 'Administer site configuration' permission.
Overview
Custom Permissions is a lightweight Drupal module that provides a simple yet powerful way to create and manage custom permissions through an administration interface. The module allows administrators to define permissions that can be assigned to specific routes (administrative paths), enabling fine-grained access control for site configuration tasks.
The module works by creating configuration entities that store permission names and their associated routes. When enabled, it dynamically generates these permissions in Drupal's permission system and overrides the default access checks on the specified routes with its own access checker. This means that users with the custom permission can access the specified routes without needing the broader 'Administer site configuration' permission.
The module comes with four pre-configured permissions out of the box: Administer account settings, Administer date-time, Administer error logs, and Administer file system. Administrators can easily add new permissions or modify existing ones through the administration interface.
Install
composer require 'drupal/config_perms:8.x-2.3'
Features
- Create custom permissions mapped to specific Drupal routes through an intuitive admin interface
- Dynamically generates permissions that appear on Drupal's standard permissions page
- Overrides route access checks to use custom permission-based access control
- Comes with four pre-configured permissions for common administrative tasks
- Supports multiple routes per permission using newline-separated route names
- Stores permissions as configuration entities, making them exportable and deployable
- Validates route names to ensure they exist before saving permissions
- User 1 maintains full administrative control regardless of permission settings
Use Cases
Delegating Administrative Tasks to Content Editors
A common use case is allowing content editors to access specific configuration pages without granting full administrative access. For example, you can create a custom permission that allows editors to manage date formats (entity.date_format.collection) so they can configure how dates appear on the site, without having access to other system settings.
Creating Role-Based Access to Reporting
Site administrators can create a custom permission to access the database logging page (dblog.overview) and assign it to a 'Site Monitor' role. This allows designated users to view error logs and site activity without having broader administrative privileges.
Separating File System Administration
For sites where specific users need to configure file upload settings, create a permission mapped to system.file_system_settings. This enables file administrators to manage upload directories and file handling without access to other system configuration.
Multi-Route Permission Bundles
Create a single permission that grants access to multiple related routes. For example, a 'Manage User Settings' permission could include both entity.user.admin_form (account settings) and user.role_admin (role management), creating a comprehensive user administration permission.
Tips
- Route names can be found in *.routing.yml files within Drupal core and contributed modules, or by using debugging tools like Devel module
- Remember that custom permissions completely override the default access requirements for specified routes - users with original core permissions will no longer have access unless they also have the custom permission
- Always test custom permissions with a non-admin account to verify access is correctly restricted
- When migrating from older versions, note that paths have been replaced with route names - use Drupal's path validator to convert paths to route names
- Multiple routes can be assigned to a single permission by entering each route name on a separate line in the Route(s) field
Admin Pages
| Title | Path | Description |
|---|---|---|
| Custom permissions list forms | /admin/people/custom-permissions/list |
The main administration page for managing custom permissions. This page displays a table of all defined custom permissions and allows administrators to create, edit, enable/disable, and delete permissions. Each permission can be mapped to one or more Drupal routes. |
| Delete Custom perms entity | /admin/structure/custom_perms_entity/{custom_perms_entity}/delete |
Confirmation page for deleting a custom permission. Displays the permission name and asks for confirmation before permanent deletion. |
Permissions
| Permission | Description |
|---|---|
|
Allows users to access and manage the Custom Permissions administration page. Users with this permission can create, edit, enable/disable, and delete custom permissions. This is a restricted access permission due to its security implications. |
Hooks
| Hook | Description |
|---|---|
config_perms_parse_path |
Utility function to convert between string and array representations of routes. When given an array of routes, joins them with newlines. When given a string, splits by newlines into an array. |
Security Notes
- Custom permissions may have security implications as they grant access to administrative pages - carefully review which routes are being exposed
- The module displays a warning on the permissions page indicating that custom permissions may have security implications
- Removing a user's 'Administer site configuration' permission while relying on custom permissions ensures they can only access specifically designated administrative areas
- User 1 always maintains full access regardless of permission settings, providing a failsafe for site recovery