База знаний Зодиак.АйТиЭм

Как настроить роли с использованием различных SSO

Описание ролевой модели в Zodiac. Встроенные роли. Взаимодействие с SSO-провайдерами.

Настройка ролей

Описание ролевой модели в Zodiac

Система Zodiac может работать как с ролевой моделью, так и без ролевой модели в зависимости от настроек в administration.ini
После включении ролевой модели Zodiac, роли (и/или другие атрибуты) заводятся в SSO провайдере (KeyCloak, Avanpost и т.п.)
А в Zodiac настраивается своя роль - которая является маппингом различных разрешений на заведённые в SSO роли (и/или другие атрибуты).

Встроенные роли

Супер администратор - имеет полный доступ к Zodiac.
Администратор ролей - имеет доступ к управлению маппингом ролей в Zodiac.
Это встроенные роли, которые предусмотрены в системе для работы в Zodiac до того как вы настроите свою ролевую модель и ещё для некоторых операций (например редактировать маппинг ролей в Zodiac может только Супер администратор или Администратор ролей).

Маппинг этих ролей указывается в конфигурации /var/zodiac/administration-server/administration.ini
Там же включается ролевая модель
Рассмотрим пример секции ролевой модели из /var/zodiac/administration-server/administration.ini

[Roles]
Enabled = true
SaExprs = "$.resource_access.zodiac.roles[?(@ == 'zodiac_ac_sa')];$.roles[?(@ == 'zodiac_ac_sa')]"
RaExprs = "$.resource_access.zodiac.roles[?(@ == 'zodiac_ac_ra')];$.roles[?(@ == 'zodiac_ac_ra')]"

Enabled - описывает включена ли ролевая модель.
SaExprs - jsonpath выражение для jwt токена которое определяет принадлежность к роли супер администратора.
RaExprs - jsonpath выражение для jwt токена которое определяет принадлежность к роли администратора ролей.
При использовании указанных в примере SaExprs и RaExprs требуется завести роли zodiac_ac_sa и zodiac_ac_ra в SSO (KeyCloak) и назначить их на требуемых пользователей.

Важно!!! Вам требуется ограничить набор пользователей, которым доступны встроенные роли, т.к. с их помощью можно менять разрешения в Zodiac.
Далее вы можете, используя аккаунты с этими ролями, настроить свою ролевую модель.

Своя ролевая модель

Для настройки своей ролевой модели вам потребуется завести роли в SSO (KeyCloak, Avanpost и т.п.) и настроить маппинг ролей в разделе «Каталог ролей» Zodiac.
Завести роли в SSO можно вручную или сконфигурировать интеграцию с доступными провайдерами.
Т.к. вам требуется использовать AD, то рекомендуется настроить интеграцию с ldap в KeyCloak/Avanpost (пункт меню User Federation).
В Руководстве администратора https://zodiac-itm.ru/docs/zodiac-admin.pdf описано как настроить маппинг ролей в разделе «Каталог ролей» Zodiac.
Для установки элементов внутри раздела, к которым настраивается доступ по роли, используется Glob-выражения.
В синтаксисе Glob-выражений в Зодиак.АйТиЭм допускаются следующие выражения:

"*" любое кол-во символов, кроме разделителя пути

"?" любой единственный символ, кроме разделителя пути

"abc" единственный символ из включенных в квадратные скобки

"!abc" единственный символ не из включенных в скобки

"**" 0 и более уровней вложенности папок

"" одна из последовательностей символов, заключенных в фигурные скобки

Также для синтаксиса Glob-выражений в Зодиак.АйТиЭм характерны следующие особенности:

Передача роли в Zodiac.ITM

Пользователь интерфейса администрирования Зодиак после аутентификации через sso провайдер получает токен доступа (access_token).
При обращении к серверу администрирования выполняется определение прав для пользователя у которого есть определённый access_token на основании сконфигурированной ролевой модели.

Пример расшифрованного Payload access_token-а:

{
  "exp": 1733326293,
  "iat": 1733326173,
  "auth_time": 1733323862,
  "jti": "xxx",
  "iss": "https://example/auth/realms/master",
  "aud": [
    "zodiac"
  ],
  "sub": "xxx",
  "typ": "Bearer",
  "azp": "zodiac",
  "allowed-origins": [
    "*"
  ],
  "resource_access": {
    "zodiac": {
      "roles": [
        "zodiac_ac_sa",
        "zodiac_ac_ra"
      ]
    }
  },
  "scope": "openid email profile",
  "email_verified": false,
  "name": "Александр Пушкин",
  "preferred_username": "admin",
  "given_name": "Александр",
  "family_name": "Пушкин"
}

В части sso(например в keycloack) можно просмотреть "предполаемый" access_token любого пользователя внутри админки (при наличии прав). От версии к версии они обожают этот функционал перемещать в самые разнообразные места, чтобы упростить нам задачу описания этого. :Z
Свой токен можно просмотреть с помощью DevTools браузеров (F12 в хроме)
В разделе "Мои настройки" Зодиак пока показываются не все поля access_token-а

Пример выражения прав супер-администратора, которое задаётся в конфигурации administration.ini

SaExprs = "$.resource_access.zodiac.roles[?(@ == 'zodiac_ac_sa')];$.roles[?(@ == 'zodiac_ac_sa')]"

Данное выражение содержит 2 jsonpath выражения разделённого символом ;

$.resource_access.zodiac.roles[?(@ == 'zodiac_ac_sa')]

и

$.roles[?(@ == 'zodiac_ac_sa')]

Для определения наличия права супер-администратора для описанных примеров Payload access_token и выражения SaExprs по очереди применяются jsonpath выражения и если какое-то выражение выдаст результат, то считается что права есть.

Чтобы роль супер администратора заработала на произвольном sso

  1. следует добавить нужные роли в sso - например роли zodiac_ac_sa и zodiac_ac_ra
  2. Назначить их на пользователя
  3. Проверить куда в access_token-е попадают данные роли
    Например роли попадают в массив по пути my_sso_access.my_sso_roles
{
"my_sso_access": {
   "my_sso_roles": ["zodiac_ac_sa"] 
 }
}
  1. Прописать в administration.ini выражения SaExprs и RaExpr с учётом где в токене находятся роли, например:
SaExprs = "$.my_sso_access.my_sso_roles[?(@ == 'zodiac_ac_sa')]"
RaExprs = "$.my_sso_access.my_sso_roles[?(@ == 'zodiac_ac_ra')]"
  1. Перезапустить сервер
    После этого роли должны заработать

Далее можно по аналогии добавить роли в разделе "Роли" сервера администрирования.