Don’t forget to subscribe to our YouTube channel to stay up-to-date.
This tutorial will demonstrate how to use the Custom Permissions module.
By default in Drupal, user permissions in the Drupal backend are not very granular.
For example, if you want to give a role the ability to edit only the “Basic site settings” in the Drupal admin UI. In Drupal, this can be achieved by giving the access permissions “administer site configuration”. However, with this permission enabled, the role will also have the ability to edit other site settings which you may not want a user to have access to.
Enter the Custom Permissions module.
With this module, you could solve the above problem by creating an extra custom permission to edit only the “Basic site settings” page without assigning the “administer site configuration”.
This light-weight module will allow you to specify the exact admin route (or path) that you want to give permissions to without giving the role access to everything in the administration section.
In this tutorial, you’ll learn how to create a custom permission which will only have access to the “Basic site settings” page. We’ll be using the 8.x-2.x version of the module.
Difference between 1.x and 2.x?
Both versions accomplish the same functionality, but the difference is that when specifying the page you want to give access to, version 8.x-2.x uses routes and version 8.x-1.x uses paths.
How to Find out the Route Name
A route in Drupal is a path which is defined for Drupal to return some sort of content on. Routes are defined in a module’s MODULE_NAME.routing.yml file. There can be routes defined in contributed, custom or Drupal core modules.
For Drupal core routes (paths in the Drupal core admin UI), you would want to text-search for the path in: web/core/modules/system/system.routing.yml
For contributed or custom routes, search in the relevant modules’s “.routing.yml” file.
In our example, the block of code in system.routing.yml for our path “admin/config/system/site-information” is:
system.site_information_settings:
path: '/admin/config/system/site-information'
defaults:
_form: '\Drupal\system\Form\SiteInformationForm'
_title: 'Basic site settings'
requirements:
_permission: 'administer site configuration'
The route name is bolded above to show you what the route name will be. The exact route name is: system.site_information_settings.
Using Devel
If you prefer not to search through code to find the route name, look at using the Devel module. Devel comes with a Routes Info page which lists all the active routes and its paths, and you can filter the page. This makes it easy to find the correct route.
Once the module is installed click on the Devel link in the toolbar then “Routes Info”.
On the “Routes Info” page you’ll see a long list of routes and its paths.
Getting Started
This module requires no additional libraries and can simply be downloaded with Composer.
Using Composer:
composer require drupal/config_perms
Installing the module with above composer command will install version 8.x-2.x of the module.
Once downloaded go and install the module.
How to create a Custom Permission
In this tutorial, we are going to create a custom permission to allow a role to access and update only the “Basic site settings” page in the Drupal admin UI.
1. Once the module is installed, go to People > Custom permissions.
You’ll notice that the module comes with four default custom permissions.
2. Click on the “Add permission” button, and you will get an additional row to add a new permission.
3. Give your new permission an admin human-readable name and click on “Save”. Note that this name is only visible to the site admin. The route that we want to use for the “Basic site settings” is “system.site_information_settings”.
4. Go to People > Roles and edit the permissions of the role that you want to assign this new custom permission too. We will use the “Authenticated user” role in this example.
5. Scroll to “Custom Permissions” and you will see the new custom permission human-readable name you created in Step 3. Enable it.
6. For the new role to access the administration pages in Drupal, you also have to enable “Use the administration pages and help”. You can also enable “Use the toolbar” so the user can see the enabled permission in the admin toolbar although this is just for convenience and not a requirement for this tutorial.
7. Now, the user with the role “Authenticated user” will have access to the following permission as shown below:
Summary
Drupal, by default, may not always define granular permissions to certain administrative pages. Typically, a role can be given all or no access to administrative pages.
Using the contributed module Custom Permissions (version 8.x-2.x) you can define custom permissions for specific Drupal admin pages. This module provides finer granular permissions for specific Drupal routes/paths.
