Role

A role in Drupal is a named group of permissions, such as editor or moderator. You assign roles to user accounts instead of granting permissions to each person. An account can hold several roles and receives the permissions of every one of them. Roles are configuration, so they travel with the rest of your site setup.

How it works in Drupal 11

A role is an entity of the type user_role, implemented by Drupal\user\Entity\Role. It is a configuration entity with the prefix role, so a role with the ID editor is stored as user.role.editor. Its exported properties are id, label, weight, is_admin and permissions. The weight sets the order in lists; a new role without one is placed last.

The methods on RoleInterface include grantPermission(), revokePermission(), hasPermission() and getPermissions(). When Drupal asks whether an account may do something, UserRolesAccessPolicy loads the roles listed in getRoles() for that account and collects the permissions of each one.

Two roles are built in. Anonymous user covers visitors who are not logged in, and Authenticated user is added to every logged-in account. The Standard profile also ships Content editor and Administrator roles. When a role is flagged is_admin, it receives all permissions automatically, and the Permissions page shows its column as checked and disabled. The Role settings page at /admin/people/role-settings chooses the administrator role; the anonymous and authenticated roles are not offered there.

Roles also track their modules. A role depends on every module that provides one of its permissions, and when that module is uninstalled, the permissions it provided are removed from the role.

Example

Go to People › Roles (/admin/people/roles), add a role and type a name such as Blog editor. The form shows a role name (up to 64 characters) and a machine name, which is locked once the role exists. Then set its permissions at /admin/people/permissions/blog_editor, and assign the role on a user's edit form or with the bulk action on the People page. In code:

$role = \Drupal\user\Entity\Role::load('blog_editor');
        $role->grantPermission('access content');
        $role->save();

Common mistakes

• Naming roles after people. A role called Anna cannot be reused. Name roles after the task, such as Content editor or Vendor.
• Handing out the Administrator role as the quick fix. It carries every permission. Add the specific permission to a narrower role instead.
• Granting too much to Authenticated user. That role reaches every logged-in account.
• Forgetting the configuration export. Permission changes live in role configuration, so include them when you export configuration.

For marketing and content teams

Describe your work to your developers in tasks: create landing pages, publish blog posts, review translations. They map those tasks to a role and its permissions. The Drupal User Guide shows the pattern with a Vendor role that can create recipes and edit or delete its own. A role that fits your task is safer for the site than the Administrator role, and it is easier to review later.

Sources

• Drupal User Guide: Concept: Users, roles and permissions
• Drupal User Guide: Creating a role
• Drupal User Guide: Assigning permissions to a role
• RoleInterface, Drupal core source
• Role entity class, Drupal core source
• User module routing, Drupal core source (11.2.0)
• RoleForm, Drupal core source (11.2.0)
• RoleSettingsForm, Drupal core source (11.2.0)
• UserRolesAccessPolicy, Drupal core source (11.2.0)
• Drupal User Guide: Changing a user's roles
• User module: authenticated role configuration (11.2.0)
• Standard profile: content editor role configuration (11.2.0)