Identity Cloud : 5.5.2. Управление внешними источниками

[ Общие сведения ] [ Добавление нового провайдера идентификации ] [ Шаг 1. Основные настройки ] [ Шаг 2. Настройки перенаправления ] [ Шаг 3. Настройки callback ] [ Шаг 4. Завершение ] [ Настройка существующего провайдера идентификации ] [ Приложение А. Значения данных для различных провайдеров идентификации ] [ Приложение Б. Рекомендации по настройке параметров перенаправления ] [ Приложение В. Скрипты получения информации о пользователе. ]

Общие сведения

Avanpost Identity Cloud реализует функциональность аутентификации при помощи внешнего IdP (Identity Provider) с поддержкой набора различных протоколов авторизации. 

Механизм интеграции с внешними провайдерами идентификации позволяет решать следующие задачи:

  • Первичная загрузка/импорт пользователей из внешнего источника.
  • Автоматическое создание пользователя в Avanpost Identity Cloud при его добавлении во внешнем источнике.
  • Автоматический импорт и обновление атрибутов пользователя при их создании/изменении во внешнем источнике.
  • Управление сопоставлением и преобразованием атрибутов пользователя, полученных от внешнего провайдера идентификации.
  • Добавление пользователей в ту или иную группу с предварительно настроенным сценарием аутентификации посредством Avanpost Identity Cloud. 
  • Аутентификация с проверкой фактора аутентификации во внешнем источнике.
  • Настройка сценария взаимодействия с внешним провайдером идентификации.
  • Создание, удаление и управление подключениями Avanpost Identity Cloud к внешним провайдерами идентификации.
  • Включение и выключение интеграции с тем или иным провайдером идентификации.

Avanpost Identity Cloud поддерживает следующие типы провайдеров идентификации:

  • OpenID Connect - провайдеры идентификации, работающие в соответствии с протоколами OAuth 2.0 и OpenID Connect.
  • SAML - провайдеры идентификации, работающие в соответствии с механизмом SAML 2.0.
  • Другие - кастомизированные IdP.

Управление внешними IdP осуществляется в разделе "Настройки внешних провайдеров идентификации (IdP)", который содержит:

  • Реестр провайдеров, отображающий базовую информацию о внешних IdP;
    • Наименование - Название IdP;
    • Тип - Графическое обозначение типа IdP: 
      • -  OpenID Connect
      • - SAML
      • - Другие
    • Статус:
      • Active - осуществляется взаимодействие между Avanpost Identity Cloud и внешним IdP (если настройки IdP верны);
      • Inactive - взаимодействие с внешним IdP приостановлено;
  • Элементы поиска - Поисковая строка;
  • Кнопка "Добавить" - Нажать для создания нового IdP.

Добавление нового провайдера идентификации

Первичная настройка внешнего провайдера идентификации осуществляется при добавлении нового IdP. Для этого требуется перейти в раздел "Настройки внешних провайдеров идентификации (IdP)" в режиме "Сервис". Затем следует нажать кнопку "Добавить" и последовательно заполнить данные в следующих разделах:

  1. Шаг 1. Основные настройки.
  2. Шаг 2. Настройки перенаправления
  3. Шаг 3. Настройки callback.
  4. Шаг 4. Завершение.

Шаг 1. Основные настройки

На данном шаге следует задать значения параметров согласно таблице. 

ПараметрЗначение
Тип

Выбрать тип провайдера идентификации:

  • OpenID Connect;
  • SAML;
  • Другие.
НаименованиеВвести название создаваемого провайдера идентификации.
СинонимВвести короткий идентификатор (ID synonym) для использования в callback URI. Использование синонима позволяет обходить ограничения некоторых сторонних сервисов на длину URL при настройке интеграции). 
Детали (Open ID Connect детали/SAML детали/Другие детали - отображение названия в зависимости от выбранного типа IdP)

Редактируемый список параметров, используемых в каждом запросе к внешнему IdP. Представлен в виде перечня со столбцами:

  • Имя - Наименование параметра.
  • Значение - Значение параметра, присваиваемое администратором.

В зависимости от выбранного типа провайдера идентификации Avanpost Identity Cloud автоматически создает набор рекомендуемых параметров. Окончательный набор параметров зависит от настроек конкретного IdP, с которым устанавливается соединение. Если параметр, необходимый для взаимодействия с данным IdP, не будет указан, его значение потребуется вводить вручную при каждом запросе. 

Для добавления нового параметра требуется нажать . Для удаления существующего — нажать напротив удаляемого параметра.

Рекомендации по вводимым параметрам их значениям даны в приложении А.

Для перехода к следующему шагу требуется нажать кнопку "Далее" после установки параметров. Для отказа от создания IdP следует нажать "Отмена". 

Шаг 2. Настройки перенаправления

На данном шаге следует задать значения параметров согласно таблице. 

