# Синтаксис правил политик

Статья описывает, как устроено дерево политик и как записывать правила: субъект, объект, действие, дополнительные условия и алгоритм комбинирования. Перечень соответствует реализации в **Webim** [10.8](https://webim.ru/webim-10-8/).

Основы ABAC — в статье [Базовые понятия](https://webim.ru/kb/for-admins/access-control-system/base.html). Формальная грамматика языка выражений — в статье [Выражения](https://webim.ru/kb/for-admins/access-control-system/expressions.html). Как открыть редактор и собрать роль с нуля — в статье [Редактор политик](https://webim.ru/kb/for-admins/service-pages/policies-editor.html). Ключи функций и прочих констант — в статье [Атрибуты и известные константы](https://webim.ru/kb/for-admins/access-control-system/available-attributes.html).

!!! Warning "Внимание!"
    Редактор политик и пользовательские роли доступны при подключении [тарифной опции](https://webim.ru/price/) управления политиками. По умолчанию править дерево может только *Администратор*.

## Иерархия дерева политик

Дерево политик отвечает на запрос доступа одним из решений: **Разрешить** (`permit`), **Запретить** (`deny`), **Не применимо** (`not_applicable`) или **Ошибка, решение не определено** (`indeterminate`). Дерево собирается из трёх типов элементов.

```
Группа политик (PolicySet)
|-- Группа политик
|   `-- Политика
|       |-- Правило
|       `-- Правило
`-- Политика
    `-- Правило
        |-- Назначение: субъект, действие, объект
        |-- Дополнительные условия
        `-- Эффект: разрешить или запретить
```

  * **Группа политик** — контейнер. В неё входят политики и другие группы. У группы есть **назначение** (когда контейнер применим к запросу) и **алгоритм комбинирования** (как сложить ответы вложенных элементов). Эффекта у группы нет.

  * **Политика** — контейнер правил. У политики тоже есть назначение и алгоритм комбинирования. Эффекта нет: решение даёт алгоритм по вложенным правилам.

  * **Правило** — атомарная проверка. У правила есть назначение, дополнительные условия и **эффект** (**Разрешить** или **Запретить**). Алгоритма комбинирования у правила нет.

Пустое назначение у группы или политики означает: контейнер применим к **любому** запросу. Пустые назначение и условия у правила означают: правило применимо всегда и сразу возвращает свой эффект.

Все выражения назначения и условий одного элемента объединяются логическим **И**. Если хотя бы одно выражение ложно, элемент отвечает **Не применимо**. Если вычисление выражения падает с ошибкой типов или путём, элемент отвечает **решение не определено**.

Порядок элементов в дереве важен: алгоритмы просматривают вложенные элементы **сверху вниз**. Новые элементы создаются выключенными и в решении не участвуют, пока их не включат через контекстное меню.

## Как редактор собирает правило

Форма правила содержит поля **Кто делает запрос**, **Над чем запрос**, **Действие**, **Дополнительные условия** и **Эффект**. Конструктор записывает их в выражения языка политик и при сохранении делит на две группы:

  * **простые** выражения попадают в назначение (`target`);

  * **сложные** — в дополнительные условия (`condition`).

На результат проверки это не влияет: и те и другие должны быть истинны. Разница важна для политик и групп: в их назначении допускаются **только простые** выражения. Сложное выражение в назначении политики или группы редактор и сервер отклонят.

Простое выражение — сравнение атрибута с константой или списком констант, без функций и без сравнения двух атрибутов. Например, `subj.type = 'agent'` и `'supervisor' in subj.roles` — простые. `subj = obj`, `intersects(...)` и `not(...)` — сложные.

Конструктор покрывает только простые проверки. Всё, что сравнивает две сущности, обращается к окружению (`env.*`) или вызывает функцию, нужно писать вручную в **Дополнительных условиях**.

## Субъект: кто делает запрос

Субъект (`subj`) — сотрудник, который запрашивает действие. В списке **Кто делает запрос** доступен один тип.

| Название в редакторе | Выражение | Кто это |
|----------------------|-----------|---------|
| Сотрудник | `subj.type = 'agent'` | Оператор, супервизор, администратор или сотрудник с пользовательской ролью |
| Ничего не выбрано | *(проверка `subj.type` не добавляется)* | Субъект любого типа |

Других значений в конструкторе нет. Служебный субъект `system` (фоновые задачи сервера) через дерево политик не проходит: такие запросы сразу получают разрешение. Писать `subj.type = 'system'` в правиле незачем.

### Атрибуты сотрудника

Один и тот же набор доступен и у субъекта (`subj.*`), и у объекта с типом `agent` (`obj.*`).

| Атрибут | Тип                           | Откуда | Описание                                                                                                                                             |
|---------|-------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| `type` | строка                        | список субъекта / объекта | Всегда `'agent'`                                                                                                                                     |
| `id` | число                         | только условия | Идентификатор сотрудника. Сравнение со строковым литералом даёт ошибку вычисления выражения                                                          |
| `roles` | список строк                  | кнопка **Добавить** у субъекта или у объекта **Сотрудник** | Ключи ролей. Системные: `admin`, `supervisor`, `operator`. У пользовательской роли в выражении используется **идентификатор**, а не отображаемое имя |
| `departments.all` | список сущностей `department` | только условия | Все отделы сотрудника                                                                                                                                |
| `departments.subordinate` | список сущностей `department` | только условия | Подревизные отделы. Признак подревизности ставится в карточке сотрудника для конкретной связи с отделом                                              |

Примеры:

```
'supervisor' in subj.roles
intersects(subj.roles, ['admin', 'supervisor'])
'power_agent' in subj.roles
subj = obj
```

`subj = obj` истинно, когда сотрудник действует сам над собой (например, правит свой профиль). Это сравнение двух сущностей — его нельзя собрать конструктором.

## Объект: над чем запрос

Объект (`obj`) — ресурс, к которому запрашивается доступ: страница, сотрудник, отдел, диалог и т. д. Значение в списке **Над чем запрос** задаёт `obj.type`. **Ничего не выбрано** означает «любой объект». Можно выбрать несколько типов — редактор запишет `obj.type in [...]`.

Для части типов конструктор позволяет добавить атрибут (роль, ключ функции, секцию РМО). Остальные атрибуты в списке не показываются: их используют только в **Дополнительных условиях**.

CRUD в таблице — это `create`, `read`, `update`, `delete`.

Несколько типов в одном правиле:

```
obj.type in ['agent', 'department']
```

Тип, которого нет в списке, можно указать вручную в условиях, например `obj.type = 'channel'`. Такие объекты есть у системных ограничений (канал, счёт, состояние дерева политик). Для настройки ролей обычно достаточно типов из конструктора.

Полный перечень атрибутов объектов и ключей `ui.*` / `api.*` — в статье [Атрибуты и известные константы](https://webim.ru/kb/for-admins/access-control-system/available-attributes.html).

## Действия

Действие (`action.type`) — что именно запрашивают над объектом. Список **Действие** зависит от выбранного объекта.

Несколько действий — значок множественного выбора:

```
action.type in ['read', 'update']
```

Дополнительный атрибут, которого нет в конструкторе:

| Атрибут | Тип | Описание |
|---------|-----|----------|
| `action.tags` | список строк | Метки запроса. В системных политиках встречается тег `stats` — чтение данных для статистики |

```
'stats' not in action.tags
```

Чтобы сотрудник увидел раздел и смог в нём работать, обычно нужны **два слоя**: доступ к функции (`action.type = 'access'`, `obj.type = 'feature'`, ключи `ui.*` и `api.*`) и действие над самой сущностью (`read` / `update` / `disconnect` и т. д.).

## Условия: полный синтаксис

Поле **Дополнительные условия** — многострочный ввод. Одна строка — одно выражение. Пустые строки игнорируются. Все непустые строки объединяются через **И**: правило применимо, только если истинна каждая.

Результатом выражения должно быть `true` или `false`. Иначе вычисление даёт ошибку типов, и элемент отвечает **решение не определено**.

### Литералы и имена

| Что | Запись (пример)                             | Замечания                                                            |
|-----|---------------------------------------------|----------------------------------------------------------------------|
| Строка | `'оператор'` или `"оператор"`               | Кавычки одного вида. Внутри можно экранировать ту же кавычку: `"\""` |
| Целое | `0`, `42`                                   | Ведущие нули запрещены (`01` — синтаксическая ошибка)                |
| Дробное | `1.5`                                       | Цифры после точки обязательны                                        |
| Логическое | `true`, `false`                             | Используйте только строчные буквы (нижний регистр)                   |
| Пустое значение | `null`                                      | Используйте только строчные буквы (нижний регистр)                                                     |
| Список | `['read', 'update']`, `[]`                  | Только литералы, типы в одном списке можно смешивать                 |
| Имя | `subj`, `departments`, `power_agent` | Латиница, `_`; после первого символа допустимы цифры                 |

Имена атрибутов, как и имена функций (`not`, `length`, `intersects`), **чувствительны к регистру** и пишутся как в справочнике: `subj.roles` верно, `Subj.Roles` даст ошибку пути. Используйте нижний регистр. Ключевые слова (`in`, `not in`, `true`, `null`) от регистра не зависят.

Обращение к атрибуту — через точку: `subj.roles`, `obj.departments.all`, `env.tariff.enabled_options`.

### Логические операторы

| Запись | Смысл | Операнды |
|--------|-------|----------|
| `=` / `!=` | равно / не равно | числа, строки, логические, `null`, две конкретные сущности одного типа |
| `>`, `>=`, `<`, `<=` | сравнение порядка | только числа (`integer` и `float` можно сравнивать между собой) |
| `in` / `not in` | входит / не входит в список | слева — атомарное значение или сущность, справа — список. Пробелы внутри `not in` не важны |

Нельзя сравнивать два списка оператором `=` (`[1, 2] = [1, 2]` — ошибка типов). Для пересечения списков используйте `intersects`.

`in` справа принимает только список: `obj.key in 'queue'` редактор не примет. Правильно: `obj.key = 'queue'` или `obj.key in ['queue']`. Наоборот, сравнение с списком без `in` тоже неверно: `action.type = ['read', 'update']`. Правильно: `action.type in ['read', 'update']`.

При проверке `in` несовместимые типы внутри списка не дают ошибку: `'foo' in [1, 2, 'foo']` истинно, `1 in subj.departments.all` ложно (число не равно сущности отдела).

### Функции

Полный список доступных функций:

| Функция | Сигнатура | Смысл |
|---------|-----------|--------|
| `not(x)` | `boolean → boolean` | Отрицание |
| `length(list)` | `list → integer` | Число элементов |
| `intersects(a, b)` | `(list, list) → boolean` | Есть хотя бы один общий элемент |

Вызов функции сам по себе может быть выражением, только если возвращает `boolean` (`not(...)`, `intersects(...)`). `length(...)` нужно сравнивать с числом:

```
length(subj.departments.all) > 0
length(obj.departments.all) = 0
```

Проверка пересечения отделов субъекта и объекта:

```
intersects(subj.departments.subordinate, obj.departments.all)
```

Это не то же самое, что `obj in subj.departments.subordinate`. Первое сравнивает два списка отделов (типично, когда объект — сотрудник). Второе проверяет, что сам объект-отдел входит в подревизные отделы субъекта.

### Простые и сложные выражения

Простые (можно оставить в назначении политики и в конструкторе):

```
subj.type = 'agent'
action.type = 'disconnect'
obj.type = 'agent'
obj.name = 'ui.agents'
obj.name in ['ui.agents', 'api.agents']
'power_agent' in subj.roles
```

Сложные (только в **Дополнительных условиях** правила):

```
subj = obj
subj != obj
obj in subj.departments.subordinate
intersects(subj.departments.subordinate, obj.departments.all)
not(intersects(obj.roles, ['admin', 'supervisor']))
not(env.config.operator_status_timer)
env.config.hide_common_queue
```

Булевый атрибут можно использовать как целое выражение: `env.config.hide_common_queue` означает «настройка включена».

### Сравнение сущностей

Сущность — значение с типом и идентификатором, например сотрудник `(type=agent, id=12)` или отдел `(type=department, id=3)`.

  * `subj = obj` истинно, если совпадают **и** тип, **и** идентификатор.

  * Сравнивать конкретную сущность с «типом без id» нельзя — будет ошибка типов.

  * Сущность можно проверять на вхождение в список сущностей: `obj in subj.departments.all`.

  * Вложенные сущности разворачиваются через точку: `obj.agent` у связи с отделом, `obj.owner` у диалога, `obj.assigned_operator` у сеанса посетителя.

### Окружение

Окружение (`env`) в списках субъекта и объекта не выбирается. Обращения к нему пишутся только в условиях.

| Атрибут | Тип | Описание |
|---------|-----|----------|
| `env.tariff.enabled_options` | список строк | Ключи включённых тарифных опций |
| `env.config.operator_department_prioritization` | boolean | Приоритизация отделов |
| `env.config.operator_status_timer` | boolean | Таймер статуса сотрудника |
| `env.config.restricted_options` | список строк | Тарифные опции, запрещённые текущим ролям субъекта |
| `env.config.hide_common_queue` | boolean | Скрывать общую и офлайн-очереди в РМО |
| `env.config.hide_anothers_chats` | boolean | Скрывать чужие диалоги в РМО |
| `env.config.hide_others` | boolean | Скрывать секцию **Остальные** |
| `env.capabilities.available` | список строк | Возможности, доступные на этом сервере |

Пример системного ограничения «функция выключена в тарифе»:

```
obj.tariff_option != null
obj.tariff_option not in env.tariff.enabled_options
```

Группа **Супервизор** в поставке сама проверяет, что опция супервизоров включена:

```
'has_supervisors' in env.tariff.enabled_options
```

Полный список ключей тарифа и опций `env.config` — в статье [Атрибуты и известные константы](https://webim.ru/kb/for-admins/access-control-system/available-attributes.html).

## Алгоритм комбинирования: полный синтаксис

Алгоритм задаётся у **политики** и у **группы политик** (поле **Алгоритм комбинирования**). У правила этого поля нет. Новая политика и новая группа получают алгоритм **Запретить, если не разрешено** (`deny_unless_permit`).

Алгоритм решает, как из ответов вложенных элементов получить один ответ. Элементы просматриваются сверху вниз — в том порядке, в каком они стоят в дереве. Выключенный элемент в просмотр не входит.

| Название в редакторе | Идентификатор | Как выбирается решение |
|----------------------|---------------|------------------------|
| Запрет переопределяет | `deny_overrides` | Просмотр идёт до первого **Запретить**. Если хотя бы один применимый элемент вернул запрет, итог — **Запретить**. Иначе, если была ошибка вычисления, итог — **решение не определено**. Иначе, если есть **Разрешить**, итог — **Разрешить**. Если никто не применился — **Не применимо** |
| Разрешение переопределяет | `permit_overrides` | Симметрично предыдущему: просмотр идёт до первого **Разрешить**. Достаточно одного разрешения. Запрет учитывается, только если разрешений нет. Ошибка вычисления важнее запрета |
| Запретить, если не разрешено | `deny_unless_permit` | Итог **Разрешить**, только если нашлось хотя бы одно разрешение. Во всех остальных случаях, в том числе когда никто не применился, итог — **Запретить**. «Закрыто по умолчанию» |
| Разрешить, если не запрещено | `permit_unless_deny` | Итог **Запретить**, только если нашёлся хотя бы один запрет. Иначе — **Разрешить**, даже если никто не применился. «Открыто по умолчанию» |
| Первый применимый элемент | `first_applicable` | Берётся решение **первого** сверху элемента, который применим к запросу (не **Не применимо**). Остальные не смотрятся. Порядок в дереве критичен |
| Только один применимый элемент | `only_one_applicable` | Если применим ровно один элемент — берётся его решение. Если применимых нет — **Не применимо**. Если применимы двое или больше — **решение не определено** |

Практические следствия:

  * Корневая группа системного дерева использует **Запретить, если не разрешено**: нет явного разрешения — доступ закрыт.

  * Группа **Разрешения сотрудников по ролям** использует **Первый применимый элемент**. Сверху администратор, затем супервизор, затем оператор. Группа **Оператор** подходит **любому** сотруднику (`subj.type = 'agent'`), поэтому пользовательскую роль нужно ставить **выше** группы **Оператор**. Иначе её правила не будут учитываться.

  * Для набора запретов (тариф, возможности сервера) удобен **Запрет переопределяет**: один запрещающий элемент перекрывает разрешения.

  * Надстройка «как оператор, плюс одно право» требует алгоритма **Первый применимый элемент** и у группы роли, и у политики внутри. Если оставить значение по умолчанию **Запретить, если не разрешено**, политика с широким назначением ответит запретом на всё, о чём в ней нет разрешающего правила, и до системного оператора запрос не дойдёт.

  * **Только один применимый элемент** смотрит применимость по **назначению**, без дополнительных условий. Два правила с одинаковым назначением и разными условиями при этом алгоритме дадут ошибку, а не «сработает то, чьи условия подошли». Для политик с несколькими правилами на одно действие используйте **Запретить, если не разрешено**.

Формальные определения совпадают с приложением C стандарта [XACML 3.0](http://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html#_Toc325047268). В **Webim** все алгоритмы считаются упорядоченными: элементы всегда просматриваются в порядке дерева.

## Пример: особый оператор может отключать операторов своих отделов

Задача: завести роль *Особый оператор*, которая работает как обычный оператор, но может [отключать операторов в отделах, в которых сам состоит](https://webim.ru/kb/for-admins/registration-agents-and-supervisors.html) — переводить их в статус *Офлайн*. Самого себя, администраторов и супервизоров отключать нельзя. Обычные операторы и системный супервизор остаются как были.

У обычного оператора нет ни `disconnect`, ни чтения профайлов других сотрудников. В списке сотрудников он видит себя, коллег из общих отделов и сотрудников без отделов. Поэтому кроме правила на `disconnect` нужно правило на `read` по своим отделам. Страницу **Сотрудники** копировать не нужно: `ui.agents` и `api.agents` уже есть у системной группы **Оператор**, оттуда роль возьмёт и остальное.

### 1. Создать роль

В разделе **Команда → Роли** создайте роль. Название — *Особый оператор*, идентификатор — `power_agent`. Идентификатор задаётся один раз и именно его пишут в выражениях.

### 2. Создать группу политик

В разделе **Команда → Политики** в группе **Разрешения сотрудников по ролям** добавьте вложенную группу *Особый оператор*.

Назначение группы (конструктор + условие):

  * **Кто делает запрос** — *Сотрудник*;

  * **Дополнительные условия**:

```
'power_agent' in subj.roles
```

Это простое выражение, его можно оставить в назначении группы.

**Алгоритм комбинирования** смените с предложенного по умолчанию на **Первый применимый элемент**. Поднимите группу **выше** группы **Оператор**. Пока внутри нет правил, группу не включайте.

Если оставить алгоритм по умолчанию **Запретить, если не разрешено**, сотрудник с новой ролью получит отключение операторов и **потеряет чат, профиль и всё остальное**: группа применится и запретит любой запрос, для которого внутри нет разрешения.

### 3. Политика «Сотрудники»

В группу добавьте политику *Сотрудники*.

  * **Кто делает запрос** — *Сотрудник*;

  * **Над чем запрос** — *Сотрудник*;

  * **Действие** — *Любое* (или не выбирайте действие: проверку `action.type` политика не ставит, её поставят правила);

  * **Алгоритм комбинирования** — **Первый применимый элемент**.

Назначение, которое запишет редактор:

```
subj.type = 'agent'
obj.type = 'agent'
```

### 4. Правило «Читать сотрудников своих отделов»

Без чтения другой оператор может не появиться в списке, и отключать будет некого.

  * **Кто делает запрос** — *Сотрудник*;

  * **Над чем запрос** — *Сотрудник*;

  * **Действие** — *Прочитать*;

  * **Эффект** — *Разрешить*;

  * **Дополнительные условия**:

```
intersects(subj.departments.all, obj.departments.all)
```

Это сложное выражение: функция и два атрибута. Конструктор его не соберёт.

### 5. Правило «Отключать других операторов своих отделов»

Это то правило, ради которого заведена роль.

  * **Кто делает запрос** — *Сотрудник*;

  * **Над чем запрос** — *Сотрудник*;

  * **Действие** — *Переключить в офлайн*;

  * **Эффект** — *Разрешить*;

  * **Дополнительные условия** — три строки, все должны быть истинны одновременно:

```
subj != obj
not(intersects(obj.roles, ['admin', 'supervisor']))
intersects(subj.departments.all, obj.departments.all)
```

Что проверяет каждая строка:

| Выражение                                              | Зачем                                                                                                                 |
|--------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| `subj != obj`                                          | Нельзя отключить самого себя                                                                                          |
| `not(intersects(obj.roles, ['admin', 'supervisor']))`  | Нельзя отключить администратора и супервизора. Отключать можно другого оператора или сотрудника пользовательской роли |
| `intersects(subj.departments.all, obj.departments.all)` | У объекта есть хотя бы один отдел, общий с субъектом.                                                                 |

Назначение, которое запишет конструктор:

```
subj.type = 'agent'
action.type = 'disconnect'
obj.type = 'agent'
```

Кнопка **Отключить всех операторов** над списком проверяет `disconnect` для сотрудника *без конкретного id*. У такого объекта нет списка отделов, третье условие ложно, массовое отключение эта роль не получит — только точечное.

### 6. Включить ветку и назначить отделы

Включайте снизу вверх: оба правила, политику, группу. Назначьте тестовому сотруднику **только** роль *Особый оператор*. В карточке этого сотрудника подготовьте список отделов.

Проверьте вход тестовой учётной записью:

  * в списке **Сотрудники** видны другие операторы своих отделов, и у них доступна пиктограмма отключения;

  * у администратора и супервизора пиктограммы нет;

  * оператор из чужого отдела не отключается;

  * чат, свой профиль и остальное операторское поведение сохранились: эти запросы группа *Особый оператор* не ловит и отдаёт системному **Оператору**.

Если сотрудник ведёт себя как обычный оператор, группа либо выключена, либо стоит ниже **Оператор**, либо в назначении опечатка в идентификаторе роли. Если пропал чат — у группы или политики остался алгоритм **Запретить, если не разрешено**.

## См. также

  * [Базовые понятия ABAC](https://webim.ru/kb/for-admins/access-control-system/base.html)

  * [Выражения](https://webim.ru/kb/for-admins/access-control-system/expressions.html)

  * [Атрибуты и известные константы](https://webim.ru/kb/for-admins/access-control-system/available-attributes.html)

  * [Редактор политик](https://webim.ru/kb/for-admins/service-pages/policies-editor.html)

  * [Добавление/удаление/редактирование ролей](https://webim.ru/kb/for-admins/add-delete-roles.html)

  * [Роли](https://webim.ru/kb/for-admins/roles.html)

---

Источник: https://webim.ru/kb/for-admins/access-control-system/policy-syntax.html
