Настройка Keycloak версии 19 и выше

Чтобы организовать единый вход (SSO) в сервисы Яндекс 360 через Keycloak, нужно предварительно создать и настроить SAML-приложение.

Шаг 1. Создайте и настройте SAML-приложение

  1. Войдите в аккаунт администратора Keycloak.

  2. Откройте консоль управления — нажмите Administration Console.

  3. Создайте SAML-приложение и настройте его:

    1. На панели слева выберите Clients и нажмите кнопку Create Client.

    2. В поле Client ID введите https://yandex.ru/ (обязательно со слешем в конце).

    3. В поле Client type укажите SAML и нажмите Save.

    4. В поле Name укажите имя приложения, например yandex360.

    5. В поле Root URL введите Service URL: https://passport.yandex.ru/auth/sso/commit.

    6. В поле Valid Redirect URIs введите Service URL: https://passport.yandex.ru/auth/sso/commit и https://passport.yandex.com/auth/sso/commit.

    7. В полях IDP Initiated SSO Relay State и Master SAML Processing URL введите Service URL: https://passport.yandex.ru/auth/sso/commit.

    8. Опции, заполненные по умолчанию (Enabled, Include AuthnStatement, Sign Documents и др.), оставьте без изменений.

    9. В качестве Name ID Format выберите email. Чтобы выбранный вариант передавался вне зависимости от настроек Яндекс 360, включите опцию Force Name ID format.

      Примечание

      Значение атрибута NameID нельзя изменить — он используется для идентификации пользователя в Яндекс ID. Если вы меняете UPN, в качестве NameID укажите один из неизменяемых атрибутов пользователей в вашем каталоге LDAP.

      Если нужен настраиваемый NameID, задайте его по умолчанию в настройках сопоставления атрибутов пользователя: на вкладке Client Scopes откройте Client scope, который соответствует создаваемому клиенту, например https://yandex.ru/-dedicated, на вкладке Mappers создайте новый User Attribute Mapper For NameID (Add mapper – By configuration).

    10. Если ваши сотрудники пользуются сервисами Яндекс 360 не только на русском домене, в поле Valid Redirect URIs дополнительно добавьте URL языковых доменов в качестве конечных точек.

      Конечные точки для языковых доменов:

      • https://passport.yandex.com/auth/sso/commit — для английского;

      • https://passport.yandex.kz/auth/sso/commit — для казахского;

      • https://passport.yandex.uz/auth/sso/commit — для узбекского;

      • https://passport.yandex.com.tr/auth/sso/commit — для турецкого.

      Полный список

      • https://passport.yandex.com/auth/sso/commit

      • https://passport.yandex.az/auth/sso/commit

      • https://passport.yandex.by/auth/sso/commit

      • https://passport.yandex.co.il/auth/sso/commit

      • https://passport.yandex.com/auth/sso/commit

      • https://passport.yandex.com.am/auth/sso/commit

      • https://passport.yandex.com.ge/auth/sso/commit

      • https://passport.yandex.com.tr/auth/sso/commit

      • https://passport.yandex.ee/auth/sso/commit

      • https://passport.yandex.eu/auth/sso/commit

      • https://passport.yandex.fi/auth/sso/commit

      • https://passport.yandex.fr/auth/sso/commit

      • https://passport.yandex.kg/auth/sso/commit

      • https://passport.yandex.kz/auth/sso/commit

      • https://passport.yandex.lt/auth/sso/commit

      • https://passport.yandex.lv/auth/sso/commit

      • https://passport.yandex.md/auth/sso/commit

      • https://passport.yandex.pl/auth/sso/commit

      • https://passport.yandex.ru/auth/sso/commit

      • https://passport.yandex.tj/auth/sso/commit

      • https://passport.yandex.tm/auth/sso/commit

      • https://passport.yandex.uz/auth/sso/commit

    11. Нажмите Save.

    12. На вкладке Keys в разделе Signing keys config выключите опцию Client Signature Required, если она включена, и еще раз нажмите Save.

Шаг 2. Настройте сопоставление атрибутов пользователей

  1. На вкладке Client scopes откройте Client scope, который соответствует создаваемому клиенту, например https://yandex.ru/-dedicated.

  2. На вкладке Scope отключите опцию Full Scope Allowed.

  3. Перейдите на вкладку Mappers, нажмите кнопку Add Mapper и выберите пункт By Configuration.

  4. В открывшемся окне выберите пункт User Property.

  5. Создайте поочередно необходимые атрибуты:

    • X500 email — адрес электронной почты;

    • X500 surname — фамилия;

    • X500 givenName — имя.

  6. Настройте синхронизацию атрибутов Keycloak и Яндекс 360: откройте каждый атрибут и измените значение SAML Attribute Name. Значения SAML Attribute Name, которые поддерживаются в Яндекс 360, приведены ниже.

    SAML Attribute Name

    Value

    User.EmailAddress

    X500 email

    User.Firstname

    X500 givenName

    User.Surname

    X500 surname

    В итоге сопоставление атрибутов будет выглядеть так:

Ответ SAML должен иметь вид:

<Attribute Name="User.EmailAddress">
    <AttributeValue>email@test.com</AttributeValue>
</Attribute>
<Attribute Name="User.Surname">
    <AttributeValue>Surname</AttributeValue>
</Attribute>
<Attribute Name="User.Firstname">
    <AttributeValue>Firstname</AttributeValue>
</Attribute>

Шаг 3. Соберите данные, которые нужно будет передать Яндекс 360

URL страницы входа

Адрес точки входа.

Чтобы получить:

1. В консоли управления на панели слева выберите Realm Settings и нажмите ссылку SAML 2.0 Identity Provider Metadata.

2. Нужное значение находится в поле Location, скопируйте его.

Издатель поставщика удостоверений

Entity ID домена.

Получить можно также, как и URL страницы входа. Нужное значение находится в поле entityID.

Проверочный сертификат

Сертификат подписи токенов формата X.509.

Получить можно также, как и URL страницы входа. Нужное значение находится в поле X509Certificate.

Также сертификат можно скопировать со вкладки Keys:

1. Перейдите к строке RS256.

2. Скопируйте содержимое Certificate.

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

После этого переходите к настройке Яндекс 360 для бизнеса.

Решение проблем с настройкой

Если в процессе настройки поставщика удостоверений заданы неверные значения, то при попытке входа через SSO вы увидите сообщение «Авторизация не удалась» и код ошибки:

email.no_in_response

Указывайте имена атрибутов в формате User.Firstname, User.Surname, User.EmailAddress. Если задать другой формат, например Firstname, авторизоваться не получится.

request_your_admin

Ошибка появляется, если администратор каталога пользователей вашей организации ограничил для аккаунта доступ к Яндекс 360. За подробной информацией обратитесь к специалистам технической поддержки вашей организации.

samlresponse.invalid

Ошибка возникает, если неверно указаны URL страницы входа, издатель поставщика удостоверений или проверочный сертификат. Проверьте корректность этих настроек SSO в Яндекс 360 для бизнеса.

unsupportable_domain

Проверьте, что домен из почтового атрибута User.EmailAddress в SAML response такой же, как и основной домен или один из доменов-алиасов организации Яндекс 360. Если они не совпадают, вы увидите сообщение об ошибке.
Написать в службу поддержки
Предыдущая
Настройка Keycloak версии 18
Следующая
Настройка Avanpost FAM