/
Настройка ADFS в Keycloak

Настройка ADFS в Keycloak

Предварительные условия

Перед началом настройки интеграции Keycloak с ADFS убедитесь, что выполнены следующие условия:

  • На Windows Server установлен Active Directory Federation Services (ADFS).

  • Сервер Keycloak (версии 26 и выше) настроен для работы по протоколу HTTPS.

  • Настроен DNS для обоих серверов.

Настройка сервера Keycloak

Настройка HTTPS для Keycloak

ADFS требует, чтобы Keycloak работал по защищенному протоколу HTTPS. Выполните следующие шаги:

  1. Настройте входящие HTTPS-соединения для Keycloak (следуйте официальному руководству по установке сервера).

  2. Экспортируйте сертификат ADFS:

    • Откройте консоль управления ADFS.

    • Перейдите в раздел Service > Certificates.

    • Экспортируйте сертификат Service communications.

  3. Добавьте сертификат в keystore keycloak, отредактировав файл platform.yml и добавив в сервис keycloak следующие записи о сертификате:

    environment: KC_TRUSTSTORE_PATHS: "/opt/keycloak/conf/truststores/adfs.pem" volumes: - ./adfs.pem:/opt/keycloak/conf/truststores/adfs.pem

Создание Identity Provider в Keycloak

  1. Войдите в консоль администратора в Keycloak по адресу:
    http(s)://<domen>/v3/keycloak/admin/Visiology/console
    где <domen> – домен или IP-адрес сервера платформы.

  2. В боковой панели выберите Поставщики идентификации:

    identity-providers.png

  3. Выберите тип "SAML v2.0".

  4. В открывшемся окне задайте псевдоним (alias) для провайдера идентификации, например "adfs-idp-alias".

  5. В поле с текстом “Позволяет вам загрузить метаданные внешнего IDP из файла конфигурации или скачать его из URL” введите URL-адрес дескриптора ADFS. Для ADFS 3.0 этот URL выглядит следующим образом:

       https://kc.domain.name/FederationMetadata/2007-06/FederationMetadata.xml

  6. Нажмите Добавить и затем проверьте автоматически заполненные настройки.

  7. Включите опцию Проверка подписей:

    verify-signs.png

  8. Если запросы аутентификации, отправляемые в ADFS, должны быть подписаны, включите опцию Ожидание подписи AuthnRequests:

    AuthnRequests.png

  9. После включения этой опции установите SAML Signature Key Name в CERT_SUBJECT, так как ADFS ожидает, что подсказка с именем ключа подписи будет субъектом сертификата подписи.

  10. Установите в поле Формат политики NameID формат Windows Domain Qualified Name (или Persistent, в зависимости от вашей конфигурации ADFS):

    format.png

  11. Сохраните настройки.

Настройка маппера для Identity Provider

На вкладке "Mappers" созданного провайдера настройте маппинги атрибутов:

  1. Маппер для групп:

    • Имя: "Group: managers".

    • Тип: "SAML Attribute to Role".

    • Атрибут: "http://schemas.xmlsoap.org/claims/Group".

    • Значение атрибута: "managers".

    • Роль: "manager".

  2. Маппер для электронной почты:

    • Имя: "Attribute: email".

    • Тип: "Attribute Importer".

    • Атрибут: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress".

    • Имя пользовательского атрибута: "email".

Настройка ADFS для работы с Keycloak

Получение информации для настройки ADFS

Получите URI SAML service provider descriptor, который будет использоваться при настройке ADFS

URI:

https://kc.domain.name/v3/keycloak/realms/Visiology/protocol/saml/descriptor

Если метаданные не работают, создайте доверие вручную:

В окне Add Relying Party Trust Wizard:

  1. Выберите Enter data about the relying party manually.

  2. Укажите отображаемое имя: "Keycloak Visiology".

  3. Пропустите настройку сертификата (можно будет добавить позже).

  4. Включите поддержку SAML 2.0.

  5. Добавьте адрес (Relying party SAML 2.0 SSO service URL):

    https://kc.domain.name/v3/keycloak/realms/Visiology/protocol/saml

  6. Добавьте идентификатор доверяющей стороны (Relying party trust identifier):

    https://kc.domain.name/v3/keycloak/realms/Visiology

  7. Выберите Permit all users to access this relying party.

  8. Завершите работу мастера.

Настройка Relying Party Trust в ADFS

Настройка Relying Party

  1. В консоли управления ADFS выберите Trust relationships, щелкните правой кнопкой мыши на Relying Party Trusts и выберите Add Relying Party Trust.

  2. В начале мастера введите URL SAML descriptor, полученный на предыдущем шаге, в поле Federation metadata address.

  3. Позвольте ADFS импортировать настройки и продолжите работу мастера.

  4. При необходимости настройте параметры. В этом примере используются только настройки по умолчанию.

  5. Не забудьте отредактировать правила утверждений (claim rules), поэтому на последней странице мастера оставьте флажок Configure claims issuance policy включенным.