ПараметрЗначение
URI авторизацииАдрес, на который перенаправляется пользователь для авторизации.
Метод перенаправления

Способ перенаправления данных от SP (Service Provider) к IdP (Identity Provider). 

Требуется установить флаг напротив одного из вариантов в зависимости от того, какой из них поддерживается внешним IdP:

  • Redirect - Данные передаются с помощью HTTP-перенаправлений;
  • Post Form - Данные передаются с помощью форм HTTP POST.
Параметры перенаправления

Редактируемый список параметров, направляемых в запросе к внешнему IdP. Представлен в виде перечня со столбцами:

  • Имя - Наименование параметра.
  • Значение - Значение параметра, присваиваемое администратором.

Для добавления нового параметра нажать . Для удаления существующего — нажать напротив удаляемого параметра.

Настраиваемые параметры отличаются в зависимости от типа IdP. Рекомендуемые параметры перенаправления представлены в приложении Б. 

Для перехода к следующему шагу требуется нажать "Далее", для перехода к предыдущему шагу — "Назад". Для отказа от создания нового IdP следует нажать "Отмена". 

Шаг 3. Настройки callback

На данном шаге следует задать значения параметров согласно таблице.

ПараметрЗначение
Шаги для получения информации о пользователе

Последовательность действий, направленная на получение от внешнего IdP и преобразование данных пользователя:

  • Тип действия (выбрать из выпадающего списка):
    • HTTP-запрос - Осуществление HTTP-запроса по выбранному метода к ресурсу; 
    • Маппинг - Сопоставление и преобразование данных, полученных от внешнего IdP;
    • Скрипт - Выполнение скрипта с полученными данными;
  • Атрибут результата - Наименование атрибута на стороне внешнего IdP, который можно запросить через API внешнего IdP (доступен при выбранном типе действия "HTTP-запрос");
  • Метод - HTTP-метод, применяемый к ресурсу (доступен при выбранном типе действия "HTTP-запрос"):
    • GET - Запрос содержимого ресурса, находящегося по указанному URL;
    • POST - Передача данных для дальнейшей обработки ресурсу, находящемуся по указанному URL;
    • PUT - Загрузка содержимого запроса на ресурс, находящийся по указанному адресу;
    • PATCH - Загрузка содержимого запроса (фрагмент ресурса) на ресурс, находящийся по указанному URL;
    • DELETE - Удаление ресурса, находящегося по указанному URL;
    • HEAD - Запрос содержимого ресурса (при отсутствии тела в ответе сервера), находящегося по указанному URL;
    • OPTIONS - Запрос для определения возможностей сервера/параметров соединения;
  • URL - URL-адрес ресурса, к которому осуществляется HTTP-запрос (доступен при выбранном типе действия "HTTP-запрос");
  • Данные - Данные операции в зависимости от выбранного типа действия:
    • для типа "HTTP-запрос" - Данные, направляемые серверу авторизации в теле HTTP-запроса:
      • Имя - Наименование параметра;
      • Значение - Присваиваемое значение (может присваиваться значение заданного/полученного параметра или задаваться без привязки к параметру);
    • для типа "Маппинг" - Параметры выполняемых функций:
      • Имя - Наименование параметра, в который записывается результат;
      • Значение - Функции и параметры для совершаемого действия (например, для проверки подписи id_token);
    • для типа "Скрипт" - Параметры выполняемого скрипта.
      • Имя - Наименование параметра, в который записываются результаты скрипта;
      • Значение - Методы, используемые в скрипте и параметры, с которым скрипт совершается (подробнее о доступных скриптах в Приложении В)
  • Заголовки - Заголовок HTTP-запроса (доступен при выбранном типе действия "HTTP-запрос"):
    • Имя - Ключ заголовка HTTP-запроса согласно RFC 2616 (например, Authorization используется для проверки подлинности пользователя и может содержать значение токена авторизации: Bearer {{ .token.access_token }})
    • Значение - Значение заголовка HTTP-запроса.

Для добавления нового действия нажать . Для удаления существующего — нажать напротив удаляемого параметра.

Маппинг атрибутов

Раздел, позволяющий сопоставить и связать атрибуты, полученные из внешнего IdP и основные атрибуты на стороне Avanpost Identity Cloud:

  • Имя - Наименование атрибута на стороне Avanpost Identity Cloud;
  • Значение - Наименование атрибута, получаемого от внешнего IdP.
Маппинг дополнительных атрибутов

Раздел, позволяющий сопоставить и связать атрибуты, полученные из внешнего IdP и дополнительные атрибуты на стороне Avanpost Identity Cloud:

  • Имя - Наименование атрибута на стороне Avanpost Identity Cloud;
  • Значение - Наименование атрибута, получаемого от внешнего IdP.

