General concept

The Main module version 20.0.1200 adds API handling new access permissions.

The library is designed to simplify and streamline handling of user access permissions in modules.

Terminology

Term	Description
User	Authenticated user. Must have unique idenfier (id).
User group	Collection of users, provided by the module: administrators, employees and etc.
Access code	Collection of users unified by a specific criteria. For example: users, as members in a specific workgroup; department members and etc. Provided by the main module and stored in the table b_user_access.
Action	Action (operation), performed by user. For example: saving of an entry.
Permission	Specific access permission, provided to a user. For example: editing of one's record/entries or editing of all records.
Access permission	Set of logic for granting permissions to a user as well as other factors, permitting/denying execution of selected action.
Role	Association between access codes and selected access permissions.

General concept

The following rule-based model was taken as the basis for implementing selection management:

Generated list of actions to be performed by the user;
Generated list of permissions that may be enabled for a user;
Each action have a described access permission (based on permissions or some other factors);
Input-data base controller (action, user or any other additional information) finds a required rule, executes it and returns a result;
Customer code defines what is to be done with the result.

System of access permissions can be independent in each module, with its own set of actions, permissions and rules, and with its own tables in the database for storage of settings. General API provides a unified approach, with necessary classes and methods. However, their use is optional.

Handling the database

Standard concept , что each module will store roles and access permissions in its tables. API provides base classes for simplifying handling of ORM:

Class	Description
`Bitrix\Main\Access\Permission\AccessPermissionTable`	Class handles table for storage of permissions. Supports permissions hierarchy and contains necessary checks.
`Bitrix\Main\Access\Role\AccessRoleTable`	Class handles table for fields.
`Bitrix\Main\Access\Role\AccessRoleRelationTable`	Class handles table for storage bindings between roles an users (user access codes).

Role

Role is used for establishing connection between user access codes and permissions. When a user has several roles, this user gets all permissions, available for these roles (accumulated permissions).

User may not have any role and have an option to perform some actions, defined by a rule for this action. The rule can also consider the issued permissions, but also may be independent from them altogether.

Permissions

List of permissions is handled by the base dictionary class Bitrix\Main\Access\Permission\PermissionDictionary, providing methods for:

getting list with all permissions;
getting names, hints and their translations;
handing hierarchy of permissions (see. below).

Such options ensure that these permissions are entered into dictionary as constants. Similar example can be viewed in the module tasks: Bitrix\Tasks\Access\Permission\PermissionDictionary.

Permissions hierarchy

Bitrix24 Self-hosted supports an option to create permissions that depend on other permissions. For example, let's take the following set of permissions:

Record editing

Editing records in your department;
Editing all records.

You cannot enable the other two permissions without enabling the Edit records permissions. Disabling the Edit records permission automatically disables all dependant permissions as well.

From technical point of view, this is implemented using a special format of values in PermissionDictionary (uses material path notation), with unlimited nesting depth. For example:

const
  PERMISSION_EDIT = '1',
  PERMISSION_EDIT_DEPARTMENT = '1.1',
  PERMISSION_EDIT_ALL = '1.2';

Separately, it must be noted why such specific record is used:

constants are easily traced by code using IDE;
doesn't require additional parent record;
this format is compact in general and convenient for writing this dictionary and reading by a user.

Controller

Front controller verifies access permissions within module, via AccessibleController interface. It also serves as descendant of BaseAccessController.

You need to create a custom controller in each module. In minimal case, its sufficient to inherit from BaseAccessController and implement two methods:

protected function loadItem(int $itemId = null): AccessibleItem
{
   //...
}

protected function loadUser(int $userId): AccessibleUser
{
   //...
}

Base controller provides two methods of use (i. e. for tasks module).

Full (employed models are described below):

$userModel = UserModel::createFromId($userId);
$item = TaskModel::createFromId($taskId);
$params = [];
$result = (new TaskAccessController($userModel))->check($action, $item, $params);

and Simplified:

$result = TaskAccessController::can($userId, $action, $itemId, $params);

Additionally, you have an option to perform batch access permission check for actions with an individual entity:

$request = [
  $actionId => $params
];
$result = (new TaskAccessController($userModel))->batchCheck($request, $item);

Such query response returns an array $actionId => $result

The controller implements a static cache for user, allowing to reduce the number of database queries. Use the method getInstance($userId) to get an already created instance.

Models

Access permissions check at the base levels operates with two models:

AccessibleUser - provides necessary information and methods about user who performs an action. For convenience, use the base class UserModel. UserModel can be created based on user id or completed with properties manually.
AccessibleItem - entity model, subject to the performed actions.

UserModel in Bitrix24 Self-hosted provides methods, convenient for use in the following rules:

isAdmin() - check user for administrator status;
getPermission(string $permissionId) - value of indicated permission for user;
getUserDepartments() - list of user departments;
getAccessCodes() - list of user access codes;
getSubordinate($userId) - relations in company hierarchy with specified user (find more details below).

Bitrix\Main\Access\User\UserSubordinate

Helper class, provides a convenient handling of hierarchy in the company. It is needed as being one of most frequent scenarios: user supervisor must have no less access permissions than the user itself.

UserSubordinate::getSubordinate($userId) - allows defining a user's position relatively to the current user.

Possible variants:

UserSubordinate::RELATION_HIMSELF - the same person;
UserSubordinate::RELATION_DEPARTMENT - one department employees;
UserSubordinate::RELATION_SUBORDINATE - subordinate;
UserSubordinate::RELATION_DIRECTOR - supervisor;
UserSubordinate::RELATION_OTHER_DIRECTOR - supervisor for another department;
UserSubordinate::RELATION_OTHER - all the rest (can be retrieved, if for example, module intranet isn't installed).

Trapping

Event-handling system is available for expanding the trap feature:

Event	Description
`Bitrix\Main\Access\Event\EventDictionary::EVENT_ON_BEFORE_CHECK`	Called before checking access permissions for specific rule.
`Bitrix\Main\Access\Event\EventDictionary::EVENT_ON_AFTER_CHECK`	Called after triggered check for specific rule.

The event passes the following set of parameters:

[
   'user' // AccessibleUser
   'item' // AccessibleItem
   'action' // string action, executed by the user
   'params' // misc any additional parameters
   'isAccess' // null|bool result of rule
]

Each handler, that got stuck at an event - must return the object Bitrix\Main\Access\Event\EventResult. Any other values will be ignored.

If at least one of handlers has returned a restriction, access will be denied. Additionally, if the event onBeforeCheck returns a specific result, performance is interrupted and controller returns the result.