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

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

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

Войдите в аккаунт администратора Keycloak.
Откройте консоль управления — нажмите Administration Console.
Создайте SAML-приложение:
1. На панели слева выберите Clients и нажмите кнопку Create.
2. В поле Client ID введите https://yandex.ru/ (обязательно со слешем в конце).
3. В поле Client Protocol укажите saml.
4. В поле Client SAML Endpoint введите Service URL: https://passport.yandex.ru/auth/sso/commit. Нажмите Save.
На вкладке Settings настройте параметры SAML-приложения:
1. В поле Name укажите имя приложения, например yandexID.
2. Выключите опцию Client Signature Required, если она включена.
3. Опции, которые заполнены по умолчанию (Enabled, Include AuthnStatement, Sign Documents и др.), оставьте без изменений.
4. В качестве Name ID Format выберите email. Чтобы выбранный вариант передавался вне зависимости от настроек организации ID, включите опцию Force Name ID format.
  
  Примечание
  
  Значение атрибута NameID нельзя изменить — он используется для идентификации пользователя в Яндекс ID. Если вы меняете UPN, в качестве NameID укажите один из неизменяемых атрибутов пользователей в вашем каталоге LDAP.
  
  Если нужен настраиваемый NameID, задайте его по умолчанию в настройках сопоставления атрибутов пользователя: в меню Mappers создайте новый User Attribute Mapper For NameID.
5. В полях Valid Redirect URIs, Base URL, Master SAML Processing URL введите Service URL: https://passport.yandex.ru/auth/sso/commit. Нажмите Save.
6. Если ваши сотрудники пользуются Яндекс ID не только на русском домене, в поле Valid Redirect URIs дополнительно добавьте URL языковых доменов в sкачестве конечных точек.
Конечные точки для языковых доменов:
- 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

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

На вкладке Scope отключите опцию Full Scope Allowed.
Перейдите на вкладку Mappers и нажмите кнопку Add Builtin.
Отметьте атрибуты в списке и нажмите Add selected:
- X500 email — адрес электронной почты;
- X500 surname — фамилия;
- X500 givenName — имя.
Настройте синхронизацию атрибутов Keycloak и организации ID: откройте каждый атрибут и измените значение SAML Attribute Name. Значения SAML Attribute Name, которые поддерживаются в Яндекс ID, приведены ниже.

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. Соберите данные, которые нужно будет передать Яндекс ID

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.

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

После этого переходите к настройке организации ID.

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

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

email.no_in_response

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

request_your_admin

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

samlresponse.invalid

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

unsupportable_domain

: Проверьте, что домен из почтового атрибута User.EmailAddress в SAML response такой же, как и основной домен организации. Если они не совпадают, вы увидите сообщение об ошибке.

Была ли статья полезна?

Настройка Azure Active Directory (EN)

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

SAML Attribute Name	Value
User.EmailAddress	X500 email
User.Firstname	X500 givenName
User.Surname	X500 surname