Федерация в Keycloak с AD: как это устроено внутри

Прошлый пост был про то, что попадает в токен. Этот — про то, откуда данные берутся до этого, и что происходит в момент логина. Потому что федерация — не «настроил и забыл», а конвейер из пяти стадий, и ломается он всегда на одной из них.

Две модели, которые постоянно путают

Прежде чем разбирать поток нужно развести два разных механизма:

- User Federation — AD выступает источником пользователей. Идентичность создаётся там, Keycloak её подтягивает: аутентификация идёт по паролю источника, атрибуты читаются оттуда.
- Identity Brokering — AD выступает внешним провайдером входа. Keycloak не видит пароль вообще, получает assertion/токен и на его основе заводит или связывает локального пользователя.

Разница принципиальная: в первом случае Keycloak знает секрет (или проверяет его через bind), во втором — доверяет подписи и заявлению. Все дальнейшие вопросы «почему нет атрибута» и «почему не обновилось» решаются в разных местах в зависимости от того, какой из двух механизмов у нас применяется.

Что происходит в момент логина (User Federation)

Пошагово:

1. Пользователь вводит логин. Keycloak ищет его в кэше провайдера.
2. Промах кэша → lookup в AD по настроенному атрибуту (username, sAMAccountName, UPN, mail — что выбрано при создании провайдера).
3. Найден → проверка пароля: bind сервисной учёткой, затем bind от имени пользователя. Пароль в Keycloak не сохраняется, он уходит в источник.
4. Успех → атрибуты прогоняются через mappers и складываются в локальную модель пользователя (в зависимости от Edit Mode).
5. Только теперь в игру вступают client scopes и protocol mappers из второго моего поста про Keycloak: они берут уже готовую модель и формируют токен.

Стадии 1–4 — это федерация, стадия 5 — выдача. Пустой claim почти всегда означает, что сломалась одна из первых четырёх, а не пятая.

Три режима, определяющие актуальность данных

- Imported — данные копируются в БД Keycloak при первом входе и живут там. Быстро, но между синхронизациями — устаревшие.
- Always read from source — атрибуты читаются при каждом обращении. Всегда свежие, но есть задержка при опросе самой AD, зависимость от доступности AD в момент логина — жёсткая.
- Write-back — изменения из Keycloak уезжают в AD. Требует прав на запись и аккуратности.

Выбор режима — это не техническая мелочь, а решение о том, где истина. Если отдел меняют в AD, а Keycloak держит копию — кто-то обязательно увидит старую должность в токене и придёт с вопросом.

Синхронизация: что и когда подтягивается

- Полная — обходит всех пользователей источника. Долго, нагружает каталог, нужна для первичного наполнения и после больших изменений.
- Инкрементальная — по метке изменения в источнике. Быстрее, но членство в группах и некоторые атрибуты подхватываются не так охотно, как хотелось бы.
- On-demand — при первом входе конкретного пользователя.
- Событийная — источник сам сообщает об изменениях. Самое свежее и самое хрупкое: ломается тихо.

Синхронизация обновляет модель пользователя. Она НЕ отзывает выданные токены. Старый access token живёт до истечения, refresh — до своего срока.

Маппинг: где чаще всего рассыпается цепочка

Данные идут в два прыжка:

1. Mapper федерации: атрибут AD → атрибут модели Keycloak
2. Protocol mapper в client scope: атрибут модели Keycloak → claim в токене
…

Полный текст поста — на сайте:
https://esin48.ru/blog/post.php?post=2026-10-25-keycloak-federation-ad
#полезное #безопасность #Keycloak