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

Настройка 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. Чтобы это сделать, в ADFS нужно создать Application Group, которая моделирует набор защищенных ресурсов и клиентов, которые могут к ним обращаться.

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’ приложение должно появится в папке ‘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​

1. В веб-интерфейсе Keycloak выберите ваш realm и во вкладке identity-providers добавьте «OpenID Connect v1.0».

Добавление openid provider в keycloak
attachment icon

2. Вставьте в поле Discovery endpoint ссылку на конфигурацию OpenID Connect provider ведущую в ваш AD FS. Проверить, доступен ли документ с конфигурацие, можно отправив запрос GET с помощью любого HTTP-клиента - браузера, curl или Postman. Ответом на запрос будет JSON документ.

curl  https://fs.domain.com/adfs/.well-known/openid-configuration

3. Измените следующие значения:

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

Сохраните настроенный identity provider.

4. Еще раз откройте конфигурацию созданного провайдера и настройте поле:

  • Disable User Info: ON

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

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

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

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

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

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

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

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

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

редирект в adfs
attachment icon

подсказка

Необходимо указать название Identity provider в поле Default Identity Provider

примечание

Поле Default Identity Provider регистро-чувствительно, необходимо убедиться что название Default Identity Provider указано в том же регистре как указано в поле Alias для текущего Identity Provider

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

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

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

Использование SSO совместно с миграцией пользователей в команды​

Для комбинирования функционала миграции пользователей в существующие команды (например при использовании групп из ADFS), необходимо добавить миграцию пользователей из LDAP в тот же Realm используемый для системы единого входа.

подсказка

Настройку миграции полей из LDAP/ADFS необходимо настроить на уровне LDAP.

  1. Настройте миграцию пользователей из LDAP совместно с маппингом полей
примечание

Необходимо убедиться что конфигурация миграции из LDAP и маппинг аттрибутов Identity Provider ADFS настроен коректно. Важно чтобы поля username и email были сконфигурированы одинако в обоех конфигурациях

  1. В Keycloak перейдите в настройки "Authentication" и добавить новую схему.
  • "Создать схему", введите имя схемы, например "First login link"
  • Добавить шаги "Detect existing broker user" и "Automatically set existing user". Необходимо также для обоих шагов добавить тип "Required"
    First login link
    attachment icon
  1. Настроить конфигурацию adfs созданную ранее
  • В поле "First login flow override" добавить конфигурацию сделанную на шаге 2 (First login link)
  • Изменить поле "Sync mode" на "Import"
  • Сохраните конфигурацию
подсказка

После применения конфигурации убедитесь что все пользователи из LDAP смигрированы и отображаются во вкладке Users интерфейса Keycloak. Для проверки конфигурации, осуществите вход с помощью AD FS SSO и убедитесь в том во вкладке "Identity provider links" появился провайдер ADFS (произошла корректная привязка пользователя из AD FS к пользователю из LDAP)

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