Настройка Claim Mapping

Правило для отправки Name ID

Это обязательное правило для идентификации пользователя:

  1. В окне Edit Claim Rules нажмите Add Rule.

  2. Выберите тип правила Transform an incoming claim.

  3. Выполните следующие настройки:

    • Name: "Send UPN as Name ID".

    • Incoming claim type: UPN.

    • Outgoing claim type: Name ID.

    • Outgoing name ID format: Persistent или Email (выберите в соответствии с форматом в метаданных Keycloak).

    • Pass through all claim values: ✓.

Правило для отправки электронной почты

  1. Нажмите Add Rule.

  2. Выберите тип правила: Send LDAP Attributes as Claims.

  3. Выполните следующие настройки:

    • Name: "Email Claims"

    • Attribute store: Active Directory.

    • Mapping (добавьте следующие отображения):

      • LDAP Attribute: E-Mail-Addresses > Outgoing Claim Type: E-Mail Address.

      • LDAP Attribute: Display-Name > Outgoing Claim Type: Name.

      • LDAP Attribute: Given-Name > Outgoing Claim Type: Given Name.

      • LDAP Attribute: Surname > Outgoing Claim Type: Surname.

Правило для отправки групп (если требуется)

  1. Нажмите Add Rule.

  2. Выберите тип правила: Send Group Membership as a Claim.

  3. Выполните следующие настройки:

    • Name: "Group Membership".

    • User's group: выберите нужные группы AD или "All groups".

    • Outgoing claim type: Group.

Дополнительное правило для сохранения формата группы (опционально)

Если группы передаются в формате "DOMAIN\group", но вам нужны только названия групп:

  1. Нажмите Add Rule.

  2. Выберите тип правила: Transform an incoming claim.

  3. Выполните следующие настройки:

    • Name: "Group Name Transform".

    • Incoming claim type: Group.

    • Outgoing claim type: Group.

    • Transform rule: Regular expression pattern:

      • Pattern: ^VISIOLOGY\\(.*)$

      • Replacement: $1

Правило для сопоставления ролей (опционально)

Если нужно сопоставить группы AD с определенными ролями в Keycloak:

  1. Нажмите Add Rule.

  2. Выберите тип правила: Send Claims Using a Custom Rule

  3. Напишите скрипт на языке правил утверждений, например:

       c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value =~ "^S-1-5-21-.*-513$"] => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/role", Value = "Domain Users");

После настройки всех правил нажмите Apply и OK.

Устранение неполадок

В случае проблем:

  1. Проверьте сообщения SAML, отправляемые между Keycloak и ADFS в браузере. Декодеры SAML доступны как расширения браузера (например, SAML Tracer для Firefox, SAML Chrome Panel для Chrome)

  2. Проверьте логи:

    • Для ADFS: в Event viewer в разделе Applications and Services Logs > ADFS > Admin.

    • В Keycloak включите трассировку обработки SAML, подключившись к работающему экземпляру Keycloak через jboss-cli.sh и выполнив следующие команды:

           /subsystem=logging/logger=org.keycloak.saml:add(level=DEBUG)      /subsystem=logging/logger=org.keycloak.broker.saml:add(level=DEBUG)

Возможные проблемы

Проблема: Невозможно выйти из системы. При нажатии на кнопку выхода в приложении кажется, что выход из Keycloak выполнен, но при возврате в приложение форма входа ADFS никогда не отображается и происходит перенаправление обратно с аутентификацией того же пользователя, что и ранее.

Решение: Это не проблема Keycloak, а настройки политики аутентификации ADFS. Попробуйте отключить Windows Authentication.

Проблема: При использовании ADFS в Windows 2016 в логе Keycloak появилась следующая ошибка после импорта дескриптора из URL: RESTEASY002010: Failed to execute: javax.ws.rs.NotFoundException.

Решение: Это безвредная ошибка. Версия Windows 2016 сначала проверяет URL-адрес дескриптора, похожего на ADFS, добавляя FederationMetadata/2007-06/FederationMetadata.xml к введенному URL. Такой ресурс в Keycloak не существует, поэтому он сообщает об ошибке. Однако ADFS, похоже, импортирует с использованием введенного URL, когда это происходит.

Если у вас возникли сложности или вопросы по работе с Keycloak, пожалуйста, обратитесь за помощью на официальный форум сообщества пользователей или подпишитесь на тематические рассылки Keycloak.

Смотрите также

Настройка Keycloak с Kerberos и Active Directory

На этой странице

Время чтения: 2 мин.

Нужна дополнительная помощь?

Свяжитесь с технической поддержкой.