Если в Avanpost Identity Cloud не создано ни одного дополнительного атрибута, раздел не отображается.

Связывать по атрибуту

Атрибут привязки, по которому пользователь на стороне Avanpost Identity Cloud ассоциируется с пользователем на стороне внешнего IdP.

Выбрать атрибут привязки из выпадающего списка:

  • Имя пользователя (логин);
  • Email;
  • Телефон;
  • Внешний ID;
  • Дополнительный атрибут (в списке отражаются дополнительные атрибуты, добавленные в Avanpost Identity Cloud).

Для перехода к следующему шагу требуется нажать кнопку "Далее", для перехода к предыдущему шагу — "Назад". Для отказа от создания нового IdP следует нажать "Отмена".

Шаг 4. Завершение

На данном шаге следует задать значения параметров согласно таблице.

ПараметрЗначение
Настройки интеграции

Набор параметров, представленный в виде перечня со столбцами:

  • Имя - Наименование параметра.
  • Значение - Переключатель (/).

Доступна настройка следующих параметров:

  • Создание пользователей
    • при включенном переключателе () появление нового пользователя на стороне внешнего IdP приводит к автоматическому созданию пользователя на стороне Avanpost Identity Cloud (решение о создании принимается в результате поиска по значению атрибута привязки, выбранному в графе "Связывать по атрибуту" на Шаге 3 данной инструкции: если на стороне внешнего IdP найден пользователь с некоторым значением атрибута привязки, отсутствующим в Avanpost Identity Cloud, данный пользователь автоматически создается в Avanpost Identity Cloud);
    • при включенном переключателе () автоматическое создание нового пользователя в Avanpost Identity Cloud, появившегося на стороне внешнего IdP, не осуществляется;
  • Обновление пользователей
    • при включенном переключателе () обновление связанных пользовательских атрибутов (указаны в графе Маппинг атрибутов на Шаге 3 данной инструкции) на стороне IdP приводит к автоматическому обновлению данных атрибутов на стороне Avanpost Identity Cloud;
    • при включенном переключателе () автоматическое обновление пользовательских атрибутов на стороне Avanpost Identity Cloud не осуществляется;
  • Подтверждение информации пользователем
    • при включенном переключателе () после создания нового пользователя в момент первичной авторизации пользователю показываются значения его атрибутов для подтверждения;
    • при включенном переключателе () новому пользователю не показываются его атрибуты для подтверждения при первой авторизации;
  • Обогащение информации пользователем
    • при включенном переключателе () после создания нового пользователя в момент первичной авторизации отображаемые значения атрибутов доступны пользователю для редактирования;
    • при включенном переключателе () новому пользователю не доступно редактирование атрибутов при первичной авторизации;
  • Подтверждение паролем
    • при включенном переключателе () выполняется связывание пользователей Avanpost Identity Cloud и внешнего IdP посредством дополнительной аутентификации (например, если при авторизации посредством внешнего IdP в Avanpost Identity Cloud не находится пользователь, связанный с этим IdP, Avanpost Identity Cloud предлагает ввести логин-пароль и на основании введенных данных связывает УЗ в Avanpost Identity Cloud и во внешнем IdP) 
    • при включенном переключателе () связывание пользователей Avanpost Identity Cloud и внешнего IdP посредством дополнительной аутентификации недоступно;
  • Множественная учетная запись
    • при включенном переключателе () допускается использование нескольких учетных записей: пользователю будет предложен выбор учетной записи из списка найденных в Avanpost Identity Cloud/создаваемых при помощи внешнего IdP;
    • при включенном переключателе () использование нескольких учетных записей недоступно пользователю.
Группа по умолчаниюГруппа, в которую по умолчанию добавляются новые пользователи, загружаемые с внешнего провайдера идентификации. В текстовое поле требуется ввести название существующей в Avanpost Identity Cloud группы.
Активный

Чекбокс "Активный":

  • при установленном чекбоксе созданный IdP запускается сразу после создания (присваивается статус Active);
  • при выключенном чекбоксе созданный IdP не запускается сразу после создания (присваивается статус Inactive): для запуска требуется активизировать созданный провайдер в его профиле.

Чтобы сохранить созданный IdP необходимо нажать кнопку "Сохранить". Для перехода к предыдущему шагу — нажать "Назад". Для отказа от создания нового IdP следует нажать "Отмена". 

Настройка существующего провайдера идентификации

Дополнительная настройка созданного IdP осуществляется в его профиле. Для перехода в профиль IdP требуется войти в раздел "Настройки внешних провайдеров идентификации (IdP)" режима "Сервис" и нажать на  название искомого провайдера. При необходимости администратор может воспользоваться поиском, введя название искомого IdP в поисковую строку.

