Перейти к основному содержимому

Настройка SSO через ADFS

Предварительные Требования​

Для настройки необходимо:

  • Microsoft Windows Server 2019 c настроенными AD и AD FS.
  • YuChat Keycloak сервер (входит в комплект поставки)

На сервисах должны быть корректно настроен HTTPS:

подсказка

Для корректной работы необходимо наличие глобальных сертификатов для AD FS и Keycloak.

примечание

Рекомендация: на стороне Keycloak используйте отдельный реалм для авторизации через AD FS SSO.

Добавление Keycloak в качестве клиента в AD FS​

Поскольку мы будем использовать AD FS в качестве доверенного поставщика, Keycloak должен быть определен как клиент OAuth 2. Чтобы это сделать, нам сначала нужно создать Application Group — сущность AD FS, которая моделирует набор защищенных ресурсов и клиентов, которые могут к ним обращаться. OAuth различает 2 типа клиентов: публичные и конфиденциальные. Первые работают на устройствах, находящихся под контролем конечного пользователя, например, в браузере на рабочем столе или на телефоне, а вторые — в бэкэнде. Microsoft называет эти приложения соотвественно нативными и серверными. В рамках данной интеграции необходимо настройка серверного приложения.

Keycloak получит ID токен в качестве клиента и затем создаст удостоверение на основе утверждений в ID токене AD FS. Но некоторая информация, которая нам нужна, недоступна в качестве стандартного утверждения ID токена, поэтому нам нужно настроить некоторые пользовательские утверждения. Для настройки этого необходимо создать API в Application Group.

Создание Серверного Приложения В Application Group​

В AD FS, откройте ‘Application Groups’, и нажмите ‘Add Application Group…’ в контекстном меню.

добавление сервера в adfs
attachment icon

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

URI перенаправления будет отличаться в случае создания нескольких реалмов в Keycloak. Мы сможем проверить этот URI позже, когда доберемся до настройки Keycloak. Подтвердите конфигурацию и завершите мастер. Группа приложений «keycloak» должна быть создана.

Проверьте конфигурацию и завершите настройку. ‘keycloak’ приложение должно появится в папке ‘Application Groups’ после завершения.

добавление сервера в adfs - результат
attachment icon

Создание Api​

Для настройки токена возвращаемого в Keycloak, необходимо создать серверное API. Для его создание нажмите 2 раза на ‘keycloak’ в папке application group, и выберите ‘Add application…’.

добавление api в adfs
attachment icon

Используйте следующие значения в мастере настроек:

  • Name: keycloak - API (или любое другое имя)
  • Identifier: keycloak (должно соответствовать полю Client Identifier в серверном приложении)
  • Access control policy: Permit everyone
  • Permitted scopes: выберите allatclaims в добавлении к openid который выбран по умолчанию

Область allatclaims предназначена для копирования из AD FS всех полей из access token в id token для передачи в Keycloak.

Проверьте конфигурацию и завершите настройку API. После завершения вы увидите созданное API в серверном приложении ‘keycloak’.

добавление api в adfs - результат
attachment icon

Настройка Маппинга Полей Данных​

Настройка AD FS почти готова, но для корректной идентификации пользователя в YuChat Keycloak необходима настройка соответствия полей данных. Для корректной работы необходимо передать следующие поля: email, given_name, и family_name. Так как уже настроена передача всех полей через allatclaims эти данные уже будут содержаться в id token передаваемого в Keycloak.

Откройте серверное приложение ‘keycloak’ и нажмите 2 раза на ‘keycloak - Web API’ для открытия конфигурации. Перейдите на вкладку ‘Issuance Transform Rules’ и нажмите ‘Add Rule…’. Для передачи полей будем использовать ‘Send LDAP Attributes as Claims’ шаблон.

Используйте следующую конфигурацию:

  • Claim rule name: Attributes (или любое другое имя по вашему выбору)
  • Attribute store: Active Directory
  • Mappings:
    • E-Mail-Addresses => email
    • Given-Name => given_name
    • Surname => family_name

Поля email, given_name, family_name не будут отображаться в выпадающем списке, вам необходимо добавить эти значения вручную.

