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

General concept

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

1. Generated list of actions to be performed by the user;
2. Generated list of permissions that may be enabled for a user;
3. Each action have a described access permission (based on permissions or some other factors);
4. Input-data base controller (action, user or any other additional information) finds a required rule, executes it and returns a result;
5. 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:

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:

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.