Профиль провайдера идентификации содержит следующую информацию и возможности:

  • Вкладка "Основные настройки" - Вкладка содержит параметры, настраиваемые на Шаге 1 и Шаге 4 создания нового провайдера идентификации;
  • Вкладка "Настройки перенаправления" - Вкладка содержит параметры, настраиваемые на Шаге 2 создания нового провайдера идентификации;
  • Вкладка "Настройки callback" - Вкладка содержит:
    • параметр "Callback URI", доступный для копирования нажатием на кнопку (для редактирования параметр недоступен);
    • параметры, настраиваемые на Шаге 3 создания нового провайдера идентификации;
  • Кнопка "Изменить" - Нажать, чтобы добавить/изменить иконку IdP (после нажатия откроется окно, в котором потребуется указать путь до графического файла);
  • Кнопка / - Включить/выключить возможность редактирования параметров во вкладках "Основные настройки", "Настройки перенаправления", "Настройки callback".
  • Кнопка / - Включить (перевести в статус "Actice")/выключить (перевести в статус "Inactice") данный IdP (после нажатия кнопки запрашивается подтверждение действия); 
  • Кнопка - Удалить данный IdP (после нажатия кнопки запрашивается подтверждение действия);
  • Кнопка "Сохранить" - Сохранить внесенные изменения (доступна после нажатия кнопки );
  • Кнопка "Отмена" - Отменить внесение изменений (доступна после нажатия кнопки ).

Приложение А. Значения данных для различных провайдеров идентификации 

В таблице представлены значения параметров, рекомендуемых к заполнению в разделе "Данные" на Шаге 1 создания нового провайдера аутентификации. 

Если в качестве типа IdP выбран "Другие", Avanpost Identity Cloud не создает поля с параметрами в разделе "Данные" автоматически. Avanpost Identity Cloud дает администратору возможность подключиться к кастомизированному внешнему IdP, заполнив поля в разделе "Данные" в соответствии с настройками данного IdP.

ПараметрОписание
OpenID Connect
baseUrl

Адрес, на который пользователь будет перенаправляться при переходе из личного кабинета.

Для упрощения настройки ссылка на данный параметр автоматически подставляется в дальнейших настройках при указании пути до того или иного объекта на стороне IdP.

scopeОбласти доступа (scopes), т.е. запрашиваемые права. В составе jwt-токена, отправляемого провайдером идентификации будут передаваться claim'ы, входящие в запрошенные scope.
clientIDУникальный идентификатор Avanpost Identity Cloud.
clientSecretСекрет, который будет использоваться для подключения.
SAML
baseUrlАдрес, на который пользователь будет перенаправляться при переходе из личного кабинета.
idp_issУникальный идентификатор (Issuer) IdP.
sp_issУникальный идентификатор (Issuer) SP, т.е. Avanpost Identity Cloud.
audЗначение параметра соответствует Audience URI. Параметр содержит набор (аудиторию) субъектов, которым разрешено использовать сгенерированное Assertion. 
sig

Подпись запроса аутентификации:

  • true - запрос аутентификации подписывается;
  • false - запрос аутентификации не подписывается (обычно используется при тестировании).
ver

Пропускать проверку подписи:

  • true - проверка подписи Assertion не осуществляется (обычно используется при тестировании);
  • false - проверка подписи Assertion осуществляется.
certСертификат в формате base64. 

Приложение Б. Рекомендации по настройке параметров перенаправления

В таблице представлены значения параметров, рекомендуемых к заполнению в разделе "Параметры перенаправления" на Шаге 2 создания нового провайдера аутентификации.

ПараметрОписание
OpenID Connect
response_type

Тип ответа, который ожидается от OIDC-провайдера.

Рекомендуется использовать значение code (Avanpost Identity Cloud получает от IdP авторизационный код).

client_id

Уникальный идентификатор Avanpost Identity Cloud.

Ссылается на параметр clientID, предварительно указанный в разделе "Детали" Шага 1 данной инструкции. Пример значения параметра: {{.extidp_details.clientID}}.

scope

Области доступа (scopes), т.е. запрашиваемые права.

Ссылается на параметр scope, предварительно указанный в разделе "Детали" Шага 1 данной инструкции. Пример значения параметра: {{ .extidp_details.scope }}.

redirect_uri

Ссылка, по которой должен быть направлен пользователь после того, как даст разрешение на доступ к ресурсу.

Значение параметра должно быть предварительно указано в параметрах при настройке внешней IdP. Пример значения параметра: {{.extidp_request.CallbackURI}}.

Приложение В. Скрипты получения информации о пользователе.

В последовательности действий для получения информации о пользователе, применяемая на шаге 3, используются по преимуществу следующие методы. 

МетодНазначениеПример
"jwt" Парсинг claim'ов из токена.

jwt(token.id_token) - парсинг claim'ов из токена, указанного в параметре token.id_token.


"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 Identity Cloud реализована подпись посредством КриптоПро).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.


Обсуждение