Перейти к содержанию

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

Статья описывает, как устроено дерево политик и как записывать правила: субъект, объект, действие, дополнительные условия и алгоритм комбинирования. Перечень соответствует реализации в 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. Включить ветку и назначить отделы

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

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

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

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

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

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

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

См. также