Общие сведения
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. |