Синтаксис правил политик
Статья описывает, как устроено дерево политик и как записывать правила: субъект, объект, действие, дополнительные условия и алгоритм комбинирования. Перечень соответствует реализации в Webim 10.8.
Основы ABAC — в статье Базовые понятия. Формальная грамматика языка выражений — в статье Выражения. Как открыть редактор и собрать роль с нуля — в статье Редактор политик. Ключи функций и прочих констант — в статье Атрибуты и известные константы.
Внимание!
Редактор политик и пользовательские роли доступны при подключении тарифной опции управления политиками. По умолчанию править дерево может только Администратор.
Иерархия дерева политик
Дерево политик отвечает на запрос доступа одним из решений: Разрешить (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.* — в статье Атрибуты и известные константы.
Действия
Действие (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 — в статье Атрибуты и известные константы.
Алгоритм комбинирования: полный синтаксис
Алгоритм задаётся у политики и у группы политик (поле Алгоритм комбинирования). У правила этого поля нет. Новая политика и новая группа получают алгоритм Запретить, если не разрешено (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. В Webim все алгоритмы считаются упорядоченными: элементы всегда просматриваются в порядке дерева.
Пример: особый оператор может отключать операторов своих отделов
Задача: завести роль Особый оператор, которая работает как обычный оператор, но может отключать операторов в отделах, в которых сам состоит — переводить их в статус Офлайн. Самого себя, администраторов и супервизоров отключать нельзя. Обычные операторы и системный супервизор остаются как были.
У обычного оператора нет ни 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. Включить ветку и назначить отделы
Включайте снизу вверх: оба правила, политику, группу. Назначьте тестовому сотруднику только роль Особый оператор. В карточке этого сотрудника подготовьте список отделов.
Проверьте вход тестовой учётной записью:
-
в списке Сотрудники видны другие операторы своих отделов, и у них доступна пиктограмма отключения;
-
у администратора и супервизора пиктограммы нет;
-
оператор из чужого отдела не отключается;
-
чат, свой профиль и остальное операторское поведение сохранились: эти запросы группа Особый оператор не ловит и отдаёт системному Оператору.
Если сотрудник ведёт себя как обычный оператор, группа либо выключена, либо стоит ниже Оператор, либо в назначении опечатка в идентификаторе роли. Если пропал чат — у группы или политики остался алгоритм Запретить, если не разрешено.