Данное руководство является примерном настройки интеграции между Polymatica Analytics и Avanpost FAM по протоколу OpenID Connect с чтением прав доступа Polymatica Analytics, настроенных в Avanpost FAM для пользователей.
В этом руководстве описывается пример настройки конкретной системы у конкретного заказчика. В зависимости от различных факторов, те или иные шаги по настройке могут отличаться.
Подготовка к настройке
Перед выполнением настроек необходимо наличие:
- Доступ к системе Avanpost FAM. Это может быть VPN-подключение в закрытый контур. Главное, чтобы главная страница Avanpost FAM была доступна.
- Учётная запись Avanpost FAM с правами администратора или на создание приложения, управление ролями пользователей, управление группами и пользователями.
- Сервер с развёрнутой системой Polymatica Analytics и доступ к конфигурационному файлу (polymatica.conf).
Настройка
Создание дополнительных атрибутов пользователя
Avanpost FAM позволяет дополнять учётную запись пользователя произвольными данными ("Дополнительные атрибуты"). Например, через этот функционал работает функция автоматического назначения групп пользователям Полиматики.
Для добавления нового атрибута или редактирования существующего, необходимо открыть вкладку "Пользователи" и нажать ссылку "Редактор атрибутов".
Открытая таблица содержит все дополнительные атрибуты, существующие в системе Avanpost FAM.
Список дополнительных атрибутов, поддерживаемых Полиматикой:
Наименование | Описание | Ожидаемый тип значения |
|---|---|---|
| plm_user_groups | Список групп в Polymatica Analytics, в которые добавить пользователя после успешной аутентификации. | SCSV-строка (Semicolon Separated Values). Одна строчка, произвольное количество столбцов. Каждый столбец - название одной группы. Разделитель: ; (точка с запятой). Символ кавычек: ' (одинарная кавычка). Кодировка текста: UTF-8 |
Добавление приложения
Осуществить вход в систему с учётной записью с необходимыми правами.
Перейти на вкладку "Приложения".
Нажать кнопку "Добавить приложение". Откроется страница с 4 пунктами, первая вкладка "Основные настройки":
- Наименование - любое уникальное в рамках данного инстанса Avanpost FAM;
- Тип - OpenID;
- Показывать приложение пользователям - на выбор;
Нажать "Далее". Откроется вкладка "Настройки интеграции":
- Secret - сгенерировать с помощью рандомайзера максимально сложную последовательность из 20 символов (макс. ограничение) и записываем её куда-нибудь. Понадобится позже;
- Redirect URIs - указать адрес редиректа на сервер Polymatica Analytics. Например, "http://10.8.0.74:8080/api/v2/login/oauth2/redirect/bft_avanpost";
- Base URL - аналогично предыдущему, указать только базовый адрес сервера. Например, "http://10.8.0.74:8080";
- Logout URL - указать адрес редиректа для выхода из учётной записи Polymatica Analytics. Например, "http://10.8.0.74:8080/api/v2/logout/oauth2";
Система выхода из учётной записи через Logout URL на стороне Polymatica Analytics пока не поддерживается. См. реализацию стандарта OpenID Connect Back-Channel Logout.
Нажать "Далее". Откроется следующая вкладка "Настройки аутентификации":
- Оставить Password.
Нажать "Далее". Откроется последняя вкладка "Завершение":
- Оставить включённой галку "Сделать приложение активным";
Нажать "Далее". Приложение создано.
Настройка дополнительных параметров приложения
На вкладке "Приложения" выбрать только что созданное приложение. Перейти на вкладку "Настройки" и включить редактирование нажатием на кнопку с карандашом справа. Установить следующие параметры:
- Access Token Type - JSON Web Token. Это необходимо, чтобы в access token система передавала права доступа приложения.
Нажать кнопку "Сохранить".
Перейти на вкладку "Scopes". На этой вкладке настроим добавление в токены данных по запрашиваемым утверждениям (clams). Нажимаем кнопку "+" и указываем:
- Scope - название скоупа, по которому будут добавляться данные. Например, "plm_groups". Запоминаем/записываем его, понадобится позже на этапе настройки сервера Polymatica Analytics.
Утверждения (claims) - это маппинг данных из атрибутов пользователя на данные в токене, согласно следующей таблице (наименования запоминаем/записываем, понадобятся позже на этапе настройки сервера Polymatica Analytics):
Наименование
Тип
Значение
Комментарий
plm_groups Значение из атрибута plm_user_groups В токен будет добавлен элемент "plm_groups" со значением, взятым из атрибута "plm_user_groups" блока дополнительных атрибутов карточки пользователя
Нажимаем кнопку "Сохранить". Новый scope добавлен.
Перейти на вкладку "Модель доступа".
Осуществить перенос ролей пользователей Polymatica Analytics в Avanpost FAM. Нажать кнопку "+" и указать:
- Код - указать уникальный идентификатор объекта ресурсов. Например, "user_permissions". Запомнить/записать его, понадобится позже;
- Описание - "Права пользователя";
В блоке "Права (scopes)" добавить 5 вариантов доступа:
| Код | Описание |
|---|---|
| administrator | Администратор системы |
| cube_creation | Создание мультисфер |
| data_export | Экспорт данных |
ВАЖНО
Данные в графе "Код" должны соответствовать hardCode идентификаторам ролей на сервере Polymatica Analytics (для списка допустимых идентификаторов см. plm::server::MemberRolesCodes::serialize). Описание взято со страницы списка ролей Polymatica Analytics, но может быть абсолютно любым. Чтобы не создавать диссонанс в сознании оператора техподдержки, имеет смысл указывать одинаковое описание.
Сохранить указанные права и перейти к процессу создания пользователей/групп (или назначению прав пользователей, если Avanpost FAM получает пользователей откуда-то извне. Например из LDAP).
Добавление пользователей (при необходимости)
Осуществить переход на вкладку "Пользователи". Нажать кнопку "Добавить пользователя". Указать основные данные учётной записи (в местной терминологии "атрибуты"). Дополнительные атрибуты указывать не требуется - нет поддержки со стороны Polymatica Analytics. Повторить процесс столько раз, сколько необходимо.
Добавление групп пользователей (при необходимости)
Перейти на вкладку "Группы". Нажать кнопку "Добавить группу".
- Наименование - любое;
- Описание - любое.
Открыть созданную группу и добавить пользователей, активировать для группы созданное ранее приложение.
Добавление ролей пользователей и групп
Перейти на вкладку "Сервис" и нажать на ссылку "Настройка ролей и прав". Нажать на кнопку "Добавить".
- Наименование - любое уникальное;
- Описание - любое;
- Объекты доступа и права выбрать только из списка test_polymatica. Они были добавлены ранее на этапе редактирования параметров только что созданного приложения. Выбрать права.
Нажать "Сохранить" и открыть параметры только что созданной роли. Убедиться, что на вкладке "Объекты доступа и права" всё правильно и добавить пользователей и группы в соответствующих вкладках.
ВАЖНО
По состоянию Avanpost FAM 1.2.0, имеется баг, из-за которого система некорректно определяет роли пользователя в случае, если он добавлен в группу, а роли выданы только группе. Avanpost FAM не возвращает в Polymatica Analytics роли и, соответственно, управление правами доступа через Avanpost FAM становится невозможным. Решение проблемы есть, но оно не является оптимальным - необходимо назначить роли напрямую каждому пользователю.
Настройка конфигурации для OpenID Connect
Настроить провайдера OpenID Connect для Polymatica Analytics. Процесс не отличается от настройки произвольного провайдера, но есть ряд важных параметров:
| Параметр | Значение | Применение |
|---|---|---|
plm.login.oauth2.avanpost_permissions_resource_id | user_permissions (который требовалось запомнить заранее) Значение должно соответствовать идентификатору объекта доступа, указанному ранее в настройках приложения в Avanpost FAM. | Если не указать, то Polymatica Analytics не сможет правильно прочитать права доступа пользователя, а Avanpost FAM может возвращать права доступа произвольных приложений |
plm.login.oauth2.providers[i].client_secret | Секрет созданного приложения. Требовалось запомнить запомнить заранее, на этапе создания приложения Avanpost FAM. | Без секрета невозможно проверить подлинность запроса на получение токена доступа от Polymatica Analytics к Avanpost FAM |
plm.login.oauth2.providers[i].scope | openid profile email permissions | Если не указать permissions, то Avanpost FAM не будет сообщать права доступа пользователя и, соответственно, их не удастся применить к учётной записи пользователя Polymatica Analytics |
plm.login.oauth2.providers[i].flow | pkce | pkce – наиболее безопасный вариант аутентификации из общих |
plm.login.oauth2.providers[i].claims.login | preferred_username | Если не указать, то Polymatica Analytics не сможет прочитать логин пользователя, а место хранения будет отличаться от стандартного |
plm.login.oauth2.providers[i].claims.fullname | name | Если не указать, то Polymatica Analytics не сможет прочитать полное имя пользователя, а место хранения будет отличаться от стандартного |
plm.login.oauth2.providers[i].claims.permissions | permissions | Если не указать, то Polymatica Analytics не сможет прочитать права доступа пользователя |
plm.login.oauth2.providers[i].claims.groups | plm_groups (запоминали ранее на этапе добавления scope для приложения) | Если не указать – Polymatica Analytics не сможет прочитать группы пользователей |
plm.login.oauth2.providers[i].metadata.use_oidc_discovery | Avanpost FAM поддерживает OpenID Connect Discovery, поэтому данный параметр позволяет сэкономить время, предоставив настройку серверу | |
plm.login.oauth2.providers[i].metadata.url | http://srv-dev-rrsys-avanpost | Этот URI используется в качестве базового для запроса метаданных провайдера по протоколу OIDC. Используется в паре с use_oidc_discovery |
plm.login.oauth2.providers[i].metadata.skip_validation | Не рекомендуется использовать. Позволяет пропустить валидацию данных, например, в случае, если введённые данные не позволяют пройти валидацию | |
plm.login.oauth2.providers[i].authorization_add_redirect_parameter | Без добавления параметра редиректа сервер Avanpost FAM передаёт ошибку | |
plm.login.oauth2.avanpost.admin_group_name | Отвечает за назначение роли "Администратор" всем пользователям той группы, название которой прислал Avanpost в claims | |
plm.login.oauth2.providers[i].token_add_client_secret | Без добавления этих параметров приводит к возникновению ошибки в браузере в процессе получения токена сервером от провайдера: Failed to get access token from OAuth2 provider. В консоли сервера Polymatica Analytics: ["invalid_client", "Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).", ""] | |
plm.login.oauth2.providers[i].skip_token_permissions | Применяется для пропуска сброса и применения прав доступа из токенов OAuth2 после успешной аутентификации | |
plm.login.oauth2.providers[i].skip_token_roles | Применяется для пропуска сброса и применения ролей из токенов OAuth2 после успешной аутентификации | |
plm.login.oauth2.providers[i].skip_token_groups | Применяется для пропуска сброса и применения групп пользователей из токенов OAuth2 после успешной аутентификации. При включенном параметре, параметр | |
plm.login.oauth2.providers[i].use_groups_whitelist | Использовать белый список групп пользователей для разрешения авторизации в Polymatica Analytics | |
plm.login.oauth2.providers[i].groups_whitelist[j] | Название группы пользователей | Добавляет группу пользователей в белый список групп пользователей, которым разрешена авторизация в Polymatica Analytics. Приращивать индекс j необходимо по правилу:
|