Drupal 8  8.0.2
User accounts, permissions, and roles

Data Structures

interface  AccountInterface
interface  AccountProxyInterface
interface  AccountSwitcherInterface
interface  RoleInterface
interface  UserInterface

Detailed Description

API for user accounts, access checking, roles, and permissions.

Overview and terminology

Drupal's permission system is based on the concepts of accounts, roles, and permissions.

Users (site visitors) have accounts, which include a user name, an email address, a password (or some other means of authentication), and possibly other fields (if defined on the site). Anonymous users have an implicit account that does not have a real user name or any account information.

Each user account is assigned one or more roles. The anonymous user account automatically has the anonymous user role; real user accounts automatically have the authenticated user role, plus any roles defined on the site that they have been assigned.

Each role, including the special anonymous and authenticated user roles, is granted one or more named permissions, which allow them to perform certain tasks or view certain content on the site. It is possible to designate a role to be the "administrator" role; if this is set up, this role is automatically granted all available permissions whenever a module is enabled that defines permissions.

All code in Drupal that allows users to perform tasks or view content must check that the current user has the correct permission before allowing the action. In the standard case, access checking consists of answering the question "Does the current user have permission 'foo'?", and allowing or denying access based on the answer. Note that access checking should nearly always be done at the permission level, not by checking for a particular role or user ID, so that site administrators can set up user accounts and roles appropriately for their particular sites.

Defining a new plugin type

Modules define permissions via a $module.permissions.yml file. See for documentation of permissions.yml files.

Access checking on entities

Depending on the situation, there are several methods for ensuring that access checks are done properly in Drupal:

User and role objects

User objects in Drupal are entity items, implementing . Role objects in Drupal are also entity items, implementing . See the Entity API topic for more information about entities in general (including how to load, create, modify, and query them).

Roles often need to be manipulated in automated test code, such as to add permissions to them. Here's an example:

$role = \Drupal\user\Entity\Role::load('authenticated');
$role->grantPermission('access comments');

Other important interfaces: