Добрый день!

Сегодня я хочу поговорить о механизме Identity Brokering внутри Keycloak, а точнее о возможности использовать один realm как Identity Provider для другого. Звучит просто, но на практике нюансов хватает, поэтому давайте разберёмся по порядку.

Что такое Identity Brokering

Identity Broker - это посредник, который устанавливает доверительные отношения между сервис-провайдером (приложением, которому нужна аутентификация) и одним или несколькими Identity Provider-ами (источниками учётных данных). В контексте Keycloak это означает, что один realm может делегировать аутентификацию другому realm-у - как внутри одного инстанса Keycloak, так и между разными серверами.

Суть проблемы: представьте, что в вашей организации несколько подразделений, каждое со своим realm-ом в Keycloak. У отдела разработки свой realm dev-realm с разработчиками, у HR - свой hr-realm с кадровиками. И вот появляется корпоративный портал, которому нужно пускать и тех, и других. Заводить всех пользователей заново? Синхронизировать базы руками? Нет, спасибо. Вот тут-то и приходит на помощь Identity Brokering.

Keycloak в роли брокера перенаправляет пользователя на страницу логина того realm-а, где хранятся его учётные данные, получает обратно токен и на его основе создаёт (или находит) локального пользователя в своём realm-е.

Подготовка окружения

Для демонстрации нам потребуется один инстанс Keycloak.
Мы создадим два realm-а:

• idp-realm - realm, выступающий в роли Identity Provider. Здесь живут пользователи.
• sp-realm - realm, выступающий в роли Service Provider (потребитель). Сюда будут «приходить» пользователи через брокеринг.

Запускаем Keycloak через Docker Compose. Создаём файл docker-compose.yml:

services:
  keycloak:
    image: quay.io/keycloak/keycloak:25.0.0
    command: start-dev
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports:
      - "8080:8080"

Поднимаем:

docker compose up -d

Теперь можно заходить в админку http://localhost:8080 и авторизоваться.

Настройка realm-провайдера (IDP realm)

Начнём с realm-а, который будет отдавать пользователей. Создаём новый realm с именем idp-realm. В админке нажимаем на выпадающий список realm-ов в левом верхнем углу -> Create realm. Указываем имя idp-realm и жмём Create.

Теперь, чтобы sp-realm мог аутентифицировать пользователей через idp-realm, в idp-realm необходимо создать клиент (Client), который будет представлять собой наш sp-realm.
Переходим в Clients -> Create client и заполняем:

Client ID:            sp-realm-broker
Client type:          OpenID Connect
Valid redirect URIs:  http://localhost:8080/realms/sp-realm/broker/idp-realm-oidc/endpoint/*

