Данное руководство является примерном настройки интеграции между 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
pkcepkce – наиболее безопасный вариант аутентификации из общих
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
plm.login.oauth2.providers[i].token_pass_parameters_through_body

Без добавления этих параметров приводит к возникновению ошибки в браузере в процессе получения токена сервером от провайдера:
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 после успешной аутентификации.

При включенном параметре, параметр use_groups_whitelist игнорируется.

plm.login.oauth2.providers[i].use_groups_whitelist

Использовать белый список групп пользователей для разрешения авторизации в Polymatica Analytics

plm.login.oauth2.providers[i].groups_whitelist[j]
Название группы пользователей

Добавляет группу пользователей в белый список групп пользователей, которым разрешена авторизация в Polymatica Analytics.

Приращивать индекс j необходимо по правилу:

    • первая группа в списке:
      j = 0;
    • последующие группы в списке:
      j += 1
  • Нет меток