Permission

A permission in Drupal is a single named right, such as access content or administer nodes, that a module defines and a site owner grants. Drupal checks it before an account may do the matching action. Core grants permissions to roles, not to individual accounts, and an account receives the permissions of the roles it holds.

How it works in Drupal 11

A module declares permissions in a file named MODULE.permissions.yml. Each entry has a machine name and a title, which is required. It can also have a description and a boolean restrict access. According to the class documentation of PermissionHandler, the latter shows a security warning on the Permissions page and defaults to false. A module that needs permissions built on the fly lists callables under permission_callbacks, and each returns permissions keyed by machine name.

Permissions are enforced in two common ways. A route can require one with _permission; the access check also accepts several, joined with a comma for AND or a plus sign for OR. In code, $account->hasPermission('administer nodes') asks the permission checker service, which runs the access policies. One of them, UserRolesAccessPolicy, reads the permissions from the account's roles. Two cases grant everything: a role flagged as administrator, and user 1, through an access policy of its own that the container parameter security.enable_super_user can switch off.

Permissions live in role configuration. A role depends on the module that provides each of its permissions. If a role names a permission that no module defines, Role::calculateDependencies() removes it and logs one error that lists the removed permissions.

Example

A custom module that manages event schedules could declare this in events.permissions.yml:

administer event schedules:
          title: 'Administer event schedules'
          description: 'Change the schedule for all events.'
          restrict access: true

Then protect a route with _permission: 'administer event schedules'. Site owners now see the permission on People › Permissions (/admin/people/permissions), which has a filter box and shows the warning for this one. The Drupal User Guide adds a caution for that page: some permissions have security implications, so be careful when assigning them to roles.

Common mistakes

• Ticking boxes for Anonymous user. Every visitor gets what that column grants. Read it as if a stranger held the permission. See anonymous.
• Checking a role name in code. A test for the role editor breaks when the site owner reshapes the roles. Check the permission instead.
• Renaming a permission in a module. Roles still hold the old name, and when Drupal recalculates the role's dependencies it removes the unknown permission. Keep the name, or update the role configuration.
• Granting an administer permission to be safe. Permissions such as administer nodes set restrict access because they have security implications. Grant them to trusted roles only.

For marketing and content teams

When a button, menu entry or page is missing for you, a missing permission is the first thing to rule out. Give your developers the exact task you cannot do, for example publish a page, and they will find the permission on the Permissions page and decide which role should hold it. The titles on that page, such as Administer users, are what you can quote in a ticket. You can also ask which role carries them.

Sources

• Drupal User Guide: Concept: Users, roles and permissions
• Drupal User Guide: Assigning permissions to a role
• PermissionHandler, Drupal core source
• Node module permissions file, Drupal core source
• PermissionAccessCheck, Drupal core source (11.2.0)
• UserPermissionsForm, Drupal core source (11.2.0)
• User module routing, Drupal core source (11.2.0)
• PermissionChecker, Drupal core source (11.2.0)
• Role entity class, Drupal core source
• System module permissions file, Drupal core source (11.2.0)
• SuperUserAccessPolicy, Drupal core source (11.2.0)
• Core services, security.enable_super_user parameter (11.2.0)