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

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

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

Войдите в аккаунт администратора Keycloak.
Откройте консоль управления — нажмите Administration Console.
Создайте SAML-приложение и настройте его:
1. На панели слева выберите Clients и нажмите кнопку Create Client.
2. В поле Client ID введите https://yandex.ru/ (обязательно со слешем в конце).
3. В поле Client type укажите SAML и нажмите Save.
4. В поле Name укажите имя приложения, например yandexID.
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. Чтобы выбранный вариант передавался вне зависимости от настроек организации ID, включите опцию 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. Если ваши сотрудники пользуются Яндекс ID не только на русском домене, в поле 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. Настройте сопоставление атрибутов пользователей

На вкладке Client scopes откройте Client scope, который соответствует создаваемому клиенту, например https://yandex.ru/-dedicated.
На вкладке Scope отключите опцию Full Scope Allowed.
Перейдите на вкладку Mappers, нажмите кнопку Add Mapper и выберите пункт By Configuration.
В открывшемся окне выберите пункт User Property.
Создайте поочередно необходимые атрибуты:
- 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 такой же, как и основной домен организации. Если они не совпадают, вы увидите сообщение об ошибке.

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

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

Настройка Avanpost FAM

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