Общие сведения
Avanpost FAM реализует функциональность аутентификации при помощи внешнего IdP (Identity Provider) с поддержкой набора различных протоколов авторизации.
Данная функция доступна в версиях Avanpost FAM Server 1.13.0 и выше. В более ранних версиях продукта для настройки SAML-провайдеров доступна только в разделе Настройки SAML-провайдеров в режиме "Сервис" (более подробно описано в разделе Управление SAML-источниками), настройки OIDC-провайдеров — в разделе "Настройка OpenID провайдеров" в режиме "Сервис" (более подробно описано в Управление IdP с поддержкой OIDC Federation).
Механизм интеграции с внешними провайдерами идентификации позволяет решать следующие задачи:
- Первичная загрузка/импорт пользователей из внешнего источника.
- Автоматическое создание пользователя в Avanpost FAM при его добавлении во внешнем источнике.
- Автоматический импорт и обновление атрибутов пользователя при их создании/изменении во внешнем источнике.
- Управление сопоставлением и преобразованием атрибутов пользователя, полученных от внешнего провайдера идентификации.
- Добавление пользователей в ту или иную группу с предварительно настроенным сценарием аутентификации посредством Avanpost FAM.
- Аутентификация с проверкой фактора аутентификации во внешнем источнике.
- Настройка сценария взаимодействия с внешним провайдером идентификации.
- Создание, удаление и управление подключениями Avanpost FAM Server к внешним провайдерами идентификации.
- Включение и выключение интеграции с тем или иным провайдером идентификации.
Avanpost FAM поддерживает следующие типы провайдеров идентификации:
- OpenID Connect - провайдеры идентификации, работающие в соответствии с протоколами OAuth 2.0 и OpenID Connect.
- SAML - провайдеры идентификации, работающие в соответствии с механизмом SAML 2.0.
- ЕСИА - механизм аутентификации через Госуслуги, выстроенный на базе стандартов SAML и OpenID Connect 1.0, но с рядом отличий от RFC.
- Другие - кастомизированные IdP.
Управление внешними IdP осуществляется в разделе "Настройки внешних провайдеров идентификации (IdP)", который содержит:
- Реестр провайдеров, отображающий базовую информацию о внешних IdP;
- Наименование - Название IdP;
- Тип - Графическое обозначение типа IdP:
- - OpenID Connect
- - SAML
- - ЕСИА
- - Другие
- Статус
- Active - осуществляется взаимодействие между Avanpost FAM и внешним IdP (если настройки IdP верны);
- Inactive - взаимодействие с внешним IdP приостановлено;
- Элементы поиска - Поисковая строка;
- Кнопка "Добавить" - Нажать для создания нового IdP.
Добавление нового провайдера идентификации
Первичная настройка внешнего провайдера идентификации осуществляется при добавлении нового IdP. Для этого требуется перейти в раздел "Настройки внешних провайдеров идентификации (IdP)" в режиме "Сервис". Затем следует нажать кнопку "Добавить" и последовательно заполнить данные в следующих разделах:
- Шаг 1. Основные настройки.
- Шаг 2. Настройки перенаправления
- Шаг 3. Настройки callback.
- Шаг 4. Завершение.
Шаг 1. Основные настройки
На данном шаге следует задать значения параметров согласно таблице.
Параметр | Значение |
---|---|
Тип | Выбрать тип провайдера идентификации:
|
Наименование | Ввести название создаваемого провайдера идентификации. |
Детали (Open ID Connect детали/ЕСИА детали/SAML детали/Другие детали - отображение названия в зависимости от выбранного типа IdP) | Редактируемый список параметров, используемых в каждом запросе к внешнему IdP. Представлен в виде перечня со столбцами:
В зависимости от выбранного типа провайдера идентификации Avanpost FAM автоматически создает набор рекомендуемых параметров. Окончательный набор параметров зависит от настроек конкретного IdP, с которым устанавливается соединение. Если параметр, необходимый для взаимодействия с данным IdP, не будет указан, его значение потребуется вводить вручную при каждом запросе. Для добавления нового параметра требуется нажать . Для удаления существующего — нажать напротив удаляемого параметра. Рекомендации по вводимым параметрам их значениям даны в приложении А. |
Для перехода к следующему шагу требуется нажать кнопку "Далее" после установки параметров. Для отказа от создания IdP следует нажать "Отмена".
Шаг 2. Настройки перенаправления
На данном шаге следует задать значения параметров согласно таблице.
Параметр | Значение |
---|---|
URI авторизации | Адрес, на который перенаправляется пользователь для авторизации. |
Метод перенаправления | Способ перенаправления данных от SP (Service Provider) к IdP (Identity Provider). Требуется установить флаг напротив одного из вариантов в зависимости от того, какой из них поддерживается внешним IdP:
|
Параметры перенаправления | Редактируемый список параметров, направляемых в запросе к внешнему IdP. Представлен в виде перечня со столбцами:
Для добавления нового параметра нажать . Для удаления существующего — нажать напротив удаляемого параметра. Настраиваемые параметры отличаются в зависимости от типа IdP. Рекомендуемые параметры перенаправления представлены в приложении Б. |
Для перехода к следующему шагу требуется нажать "Далее", для перехода к предыдущему шагу — "Назад". Для отказа от создания нового IdP следует нажать "Отмена".
Шаг 3. Настройки callback
На данном шаге следует задать значения параметров согласно таблице.
Параметр | Значение |
---|---|
Шаги для получения информации о пользователе | Последовательность действий, направленная на получение от внешнего IdP и преобразование данных пользователя:
Для добавления нового действия нажать . Для удаления существующего — нажать напротив удаляемого параметра. |
Маппинг атрибутов | Раздел, позволяющий сопоставить и связать атрибуты, полученные из внешнего IdP и основные атрибуты на стороне Avanpost FAM:
|
Маппинг дополнительных атрибутов | Раздел, позволяющий сопоставить и связать атрибуты, полученные из внешнего IdP и дополнительные атрибуты на стороне Avanpost FAM:
Если в Avanpost FAM не создано ни одного дополнительного атрибута, раздел не отображается. |
Связывать по атрибуту | Атрибут привязки, по которому пользователь на стороне Avanpost FAM ассоциируется с пользователем на стороне внешнего IdP. Выбрать атрибут привязки из выпадающего списка:
|
Для перехода к следующему шагу требуется нажать кнопку "Далее", для перехода к предыдущему шагу — "Назад". Для отказа от создания нового IdP следует нажать "Отмена".
Шаг 4. Завершение
На данном шаге следует задать значения параметров согласно таблице.
Параметр | Значение |
---|---|
Настройки интеграции | Набор параметров, представленный в виде перечня со столбцами:
Доступна настройка следующих параметров:
Параметр "Множественная учетная запись" рекомендуется использовать для IdP типа ЕСИА. В случае, когда из ЕСИА загружен пользователь, одновременно состоящий в нескольких разных организациях, в Avanpost FAM создаются учетные записи пользователя отдельно для каждой организации. При авторизации в Avanpost FAM у пользователя будет возможность выбрать в какую из учетных записей входить. |
Группа по умолчанию | Группа, в которую по умолчанию добавляются новые пользователи, загружаемые с внешнего провайдера идентификации. В текстовое поле требуется ввести название существующей в Avanpost FAM группы. |
Активный | Чекбокс "Активный":
|
Чтобы сохранить созданный IdP необходимо нажать кнопку "Сохранить". Для перехода к предыдущему шагу — нажать "Назад". Для отказа от создания нового IdP следует нажать "Отмена".
Настройка существующего провайдера идентификации
Дополнительная настройка созданного IdP осуществляется в его профиле. Для перехода в профиль IdP требуется войти в раздел "Настройки внешних провайдеров идентификации (IdP)" режима "Сервис" и нажать на название искомого провайдера. При необходимости администратор может воспользоваться поиском, введя название искомого IdP в поисковую строку.
Профиль провайдера идентификации содержит следующую информацию и возможности:
- Вкладка "Основные настройки" - Вкладка содержит параметры, настраиваемые на Шаге 1 и Шаге 4 создания нового провайдера идентификации;
- Вкладка "Настройки перенаправления" - Вкладка содержит параметры, настраиваемые на Шаге 2 создания нового провайдера идентификации;
- Вкладка "Настройки callback" - Вкладка содержит параметры, настраиваемые на Шаге 3 создания нового провайдера идентификации;
- Кнопка "Изменить" - Нажать, чтобы добавить/изменить иконку IdP (после нажатия откроется окно, в котором потребуется указать путь до графического файла);
- Кнопка / - Включить/выключить возможность редактирования параметров во вкладках "Основные настройки", "Настройки перенаправления", "Настройки callback".
- Кнопка / - Включить (перевести в статус "Actice")/выключить (перевести в статус "Inactice") данный IdP (после нажатия кнопки запрашивается подтверждение действия);
- Кнопка - Удалить данный IdP (после нажатия кнопки запрашивается подтверждение действия);
- Кнопка "Сохранить" - Сохранить внесенные изменения (доступна после нажатия кнопки );
- Кнопка "Отмена" - Отменить внесение изменений (доступна после нажатия кнопки ).
Приложение А. Значения данных для различных провайдеров идентификации
В таблице представлены значения параметров, рекомендуемых к заполнению в разделе "Данные" на Шаге 1 создания нового провайдера аутентификации.
Если в качестве типа IdP выбран "Другие", Avanpost FAM не создает поля с параметрами в разделе "Данные" автоматически. Avanpost FAM дает администратору возможность подключиться к кастомизированному внешнему IdP, заполнив поля в разделе "Данные" в соответствии с настройками данного IdP.
Параметр | Описание |
---|---|
OpenID Connect | |
baseUrl | Адрес, на который пользователь будет перенаправляться при переходе из личного кабинета. Для упрощения настройки ссылка на данный параметр автоматически подставляется в дальнейших настройках при указании пути до того или иного объекта на стороне IdP. |
scope | Области доступа (scopes), т.е. запрашиваемые права. В составе jwt-токена, отправляемого провайдером идентификации будут передаваться claim'ы, входящие в запрошенные scope. |
clientID | Уникальный идентификатор Avanpost FAM. |
clientSecret | Секрет, который будет использоваться для подключения. |
SAML | |
baseUrl | Адрес, на который пользователь будет перенаправляться при переходе из личного кабинета. |
idp_iss | Уникальный идентификатор (Issuer) IdP. |
sp_iss | Уникальный идентификатор (Issuer) SP, т.е. Avanpost FAM. |
aud | Значение параметра соответствует Audience URI. Параметр содержит набор (аудиторию) субъектов, которым разрешено использовать сгенерированное Assertion. |
sig | Подпись запроса аутентификации:
|
ver | Пропускать проверку подписи:
|
cert | Сертификат в формате base64. |
ЕСИА | |
baseUrl | Адрес, на который пользователь будет перенаправляться при переходе из личного кабинета. |
scope | Области доступа (scopes), т.е. запрашиваемые права. Например, если Avanpost FAM запрашивает доступ к сведениям о сотрудниках организации, то область доступа (scope) должна иметь значение «http://esia.gosuslugi.ru/org_emps» (с необходимыми параметрами). |
scopeOrg | Область доступа, т.е. запрашиваемые права для юридических лиц; например, если система-клиент запрашивает доступ к сведениям об организации (hhtp://esia.gosuslugi.ru/org_inf), то не нужно в качестве параметра указывать oid организации этого пользователя. |
clientID | Идентификатор Avanpost FAM (мнемоника системы в ЕСИА указанная прописными буквами). |
clientCertHash | Параметр, содержащий хэш сертификата (fingerprint сертификата) системы-клиента в hex–формате. Используемый для проверки подписи сертификат должен быть предварительно зарегистрирован в ЕСИА63 и привязан к УЗ системы-клиента в ЕСИА. ЕСИА использует сертификаты в формате X.509 и взаимодействует с алгоритмами формирования электронной подписи ГОСТ Р 34.10-2012 и криптографического хэширования ГОСТ Р 34.11-2012. |
cryptoProvider | Комплексный параметр, содержащий данные о контейнере. В текстовом поле указывается JSON-токен со следующими данными:
|
Приложение Б. Рекомендации по настройке параметров перенаправления
В таблице представлены значения параметров, рекомендуемых к заполнению в разделе "Параметры перенаправления" на Шаге 2 создания нового провайдера аутентификации.
Параметр | Описание |
---|---|
OpenID Connect | |
response_type | Тип ответа, который ожидается от OIDC-провайдера. Рекомендуется использовать значение |
client_id | Уникальный идентификатор Avanpost FAM. Ссылается на параметр |
scope | Области доступа (scopes), т.е. запрашиваемые права. Ссылается на параметр |
redirect_uri | Ссылка, по которой должен быть направлен пользователь после того, как даст разрешение на доступ к ресурсу. Значение параметра должно быть предварительно указано в параметрах при настройке внешней IdP. Пример значения параметра: |
ЕСИА (в соответствии с Методическими рекомендациями по использованию ЕСИА) | |
response_type | Тип ответа, который ожидается от ЕСИА. Рекомендуется использовать значение |
access_type | Тип доступа к ресурсам владельца:
|
client_id | Идентификатор Avanpost FAM (мнемоника системы в ЕСИА указанная прописными буквами). Ссылается на параметр |
scope | Области доступа (scopes), т.е. запрашиваемые права. Ссылается на параметр |
redirect_uri | Ссылка, по которой должен быть направлен пользователь после того, как даст разрешение на доступ к ресурсу. Значение параметра должно быть предварительно указано в параметрах внешней ИС в ЕСИА – на стороне ЕСИА выполняется верификация соответствия redirect_uri в запросе и в настройках системы. |
client_secret | Подпись запроса в формате PKCS#7 detached signature в кодировке UTF-8 от значений четырех параметров HTTP-запроса: Параметр кодируется в формате base64 url safe. Используемый для проверки подписи сертификат должен быть предварительно регистрируется в ЕСИА63 и привязывается к УЗ системы-клиента (Avanpost FAM) в ЕСИА. ЕСИА использует сертификаты в формате X.509 и взаимодействует с алгоритмами формирования электронной подписи ГОСТ Р 34.10-2012 и криптографического хэширования ГОСТ Р 34.11-2012. Пример значения параметра: |
timestamp | Время запроса авторизационного кода в формате yyyy.MM.dd HH:mm:ss Z (например, 2013.01.25 14:36:11 +0400), необходимое для фиксации начала временного промежутка, в течение которого будет валиден запрос с данным идентификатором (state ). Пример значения параметра: {{ timeFormat "2006.01.02 15:04:05 Z0700" .process_started }}. |
state | Идентификатор запроса. Набор случайных символов, имеющий вид 128-битного идентификатора запроса (необходимо для защиты от перехвата), генерируется по стандарту UUID. Пример значения параметра: |
client_certificate_hash | Параметр, содержащий хэш сертификата (fingerprint сертификата) системы-клиента в hex–формате. Ссылается на параметр |
scope_org | Область доступа, т.е. запрашиваемые права для юридических лиц. Ссылается на параметр |
Приложение В. Скрипты получения информации о пользователе.
В последовательности действий для получения информации о пользователе, применяемая на шаге 3, используются по преимуществу следующие методы.
Метод | Назначение | Пример |
---|---|---|
"jwt" | Парсинг claim'ов из токена. |
|
"join" | Преобразование значений нескольких элементов в общую строку. | join "a" "bc" "d" - преобразует значения "a", "bc", "d" в единую строку "abcd". |
"fail" | Прерывание процесса аутентификации с выдачей сообщений об ошибке. | fail "some error text" - прерывает процесс аутентификации и выдает пользователю сообщение "some text of error". |
"base64" | Преобразование набора символов в набор символов в формате base64. | base64 "some text or bytes" - преобразует "some text or bytes" в формат base64 с получением "c29tZSB0ZXh0IG9yIGJ5dGVzCg==". |
"debase64" | Преобразование набора символов в формате base64 в исходный набор символов. | debase64 "c29tZSB0ZXh0IG9yIGJ5dGVzCg==" - декодирует набор символов "c29tZSB0ZXh0IG9yIGJ5dGVzCg==" из формата base64 с получением строки "some text or bytes". |
"timeFormat" | Ввод значения текущей даты и времени. | timeFormat "2006.01.02 15:04:05 Z0700" - вводит значение текущей даты и времени. |
"cryptoSign" | Подпись с помощью криптопровайдера (в Avanpost FAM реализована подпись посредством КриптоПро). | cryptoSign .context "some data" .extidp_details.cryptoProvider - подписывает данные криптопровайдером, указанным в разделе "Детали" Шага 1 (см. значение параметра cryptoProvider в приложении А. |
"cryptoVerify" | Проверка подписи данных при помощи криптопровайдера. | cryptoVerify .context .signatureBytes .dataBytes .extidp_details.cryptoProvider - Проверка подписи данных (signatureBytes .dataBytes ), при помощи криптопровайдера, указанного в разделе "Детали" Шага 1. |
"cryptoVerifyJWT" | Проверка подписи токена при помощи криптопровайдера. | cryptoVerifyJWT .context .token.id_token .extidp_details.cryptoProvider - Проверка подписи токена (token.id_token ) при помощи криптопровайдера, указанного в разделе "Детали" Шага 1. |
"emailUsername" | Получение логина пользователя из email. | emailUsername "user123@example.com" - Преобразование user123@example.com в user123 . |