Custom Permissions

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.

config_perms

10,058 sites

drupal.org

gui api

permissions access control administration security user roles route access configuration management

Drupal 8 Drupal 9 Drupal 10 Drupal 11

Install

Drupal 11, 10, 9, 8 v8.x-2.3

composer require 'drupal/config_perms:8.x-2.3'

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.

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

Technical Details

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.

Administer custom permissions

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.

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.

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