Понимание Realms, Clients и Roles в Keycloak

Коротко

Реалмы — изолированные области идентичности (удобно для мультиарендности и разделения окружений).
Клиенты — приложения/сервисы по OIDC/SAML. Выберите тип доступа: public, confidential или bearer-only.
Роли — разрешения. Realm roles — для уровней доступа между приложениями; client roles — для гранулярности внутри конкретного приложения. Объединяйте роли в composite.

Введение

Keycloak — мощная open-source-платформа IAM. Ментальная модель проста: реалмы изолируют идентичности, клиенты подключают ваши приложения, а роли управляют разрешениями. Освоив эти три сущности, вы опишете почти любой сценарий аутентификации и авторизации.

Ниже — практический разбор с «скриншот-мысленно», ясными определениями и минимальным примером корпоративного портала, который можно повторить за считанные минуты.

Реалмы: изолированные пространства аутентификации

Реалм — это автономная граница со своими пользователями, группами, клиентами и ролями. Создавайте отдельные реалмы для арендаторов или окружений (dev/test/prod), а не перегружайте один общий.

Здравые дефолты

Делите по окружениям (Company-Dev, Company-Staging, Company-Prod).
Разные админ-аккаунты для разных реалмов; избегайте кросс-связей.
Задокументируйте политики реалма (пароли, TTL JWT, темы и т. п.).

Клиенты: приложения и сервисы

Клиент — любое приложение или сервис, делегирующее аутентификацию Keycloak. В современных стэках используйте OpenID Connect; SAML — для легаси-интеграций.

Параметры, которые действительно важны:

Client ID

Уникален в рамках реалма; используется приложением для запуска OIDC-потоков.

Протокол

Предпочитайте OpenID Connect, если партнёр не требует SAML 2.0.

Тип доступа

public (SPA/нативные), confidential (серверные с client secret), bearer-only (API лишь валидируют токены).

Valid Redirect URIs

Разрешайте точные origin/пути, чтобы исключить open redirect; избегайте вайлдкардов в проде.

Полезно: держите Web Origins максимально строгими. В локальной разработке явно указывайте http://localhost:3000 вместо *.

Роли: управление доступом (RBAC)

Роли моделируют разрешения. Назначайте их пользователям или группам, читайте их из токенов в ваших приложениях.

Две разновидности, которые вы будете использовать ежедневно:

Realm roles

Глобальны в рамках реалма; идеально для уровней доступа «через все приложения»:admin, editor, viewer.

Client roles

Привязаны к конкретному клиенту; подходят для прав внутри приложения, напр. billing:read.

Composite roles

Композитная роль включает другие роли. Назначили одну — получили сразу набор. Удобно для «Админ», что подразумевает editor + billing:write + user:manage.

Пример: корпоративный портал за 5 шагов

Минимальная конфигурация, которую можно запустить локально. Подстройте имена/URI под ваш стек.

Шаг 1: запуск Keycloak

Для локальной разработки используйте Docker:

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:25.0.2 start-dev

Логин: http://localhost:8080 с указанными выше админ-данными.

Шаг 2: создайте реалм

Создайте CompanyPortal, чтобы изолировать идентичности портала.

Левое верхнее меню → Create realm
Name: CompanyPortal
Сохранить

Шаг 3: зарегистрируйте клиентов

Добавьте WebApp и MobileApp:

Sidebar → Clients → Create client
Client ID: WebApp · Protocol: openid-connect
Valid Redirect URIs: http://localhost:3000/* (под ваш фронтенд)
Повторите для MobileApp с корректными URI

Шаг 4: создайте роли

Добавьте Admin и User как роли реалма.

Sidebar → Realm roles → Create role
Name: Admin → Save; затем User

Шаг 5: назначьте роли

Назначьте роли пользователям (или группам):

Sidebar → Users → выберите пользователя
Role mapping → Assign role → выберите роли → Assign

Теперь у вас есть изоляция (реалм), подключённые приложения (клиенты) и авторизация (роли). Публикуйте портал, читайте роли из токенов и соблюдайте правила в коде.

Частые ошибки и как их избежать

Вайлдкарды в Redirect URI. Удобно в dev, опасно в prod. Перечисляйте точные origin/пути.
Смешивание арендаторов в одном реалме. Делайте реалм на тенанта или, как минимум, на окружение — это сокращает зону поражения.
Назначение ролей только пользователям. Отдавайте предпочтение назначению ролей группам: масштабируется и удобнее в аудите.
Утечки секретов в public-клиентах. SPA/нативные — всегда public; client secret там хранить нельзя.

FAQ

Realm roles vs client roles — когда что использовать?

Realm roles — для сквозных уровней доступа в организации; client roles — для разрешений внутри конкретного приложения. При необходимости комбинируйте.

Можно ли шарить пользователей между реалмами?

Напрямую — нет. Реалмы изолированы. Используйте identity brokering или federated identity, если нужно пересекать границы реалмов.

Как читать роли в моём приложении?

Читайте ID/Access токены. В OIDC роли находятся в realm_access.roles и resource_access[client].roles.

Итоги и что дальше

Реалмы изолируют, клиенты интегрируют, роли авторизуют. Начните с чётких границ и строгих redirect-правил; по мере роста системы переходите на назначение ролей через группы и используйте composite-роли.

Продолжите с моим гайд-постом по интеграции Keycloak + Next.js (App Router) или посмотрите кластеризацию Keycloak с Nginx.

Нужен sanity-чек вашей модели авторизации? Провожу аудиты и помогаю командам настроить безопасные и ненавязчивые логины.