Подключение каталога групп по LDAP

В системе существует возможность подключения к внешнему реестру пользователей по протоколу LDAP и синхронизации пользователей/групп LDAP-сервера с пользователями/группами в Polymatica Analytics.

Добавьте в файл конфигурации polymatica.conf следующие строки:

# Параметры синхронизации с LDAP-сервером

# Если используется сторонняя БД с пользователями и группами (например, LDAP)
plm.manager.use_external_users_groups_bd

# Тип аутентификации, для LDAP выставить этот параметр в LDAP
plm.manager.auto_authentication_type = LDAP

# Адрес LDAP-сервера
plm.manager.auto_authentication_uri = srv-dc01.bft.local:3268

# Учетная запись (для получения информации о пользователях и группах)
plm.manager.auto_authentication_ldap_dn = CN=zirvan,CN=Users,DC=bft,DC=local

# Пароль
plm.manager.auto_authentication_password = ...

# Базовый DN
plm.manager.auto_authentication_ldap_base_dn = OU=БФТ-Эксперт,OU=Организации,DC=bft,DC=local

# Фильтр для выборки записей о пользователях и группах
plm.manager.auto_authentication_ldap_filter = (&(ObjectClass=user))

# Атрибут записи о пользователе. По нему выбираются записи из LDAP-каталога.
plm.manager.auto_authentication_ldap_login_attribute = sAMAccountName

Интеграция с ЕСИА

В Polymatica Analytics предусмотрена возможность интеграции с ЕСИА.

Для подключения к ЕСИА:

Добавьте в файл конфигурации polymatica.conf следующие строки:

# Тип автоматической аутентификации (зависит от клиента), возможные варианты:

# DEFAULT, ECASA, ASNA, SIMPLE, LUNA, ESIA

plm.manager.auto_authentication_type = DEFAULT

# URI для получения кода авторизации (только для типа ESIA, запрос от клиента):

plm.manager.auto_authentication_code_uri = https://esia-portal1.test.gosuslugi.ru/aas/oauth2/ac

# URI для получения access-кода:

plm.manager.auto_authentication_uri = https://esia-portal1.test.gosuslugi.ru/aas/oauth2/te

# URI для перехода после успешной авторизации, только для типа ESIA:plm.manager.auto_authentication_redirect_uri = https://moscow0.polymatica.ru:37612/login

# URI для получения персональных данных, только для типа ESIA:plm.manager.auto_authentication_personinfo_uri = https://esia-portal1.test.gosuslugi.ru/rs/prns

# URI для получения данных об организации, только для типа ESIA: plm.manager.auto_authentication_orginfo_uri = https://esia-portal1.test.gosuslugi.ru/rs/orgs

# Идентификатор организации, только для типа ESIA: plm.manager.auto_authentication_clientid = id

# Путь к закрытому ключу, только для типа ESIA:

plm.manager.auto_authentication_key = /etc/polymatica/esia_key.key

# Путь к сертификату x509, только для типа ESIA:

plm.manager.auto_authentication_crt = /etc/polymatica/esia_crt.crt

Авторизация пользователей по OAuth 2.0

Для авторизации через OAuth 2.0 требуется отдельная сборка, в результате которой получаются стандартные пакеты (как и при обычной сборке), а также файл libplmoauth2-extension.so.
Пакеты устанавливаются как и при обычной поставке, а файл libplmoauth2-extension.so помещается в директорию /usr/share/polymatica/extensions.

В файле конфигурации /etc/polymatica/polymatica.conf устанавливаются следующие значения:

# Тип автоматической аутентификации
plm.manager.auto_authentication_type = OAUTH2

# URI сервера авторизации для получения кода авторизации
plm.manager.auto_authentication_code_uri = http://<CA address>

# URI сервера авторизации для получения access-кода (token)
plm.manager.auto_authentication_uri = http://<CA address>

# URI в Polymatica Analytics для перехода после успешной авторизации сервером авторизации
plm.manager.auto_authentication_redirect_uri = http://<Polymatica address>/login/callback

# Credentials используется для авторизованного общения Polymatica Analytics с сервером авторизации
plm.manager.auto_authentication_clientid = polymatica
plm.manager.auto_authentication_password = password123

После этого необходимо перезапустить Polymatica Analytics.

В процессе авторизации Polymatica Analytics делает запрос к серверу авторизации на получение токена с правами пользователя. Токен имеет формат:

{
    "access_token": "<token id>",
    "token_type": "bearer",
    "expires_in": 9,
    "scope": "polymatica",
    "user_name": "<login>",
    "authorities": {
        "cubes": [{
                "name": "cube name 1",
                "uuid": "<cube id>",
                "dims": [{
                        "id": "some dimension 1",
                        "name": "some dimension 1 name"
                    }, {
                        "id": "some dimension 2",
                        "name": "some dimension 2 name"
                    }, {
                        "id": "some dimension 3",
                        "name": "some dimension 3 name"
                    },
                    ...
                ],
                "dims_restrictions": [],
                "facts": [],
                "creator": null,
                "available": false,
                "creation_time": 0
            },
            {
                "name": "cube name 2",
                "uuid": "<cube id>",
                "dims": [{
                        "id": "some dimension 1",
                        "name": "some dimension 1 name"
                    }, {
                        "id": "some dimension 2",
                        "name": "some dimension 2 name"
                    }, {
                        "id": "some dimension 3",
                        "name": "some dimension 3 name"
                    },
                    ...
                ],
                "dims_restrictions": [],
                "facts": [],
                "creator": null,
                "available": false,
                "creation_time": 0
            }
            ...
         ]
    }
}

Пустые значения dims, facts и dims_restrictions означают полную доступность всех размерностей и фактов.
Если необходимо указать доступ только на некоторые элементы размерности, то поле dims_restrictions заполняется следующим образом:

 "dims_restrictions": [{
                        "id": "<dimension id>",
                        "name": "<dimension name>",
                        "elements": ["element 1", "element 2", ... ]
                    }],

При этом вектор dims может быть пустым.

Avanpost FAM

Данное руководство является примерном настройки интеграции между 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 становится невозможным. Решение проблемы есть, но оно не является оптимальным - необходимо назначить роли напрямую каждому пользователю.

Настройка сервера Polymatica Analytics

Настроить провайдера 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 plm_groups permissions	Если не указать permissions, то Avanpost FAM не будет сообщать права доступа пользователя и, соответственно, их не удастся применить к учётной записи пользователя Polymatica Analytics. Если не указать plm_groups (запоминали ранее на этапе добавления приложения), то Avanpost FAM не будет сообщать список групп, в которые необходимо добавить пользователя.
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		НЕ РЕКОМЕНДУЕТСЯ пропускать любые валидации данных, но конкретно в этом случае, похоже, система была некорректно настроена и метаданные не проходят валидацию (issuer не совпадает с хостом).
plm.login.oauth2.providers[i].authorization_add_redirect_parameter		Без добавления параметра редиректа сервер Avanpost FAM передаёт ошибку.
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).", ""]

Дерево страниц

Внешние пользователи

Подключение каталога групп по LDAP

Интеграция с ЕСИА

Авторизация пользователей по OAuth 2.0

Avanpost FAM

Подготовка к настройке

Настройка

Создание дополнительных атрибутов пользователя

Добавление приложения

Настройка дополнительных параметров приложения

Добавление пользователей (при необходимости)

Добавление групп пользователей (при необходимости)

Добавление ролей пользователей и групп

Настройка сервера Polymatica Analytics