| Роли | Группы | |
| Назначение | права доступа | организация пользователей |
| Уровень | низкий (atomic) | высокий (aggregation) |
| Используются в коде | Да | Косвенно |
| Наследование | Нет | Да |
| Иерархия | Нет | Да |
| Название | Описание | Тип приложения |
| Authorization Code | Стандартный безопасный flow для веб-приложений, где сервер клиента может хранить секреты. Клиент формирует POST-запрос к token-эндпоинту авторизационного сервера с обязательными параметрами: - grant\_type -> Authorization Code - authorization\_code -> code, полученный на шаге 6 - redirect\_uri -> тот же URI, что использовался при авторизации - client\_id -> Идентификатор клиента - client\_secret -> Секрет клиента безопасно для серверов с хранением Client Secret. Уязвимость на этапе редиректа. Подходит для серверных приложений | Веб-приложения (backend + frontend). |
| Authorization Code + PKCE | Модификация Authorization Code Flow для публичных клиентов (например, мобильных и SPA), чтобы предотвратить атаку перехвата кода. Клиент перед началом авторизации: - Генерирует случайный код (code\_verifier) - Строит на его основе code\_challenge (обычно SHA-256) - При первом запросе отправляется code\_challenge - При обмене Authorization Code на Access Token отправляется code\_verifier. - Authorization Server сверяет code\_challenge и code\_verifier: Если всё сходится, только тогда выдает Access Token. Это защищает от атаки перехвата кода, потому что даже если злоумышленник украдет Authorization Code, без правильного code\_verifier он не сможет обменять его на Access Token. безопасно для мобильных и браузерных клиентов без секретов. Нужен только Code Verifier Защита на этапе редиректа Подходит для мобильных и SPA | Мобильные приложения, SPA (Single Page Applications). |
| Client Credentials | Классический machine-to-machine сценарий, когда приложение запрашивает токен от собственного имени, без пользователя. | Сервисные взаимодействия (backend to backend), микросервисы. |
| Device Code | Для устройств без полноценной клавиатуры (например, Smart TV). Пользователь вводит код на другом устройстве. | Устройства с ограниченным вводом - SmartTV, консоли, IoT. |
| Refresh Token | После получения Access Token можно получить новый токен без повторной аутентификации пользователя. | Любые клиенты с долгоживущими сессиями. |
| Название | Описание |
| browser | Встроенный поток для авторизации на основе браузера. Включает формы логина, OTP (двухфакторную аутентификацию), CAPTCHA и другие шаги. |
| clients | Встроенный поток аутентификации для клиентов (используется в client credentials grant). Работает без участия пользователя. |
| direct grant | Встроенный поток для ресурсного владельца (Resource Owner Password Credentials Grant). Используется, когда пользователь напрямую вводит логин и пароль (например, через curl или мобильное приложение). |
| docker auth | Поток аутентификации Docker-клиентов при доступе к приватному Docker Registry через Keycloak. |
| First broker login | Поток, срабатывающий при первом входе пользователя через внешний Identity Provider (например, Google, GitHub). Позволяет привязать внешний аккаунт к локальному пользователю Keycloak. |
| Registration | Поток регистрации новых пользователей. Включает форму ввода данных, подтверждение по email и проверки по политике безопасности (например, сила пароля). |
| Reset credentials | Поток для восстановления доступа, если пользователь забыл пароль. Может включать подтверждение по email, OTP и другие шаги для подтверждения личности. |
| Параметр | Описание |
| Client type | Алгоритм аутентификации клиента. OpenID или SAML. |
| Client ID | Идентификатор клиента. Он будет использоваться в запросах, поэтому желательно с маленькой буквы, без пробелов и прочего. |
| Client authentication | Сможет ли приложение хранить секрет и использовать его для аутентификации на Keycloak. **ON — Конфиденциальный клиент** Приложение обязано хранить секрет. При обмене авторизационного кода на токены клиент предъявляет код и Client Secret. Используется для бэкенда. Пример: FastAPI приложение на сервере, обращающееся к Keycloak из защищенной среды. **OFF — Публичный клиент** У клиента нет секрета, при обмене кода на токены секрет не используется. Используется для одностраничных приложений, мобильных приложений. |
| Authorization | Активация RBAC, доступ к конкретным строчкам в БД. **OFF (выключено — поведение по умолчанию)** Пользователю даются роли (например, user, admin), и клиент сам решает на своей стороне, что с этими ролями делать. Решение принимает бэкенд клиента. **ON (включено — тонкая (fine-grained) авторизация)** Как работает: Вы описываете ресурсы (например: Аккаунт №123, Документ "Отчет.xlsx"), области действий (read, write, delete) и политики (кто, при каких условиях может что делать). Keycloak сам принимает решение: разрешено или запрещено. Кто принимает решение: Keycloak (сервер авторизации). Ваше приложение: Спрашивает у Keycloak: «Может ли пользователь Вася выполнить read над ресурсом Аккаунт №123?» Keycloak отвечает: Permit или Deny. После включения, в меню клиента появляются новые вкладки: Resources — что вы защищаете (например, Документы, Счета, Данные профиля). Authorization Scopes — действия (например, view, edit, delete, download). Policies — кто и при каких условиях может что-то делать (например, Только владелец ресурса, Только пользователи из отдела продаж, Только между 9:00 и 18:00). Permissions — связывание всего вместе: «Разрешить edit для ресурса Документ, если выполнена политика Владелец документа». Включение Authorization усложняет архитектуру. Keycloak становится точкой принятия решений (PEP — Policy Enforcement Point на клиенте, PDP — Policy Decision Point на Keycloak). Это требует: - Дополнительных запросов от вашего приложения к Keycloak (проверка каждого доступа). - Глубокого понимания политик. - Аккуратного проектирования ресурсов. |
| Root URL | Базовый адрес вашего приложения. Используется как префикс для других URL, если они указаны относительно. Может быть пустым, но лучше указать. Некоторые функции Keycloak (например, ссылка "Back to application" на странице логина) используют этот URL. |
| Home URL | Куда пользователь попадет после нажатия на логотип Keycloak или ссылку "Back to application". Отличие от Root URL: Root URL — это база/префикс. Home URL — конкретная страница, которая считается "домашней" для приложения. Если не указан, используется Root URL. |
| Valid Redirect URIs | Адреса, на которые Keycloak разрешит отправлять авторизационный код или токены после успешной аутентификации. ``` https://myapp.example.com/callback https://myapp.example.com/oauth/callback http://localhost:3000/callback # для разработки /* # любой путь в рамках корневого URL ``` Для безопасности критично. Как минимум указывать относительный. Просто \* убивает всю авторизацию. |
| Valid Post Logout Redirect URIs | Адреса, на которые Keycloak перенаправит пользователя после успешного выхода (logout). Отличие от Valid Redirect URIs: Обычные редиректы — после входа (авторизации) Post Logout — после выхода Зачем нужно: Чтобы пользователь после выхода не попал на поддельную страницу, например: вышли из банка → а вас кинули на https://fake-bank.com/again-login. Совет: Обычно указывают страницу вроде /goodbye, /logged-out или сам Root URL. |
| Web Origins | Какие домены имеют право выполнять CORS-запросы к вашему Keycloak из браузера (для SPA-приложений). Используется для: CORS (Cross-Origin Resource Sharing) на эндпоинтах Keycloak (/token, /logout, /userinfo и т.д.). Пример для SPA на React: Ваше SPA работает на https://myapp.com, а Keycloak на https://keycloak.example.com. Если Web Origins указан правильно, браузер позволит SPA из myapp.com делать fetch-запросы к Keycloak. \+ Плюс означает использовать Valid Redirect URIs как список разрешенных источников \* Любой источник (все домены) |
| Название | Описание | Адрес |
| account | Клиент пользовательского личного кабинета. Управление профилем, просмотр сеансов входа и разрешения. | /realms/{realm}/account |
| account-console | Фронтенд клиента account, вызывающий API account. | |
| admin-cli | Клиент взаимодействия с Keycloak через CLI или REST API. Например получение токена через kcadm.sh или curl для скриптов/CI/CD. Поддерживает client\_credentials и password гранты. | |
| broker | Внутренний клиент для федерации идентичности (SSO между провайдерами). Пример: Keycloak как Identity Broker между Google, GitHub и другим Keycloak сервером. | |
| master-realm | Формальный клиент, представляющий сам master realm. Часто используется для определённых внутренних механизмов и ссылок в Admin Console. | |
| security-admin-console | Клиент для административной консоли Keycloak. Используется при входе в админ-панель, управлении реалмами, пользователями и клиентами. | /admin/{realm}/console |
| Название | Тип | Протокол | Назначение |
| acr | Default | OpenID Connect | добавляет в токен acr (Authentication Context Class Reference) - уровень аутентификации (например, MFA, пароль и т. д.). |
| address | Optional | OpenID Connect | добавляет адрес пользователя (address claim) в токен (если заполнено в профиле). |
| basic | Default | OpenID Connect | включает базовые claims - sub, name, preferred\_username, given\_name, family\_name |
| Default | OpenID Connect | добавляет email и email\_verified в ID и Access токены | |
| microprofile-jwt | Optional | OpenID Connect | обеспечивает совместимость с Eclipse MicroProfile JWT - популярным стандартом для Java microservices |
| offline\_access | Optional | OpenID Connect | разрешает выдачу offline refresh token (живёт долго и используется без пользовательского взаимодействия). |
| role\_list | Default | SAML | включает список ролей (roles) пользователя в SAML assertions |
| roles | Default | OpenID Connect | добавляет роли пользователя (realm roles и client roles) в access token (в realm\_access.roles и resource\_access) |
| Имя | Описание | |||||||||||||||||||||
| Allowed Web Origins | Scope с данным mapper добавляет все разрешенные веб-источники к свойству "allowed-origins" в токене. Иначе это механизм копирования списка доверенных источников браузера из конфигурации Keycloak Client внутрь Access Token, чтобы бэкенд мог программно принять решение о разрешении CORS. При генерации токена он читает список разрешенных веб-источников, настроенный у Client (родителя этого Client Scope), и копирует этот список в указанный claim токена. Поля конфигурации маппера: - Name: Allowed Web Origins (любое имя) - Mapper Type: Allowed Web Origins - Claim name: Обычно allowed-web-origins (но можно кастомизировать) - Claim JSON Type: String или String Array - Add to ID token: Вкл/Выкл (обычно выкл, чтобы не раздувать ID токен) - Add to access token: Вкл (обычно да) **Пример**: SPA (на http://localhost:3000) стучится на бэкенд (http://localhost:8080). Бэкенд получает токен, но как ему узнать, что JavaScript вашего фронта имеет право вызывать его API? Решение через маппер Allowed Web Origins: - Вы идете в Client Scope (например, microservice-scope). - Добавляете маппер типа Allowed Web Origins. - Протоколируете этот scope к вашему клиенту (SPA). Результат: Внутри Access Token появляется поле: ```json { "allowed-web-origins": ["http://localhost:3000", "https://myapp.com"], ... } ``` Теперь бэкенд: - Декодирует токен. - Видит значение allowed-web-origins. - В middleware CORS сверяет Origin заголовок входящего запроса со списком. - Если совпадает — отдает данные. Нет — блокирует. Используется редко. - Настроить Web Origins в клиенте, а бэкенд будет брать CORS-политику из конфига вне Keycloak. - Использовать маппер, только если ваш бэкенд динамически решает, кому доверять, на основе данных из токена. | |||||||||||||||||||||
| Audience, Hardcoded claim, Audience Resolve | Решает вопрос "для кого этот токен" (Resource Server). Это поле aud (audience) в JWT токене. Оно указывает, какой ресурс (API/сервис) должен принять этот токен. ```json { "iss": "https://keycloak.local/realms/myrealm", "sub": "user-123", "aud": ["account", "https://api.mycompany.com/v1"], ... } ``` Зачем это нужно? Например, есть 3 микросервиса: - payment-api (оплата) - order-api (заказы) - analytics-api (аналитика) Если токен не имеет audience, любой сервис может принять токен, выданный для другого. Злоумышленник получает токен для payment-api, но пытается вызвать order-api. Без проверки aud — успешно. Решение: Keycloak добавляет в токен aud = "payment-api". order-api проверяет этот claim и отвергает токен (403 Forbidden). **Типы мапперов для Audience** **Audience (простой)** Создаете маппер в Client Scope, указываете жестко имя аудитории. Конфигурация: - Included Client Audience: выбираете клиента (например, payment-api) - Add to ID token: обычно false - Add to access token: true Результат: В access token появится "aud": \["payment-api"\] **Hardcoded claim** Вручную claim aud с любым значением (массивом или строкой). Конфигурация: - Claim name: aud - Claim value: \["service-a", "service-b"\] - Claim JSON Type: String Array **Audience resolve (продвинутый)** Автоматически собирает всех клиентов, которым был выдан токен, и добавляет их в aud. Например, если клиент spa-app запрашивает токен с scope, включающим audience-resolve маппер, в aud попадут все клиенты, на которые у пользователя есть доступ через service accounts. **Реальный сценарий использования** **Сценарий: SPA + два микросервиса** Настройка в Keycloak: - Создаете Client для SPA: my-spa - Создаете Client для каждого API: payment-api, order-api - Создаете Client Scope с именем audience-payment - Добавляете маппер типа Audience: - Included Client Audience: payment-api Процесс: // SPA запрашивает токен с scope = 'audience-payment' const token = await keycloak.getToken({ scope: 'audience-payment' }); // В токене: { "aud": \["payment-api"\], // Только для payment-api "scope": "audience-payment" } // SPA вызывает payment-api ✅ разрешено // SPA вызывает order-api ❌ токен не содержит aud=order-api **Сценарий: Токен для нескольких API** Иногда нужно, чтобы один токен работал с несколькими сервисами: json { "aud": \["payment-api", "order-api", "analytics-api"\] } Как сделать: Создаете маппер Hardcoded claim с массивом значений или используете несколько мапперов Audience. | |||||||||||||||||||||
| Authentication Context Class Reference (ACR) | Механизм указывающий способ (уровень или метод) аутентификации пользователя, а не просто факт. Claim acr. ```json { "iss": "https://keycloak.local/realms/myrealm", "sub": "user-123", "acr": "1", "auth_time": 1699123456, ... } ``` Конфигурация маппера: - Тип маппера: Authentication Context Class Reference (ACR) - Имя: acr-mapper (любое) - Включить в ID token: true (рекомендуется) - Включить в access token: true (если бэкенд проверяет acr) Алгоритм: - Копирует значение acr из аутентификационного контекста в токен - Если в сессии нет явного acr — используется значение по умолчанию Приложение может запросить конкретный acr, и keycloak можно настроить на изменение способа авторизации. В токен попадает итоговый реальный acr. **Реальные сценарии** Сценарий 1: Разные уровни доверия для разных операций - Просмотр баланса → достаточно acr = "1" (пароль) - Перевод до 1000$ → нужно acr = "2" (пароль + SMS) - Перевод от 1000$ → нужно acr = "3" (пароль + OTP + биометрия) Сценарий 2: Соответствие стандартам (eIDAS, NIST) Правительственные системы требуют определенные уровни аутентификации: - NIST AAL1 (Low): пароль - NIST AAL2 (Moderate): пароль + OTP - NIST AAL3 (High): аппаратный токен + биометрия Сценарий 3: Корпоративная безопасность - Доступ к обычным документам → acr = "password" - Доступ к финансовым отчетам → acr = "password+mfa" - Доступ к HR данным → acr = "hardware-key" **Отличие ACR от AMR** AMR (Authentication Methods Reference) — что использовали: пароль, OTP, WebAuthn. ACR (Authentication Context Class) — насколько надежно, агрегированный уровень. | |||||||||||||||||||||
| Authentication Method Reference (AMR) | Claim в JWT токене, который содержит **массив строк**, каждая из которых обозначает конкретный метод аутентификации, использованный пользователем во время входа. RFC 8176 определяет стандартные значения AMR : - pwd Пароль (Password) - mfa Многофакторная аутентификация (Multi-Factor) - otp Одноразовый пароль (One-Time Password) - sms SMS-код - tel Телефонный звонок - geo Геолокация - fpt Отпечаток пальца (Fingerprint) - eye Сканирование сетчатки глаза - face Распознавание лица - hwk Аппаратный ключ (Hardware Key) - pin PIN-код - user Аутентификация пользователем (обычно через интерфейс ОС) - kba Knowledge-based authentication - mca Multi-channel authentication - sc Смарт-карта (Smart Card) Keycloak позволяет использовать любые кастомные значения, не ограничиваясь стандартным списком. **Настройка в консоли администратора** Настройка аутентификаторов: - Перейдите в Authentication → Flows - Выберите ваш flow (например, Browser) - Для каждого execution (например, Username/Password Form) нажмите Actions → Config - В поле Authenticator Reference укажите значение (например, pwd) Добавление маппера AMR: - Создайте новый маппер в Client Scope - Mapper Type: Authentication Method Reference (AMR) - Name: amr-mapper (любое имя) - Add to ID token: ON (рекомендуется) - Add to access token: ON (если бэкенд проверяет AMR) Маппер автоматически соберет все выполненные аутентификаторы и добавит их в поле amr | |||||||||||||||||||||
| Claims parameter Token, Claims parameter with value ID Token | Это НЕ маппер для добавления произвольных данных в токен из запроса. Это маппер для чтения OIDC Claims Parameter из запроса авторизации и добавления их в токен. встроенный в Keycloak маппер, который читает этот самый параметр claims из запроса авторизации и преобразует его в реальные claims в токене ``` https://keycloak.local/auth/realms/myrealm/protocol/openid-connect/auth? client_id=myapp& redirect_uri=https://myapp.com/callback& response_type=code& scope=openid& claims={"userinfo":{"given_name":{"essential":true},"email":null}} ``` Из остальных точек (headers, ...) данный элемент не считывается. Сценарий применения нишевый. Пример: необходимо, чтобы в ID token обязательно были email и phone\_number, но только для этого конкретного запроса, а не для всех. Без маппера: пришлось бы создавать отдельный client scope и настраивать мапперы. С маппером: можно просто отправить правильный claims параметр. В случае Claims parameter with value ID Token, добавляются именно в токен ID. Параметр claims НЕ фильтрует claims, которые приходят из скоупов. Он добавляет дополнительные claims сверх того, что уже включено через scope. | |||||||||||||||||||||
| Group Membership | Берет группы, в которые входит пользователь в Keycloak, и записывает их названия в токен.
```json
{
"groups": ["Engineering", "Managers"]
}
```
**Настройка**
Создание маппера происходит в разделе Client Scopes или непосредственно в настройках Client:
Вариант 1: Через UI консоли администратора
Clients → Client Scopes → выберите нужный scope (или создайте новый)
Вкладка Mappers → Add mapper → By configuration
Выберите Mapper Type → Group Membership
| |||||||||||||||||||||
| Map user group membership | Жестко запрограммированное утверждение | |||||||||||||||||||||
| Hardcoded Role | Жестко запрограммируйте роль в токене доступа. | |||||||||||||||||||||
| Nonce backwards compatible | Добавляет утверждение nonce в токен Access, Refresh и ID | |||||||||||||||||||||
| Organization Membership | Сопоставьте членство пользователя в организации | |||||||||||||||||||||
| Map user Organization membership | Попарный идентификатор субъекта | |||||||||||||||||||||
| Pairwise subject identifier | Вычисляет парный идентификатор субъекта, используя хэш-код sha-256, и добавляет его к заявке "sub". Смотрите спецификацию OpenID Connect для получения дополнительной информации о парных идентификаторах субъектов. | |||||||||||||||||||||
| Role Name Mapper | Сопоставьте назначенную роль с новым именем или позицией в токене. | |||||||||||||||||||||
| Session State | Добавьте запрос о состоянии сеанса (session\_state) | |||||||||||||||||||||
| Subject (sub) | Добавьте запрос о предмете (под) | |||||||||||||||||||||
| User Address | Сопоставляет атрибуты адреса пользователя (улица, населенный пункт, регион, почтовый индекс и страна) с утверждением OpenID Connect "адрес". | |||||||||||||||||||||
| User Attribute | Сопоставляет пользовательский атрибут пользователя с утверждением токена. | |||||||||||||||||||||
| User Client Role | Сопоставьте роль пользователя-клиента с заявкой на токен. Когда Multivalued выключен, возвращаются только назначенные роли; когда включен — все существующие. | |||||||||||||||||||||
| User Property | Сопоставьте встроенное свойство пользователя (адрес электронной почты, имя, фамилию) с заявкой на токен. | |||||||||||||||||||||
| User Realm Role | Сопоставьте роль области пользователя с заявкой на токен. Когда Multivalued выключен, возвращаются только назначенные роли; когда включен — все существующие. | |||||||||||||||||||||
| User Session Note | Сопоставьте пользовательскую заметку о сеансе пользователя с заявкой на токен. | |||||||||||||||||||||
| User's full name | Сопоставляет имя и фамилию пользователя с заявкой OpenID Connect "имя". Формат <first> + ' ' + <last> |
| Модель | Процесс | + / - |
| Backend-driven | JWT → roles → проверка в FastAPI | + простой + быстрый - логика размазана по коду |
| Token-driven | JWT уже содержит всё → backend просто читает | + без внешних запросов - сложнее управлять динамикой |
| Keycloak Authorization Services | Backend → Keycloak → decision | + централизованная политика + ABAC / RBAC / rules - сложность - задержка |
| Название | Композитная | Только в master realm | Назначение |
| admin | Да | Да | Административные права: управление пользователями, клиентами, ролями и конфигурацией реалма |
| create-realm | Нет | Да | Создание новых realms через Admin Console или REST API. |
| default-roles-master | Да | Нет | набор ролей, назначаемых по умолчанию всем новым пользователям master realm. Включает offline\_access, uma\_authorization и другие (можно посмотреть внутри composite). |
| offline-access | Нет | Нет | дает возможность получать offline refresh tokens - живут дольше, не требуют активной сессии пользователя. |
| uma\_authorization | Нет | Нет | позволяет использовать User-Managed Access (UMA) - механизм, при котором пользователь может делегировать доступ к своим ресурсам другим пользователям (используется при ресурсно-ориентированном доступе). |
| Child groups | Дочерние группы. Дерево подчинения. |
| Members | Пользователи в группе. По умолчанию не показывает пользователей из дочерних групп. Для отображения пользователей дочерних групп нужно нажать кнопку Include sub-group users. [](http://bobrobotirk.ru/uploads/images/gallery/2026-04/JrGimage.png) |
| Attributes | Дополнительные атрибуты группы. Атрибуты наследуются и объединяются, но если имя атрибута совпадает — приоритет у самого глубокого (дочернего) элемента в иерархии. Если же у дочерней группы атрибут имеет пустое значение, это НЕ удаляет родительский атрибут (в текущих версиях Keycloak пустое значение просто игнорируется). [](http://bobrobotirk.ru/uploads/images/gallery/2026-04/NcVimage.png) Если пользователь в нескольких дочерних группах, то значения будут объединены в список. Значение атрибута в пользователе затрет все объединения. Работает если в маппере атрибута (Client Scope → Mappers) включена опция "Multivalued" и "Aggregate attribute values". Если эти опции не включены, поведение может отличаться: Без "Multivalued": будет взято только одно значение (какое именно — недетерминировано) Без "Aggregate": групповые атрибуты могут вообще не добавляться в токен |
| Role mapping | Роли, добавляемые данной группой. |
| Admin Events | Административные события. Отображается список для группы, редактирование в разделе Realm settings - Events. |