добавление маппинга полей в adfs
attachment icon

Вы также можете добавлять другие аттрибуты при необходимости. В примере выше указаны обязательные значения необходимые для корректной работы YuChat. Эти данные необходимы для создания имя пользователя автоматически при первом входе в YuChat.

Добавление AD FS в качестве провайдера авторизации​

В предыдущих разделах Keycloak был добавлен в качестве клиента в AD FS, но теперь необходимо провести настройку Keycloak и добавить AD FS в качестве основного способа авторизации в YuChat.

Импорт конфигурации ad fs в keycloak​

Сначала мы должны добавить AD FS в качестве OpenID Provider. Перейдите на экран «Поставщики удостоверений» и создайте нового поставщика «OpenID Connect v1.0». Это открывает длинную форму, которую мы можем заполнить вручную, но удобнее указать в конфигурации Keycloak ссылку с данными конфигурации. Местоположение, синтаксис и содержание этого документа были стандартизированы в спецификации OpenID Connect Discovery. Мы проверяем, действительно ли документ доступен, отправив запрос GET с помощью нашего любого HTTP-клиента, например, браузера, curl или Postman:

GET /adfs/.well-known/openid-configuration HTTP/1.1  
Host: fs.domain.com

Не забудьте использовать https:// в качестве схемы. Ответом на запрос будет JSON документ. Вместо копирования всех полей документа можно использовать URL для импорта полей в Keycloak, для этого необходимо вставить ссылку в поле ‘Import External IDP Config’. При нажатии кнопки Import все поля будут автоматически подставлены в Keycloak.

Перед сохранением настроек необходимо изменить следующие значения:

  • Alias: ADFS (этот alias используется в формировании redirect URL)
  • Client ID: keycloak (должен соответствовать Client Identifier настроенному в AD FS)
  • Client Secret: этот секрет был создан на этапе создания серверного приложения в AD FS

Сохраните настройки identity provider, еще раз откройте конфигурацию созданного провайдера и настройте поле:

  • Disable User Info: ON

Данную настройку необходимо выключить так как на стороне AD FS уже модифицирован токен для передачи в Keycloak.

Еще раз проверьте конфигурацию нового провайдера в Keycloak, в частности все ‘Redirect URI’ которые должны соответствовать настройкам в AD FS и сохраните форму.

Настройка маппинга полей в Keycloak​

Keycloak принимает информацию из AD FS и сохраняет в локальной базе данных для дальнейшего использования ее в YuChat. Для корректной авторизации в YuChat и отображения имени пользователя необходимо настроить маппинг полей.

Необходимо перейти во вкладку ‘Mappers’ в созданном провайдере в Keycloak и добавить 3 правила, каждое из которых будет использовать тип ‘Attribute Importer’:

  • email => email
  • given_name => firstName
  • family_name => lastName
добавление маппинга в keycloak
attachment icon

Настройка сквозного SSO через AD FS​

Keycloak используется в качестве единого авторизационного инструмента в YuChat, но при необходимости можно настроить сквозную авторизацию через AD FS. Для этого необходимо в настройках соответствующего realm перейти во вкладку Authentication и создать новую схему для браузерной аутентификации.

1. Скопируйте встроенную конфигурацию “browser” в новую, для этого необходимо нажать три точки в конце строки и выбрать меню Duplicate
2. Введите имя для новой конфигурации (yuchat-adfs-flow) перейдите в настройки
3. Настройте Identity Provider Redirector (необходимо нажать шестеренку на строке) и введите Alias созданный на этапа импорта конфигурации в Keycloak

редирект в adfs
attachment icon
4. Required в качестве параметра для Identity Provider Redirector
5. Удалите шаг “Username, password, otp and other auth forms” из списка шагов авторизации

настройки аутентификации
attachment icon
подсказка

После применения настроек, при нажатии кнопки «Войти через SSO» в интерфейсе YuChat пользователь будет направлен напрямую на форму авторизации ADFS (например уже авторизаван в интерфейсе Outlook Web Interface). В случае если пользователь уже авторизован в AD FS он попадет сразу в YuChat (даже при первом входе)

Последнее обновление