В поле Valid redirect URIs мы указываем callback-URL того realm-а, который будет потребителем. Формат URL-а: {keycloak-base}/realms/{consumer-realm}/broker/{identity-provider-alias}/endpoint/*. Алиас idp-realm-oidc - это имя, которое мы дадим Identity Provider-у в sp-realm на следующем этапе.

В настройках клиента включаем Client authentication (т.е. клиент будет конфиденциальным), после сохранения переходим на вкладку Credentials и копируем Client secret - он нам скоро понадобится.

Для проверки работы брокеринга создаём пользователя:
Переходим в Users -> Add user:

Username:   testuser
Email:      testuser@example.com
First Name: Test
Last Name:  User

После создания открываем вкладку Credentials -> Set password, задаём пароль и снимаем галку Temporary.

Настройка realm-потребителя (SP realm)

Теперь настроим realm, который будет принимать пользователей из idp-realm.
Аналогично создаём realm с именем sp-realm.

Вот тут начинается самое интересное. Переходим в sp-realm -> Identity providers -> Keycloak OpenID Connect.

На наше счастье, Keycloak умеет автоматически подтягивать конфигурацию через Discovery URL. Заполняем поля:

Alias:           idp-realm-oidc
Discovery URL:   http://localhost:8080/realms/idp-realm/.well-known/openid-configuration
Client ID:       sp-realm-broker
Client Secret:   <сИкрет, скопированный на предыдущем этапе>

После указания Discovery URL и нажатия кнопки обновления Keycloak автоматически заполнит все endpoint-ы и можно радоваться жизни.

Дополнительные настройки, на которые стоит обратить внимание:

• Store tokens - если включить, Keycloak будет хранить токены, полученные от IDP. Полезно, если вам нужно обращаться к API от имени пользователя.
• Trust emails - если в IDP realm-е email пользователя уже подтверждён, можно включить эту опцию, чтобы не требовать повторного подтверждения.
• Sync mode - определяет, как обновлять данные пользователя при повторном логине. Import - только при первом входе, Force - каждый раз.

Чтобы проверить работу брокеринга, создадим простой клиент в sp-realm:

Client ID:           test-app
Client type:         OpenID Connect
Valid redirect URIs:  http://localhost:8080/realms/sp-realm/account/*

Можно также воспользоваться встроенным Account Console, который доступен по адресу http://localhost:8080/realms/sp-realm/account.

Проверяем работу

Открываем в браузере:

http://localhost:8080/realms/sp-realm/account

На странице логина sp-realm появится кнопка IDP realm Login (или то имя, которое вы указали в Display name). Нажимаем на неё - нас перенаправит на страницу логина idp-realm. Вводим креды нашего testuser, и после успешной аутентификации нас вернёт обратно в sp-realm.

При первом входе Keycloak предложит пользователю подтвердить свой профиль (если включена соответствующая опция) и создаст локальную запись в sp-realm.

Маппинг атрибутов и ролей

По умолчанию Keycloak прокидывает базовые атрибуты - username, email, first name, last name. Но что, если нам нужно прокинуть кастомные атрибуты или роли?

Маппинг атрибутов

Переходим в sp-realm -> Identity providers -> idp-realm-oidc -> вкладка Mappers -> Add mapper.

Допустим, в idp-realm у пользователя есть атрибут department. Создаём маппер:

Name:                    Department Mapper
Sync mode override:      Inherit
Mapper type:             Attribute Importer
Claim:                   department
User Attribute Name:     department

Теперь при каждом логине значение клейма department из токена IDP будет записываться в атрибут пользователя в sp-realm. Правда есть нюанс - чтобы кастомный атрибут попадал в токен IDP realm-а, нужно создать Client scope в idp-realm с соответствующим маппером типа User Attribute, и назначить этот scope клиенту sp-realm-broker.

Маппинг ролей

Для ролей создаём маппер типа Claim to Role:

Name:             Role Mapper - Manager
Sync mode:        Inherit
Mapper type:      Claim to Role
Claim:            realm_access.roles
Claim Value:      manager
Role:             manager  (предварительно создайте эту роль в sp-realm)

Теперь пользователи с ролью manager в idp-realm автоматически получат роль manager в sp-realm.

Первый логин и стратегии обнаружения пользователей

Когда пользователь впервые приходит через брокеринг, Keycloak должен решить: создать нового пользователя или привязать к существующему? За это отвечает настройка First login flow в конфигурации Identity Provider-а.

По умолчанию используется flow first broker login, который включает в себя:

1. Review Profile - пользователю предлагают проверить свои данные.
2. Create User If Unique - если пользователя с таким email/username нет, он создаётся автоматически.
3. Confirm Link Existing Account - если пользователь уже существует, предлагается привязка аккаунтов.

Для корпоративного использования часто имеет смысл кастомизировать этот flow. Например, если вы уверены, что email уникален и доверяете IDP, можно убрать шаг Review Profile и автоматически линковать аккаунты без подтверждения.

Для этого:

1. Переходим в Authentication -> дублируем flow first broker login.
2. В нашей копии удаляем или отключаем Review Profile.
3. Настраиваем Automatically set existing user вместо ручного подтверждения.
4. Справа сверху в выпадающем списке назначаем наш кастомный flow через Bind flow в настройках Identity Provider-а в поле First broker login flow.

На этом всё. Мы рассмотрели полный цикл настройки realm-to-realm Identity Brokering-а в Keycloak: от создания realm-ов и клиентов до маппинга атрибутов и кастомизации первого логина. Механизм мощный и гибкий - позволяет строить федеративную аутентификацию без дублирования пользовательских баз и без сторонних решений.

Если тема Keycloak вам интересна, рекомендую заглянуть в официальную документацию по Server Administration Guide - там описаны продвинутые сценарии, включая брокеринг через SAML и Social Login провайдеры.