Client scope в Keycloak: что внутри, зачем нужен и как это работает поверх Active Directory

После прошлого поста про IdP у многих остались вопросы почему же один сервис одного юзера пускает, а другой не пускает и выдает ошибку. Так что ловите обещанное продолжение. Расскажу про одну из самых важных штук на примере Keycloak, так как сам работаю с ним. Начинаем начинать)

Scope чаще всего воспринимают как «галочку в настройках клиента». На деле это главный инструмент управления тем, что вообще попадает в токен. А когда под Keycloak стоит AD — почти все инциденты рождаются на стыке двух миров: федерации и scope. Разберём по порядку.

Что лежит внутри scope

Client scope — контейнер, который цепляется к клиенту и содержит:

- Protocol mappers — то, что реально формирует claims: audience, группы, роли, атрибуты пользователя
- Role scope mappings — какие роли (realm/client) попадут в токен при этом scope
- Тип: Default (применяется всегда) или Optional (только если клиент запросил через scope=)

Плюс встроенные: profile, email, roles, web-origins, address, phone, offlineaccess, acr, microprofile-jwt.

Важно: scope живёт на уровне realm и переиспользуется между клиентами. Это общий контракт, а не приватная настройка одного клиента.

Зачем он нужен

- Ограничить привелегии. Бухгалтерии нужен email, а не членство в 40 группах и не LDAP-пути.
- Переиспользование. Один scope «api-audience» на двадцать клиентов вместо двадцати одинаковых мапперов.
- Размер токена. Тяжёлые claims выносим в Optional — платим только там, где нужно.
- Явный контракт. Default = «клиент получает всегда», Optional = «можно запросить».

Главное, что нужно понять про AD

Scope НЕ знает про Active Directory. Он работает уже с загруженной моделью пользователя в Keycloak.

Данные проходят четыре звена:

1. AD → атрибут (sAMAccountName, mail, department, memberOf)
2. User Federation → LDAP mapper → попадает в модель пользователя Keycloak
3. Protocol mapper ВНУТРИ client scope → кладёт значение в токен как claim
4. Resource server читает claim

Отсюда правило, которое снимает половину вопросов: если атрибута нет в модели пользователя, можно поставить хоть десять protocol mappers — claim будет пустой. И наоборот: если атрибут в модели есть, но protocol mapper не привязан к нужному scope — в токене его не будет.

LDAP mapper — это «втянуть из AD в Keycloak». Protocol mapper в scope — это «отдать наружу в токене». Постоянно путают.

LDAP mappers, которые обычно настраивают

- Username / RDN mapper — username = sAMAccountName или userPrincipalName (выбор фиксируется при создании провайдера, потом не меняется)
- First name / Last name / Full name
- Email
- user-attribute-ldap-mapper — любой атрибут: department, title, employeeID, manager
- group-ldap-mapper — AD-группы → группы Keycloak
- role-ldap-mapper — AD-группы → роли Keycloak
- msad-user-account-control-mapper — учитывает userAccountControl (отключённые/заблокированные аккаунты)
- hardcoded-attribute-ldap-mapper — константа, если нужно

Имя атрибута в LDAP mapper и User Attribute в protocol mapper должны совпадать посимвольно. Разница в регистре — самая обидная причина пустого claim.

Edit Mode — рычаг против устаревших данных

- READONLY — атрибут импортируется и живёт в БД Keycloak. Изменилось в AD → в Keycloak старое, пока не прошла синхронизация …

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