Clients

Сможет ли приложение хранить секрет и использовать его для аутентификации на Keycloak.

ON — Конфиденциальный клиент Приложение обязано хранить секрет. При обмене авторизационного кода на токены клиент предъявляет код и Client Secret. Используется для бэкенда. Пример: FastAPI приложение на сервере, обращающееся к Keycloak из защищенной среды.

OFF — Публичный клиент У клиента нет секрета, при обмене кода на токены секрет не используется. Используется для одностраничных приложений, мобильных приложений.

Активация 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:

    Root URL — это база/префикс.

    Home URL — конкретная страница, которая считается "домашней" для приложения.

Если не указан, используется Root URL.

Адреса, на которые Keycloak разрешит отправлять авторизационный код или токены после успешной аутентификации. 

https://myapp.example.com/callback
https://myapp.example.com/oauth/callback
http://localhost:3000/callback  # для разработки
/*                             # любой путь в рамках корневого URL

Для безопасности критично. Как минимум указывать относительный. Просто * убивает всю авторизацию.

Отличие от Valid Redirect URIs:

    Обычные редиректы — после входа (авторизации)

    Post Logout — после выхода

Зачем нужно:
Чтобы пользователь после выхода не попал на поддельную страницу, например: вышли из банка → а вас кинули на https://fake-bank.com/again-login.

Совет: Обычно указывают страницу вроде /goodbye, /logged-out или сам Root URL.

Какие домены имеют право выполнять 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 как список разрешенных источников

*    Любой источник (все домены) 

Внутренний клиент для федерации идентичности (SSO между провайдерами). Пример: Keycloak как Identity Broker между Google, GitHub и другим Keycloak сервером.

добавляет email и email_verified в ID и Access токены

обеспечивает совместимость с Eclipse MicroProfile JWT - популярным стандартом для Java microservices

разрешает выдачу offline refresh token (живёт долго и используется без пользовательского взаимодействия).

включает список ролей (roles) пользователя в SAML assertions

добавляет роли пользователя (realm roles и client roles) в access token (в realm_access.roles и resource_access)

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 появляется поле: 

{
  "allowed-web-origins": ["http://localhost:3000", "https://myapp.com"],
  ...
}

Теперь бэкенд:

• Декодирует токен.
• Видит значение allowed-web-origins.
• В middleware CORS сверяет Origin заголовок входящего запроса со списком.
• Если совпадает — отдает данные. Нет — блокирует.

Используется редко. 

• Настроить Web Origins в клиенте, а бэкенд будет брать CORS-политику из  конфига вне Keycloak.
• Использовать маппер, только если ваш бэкенд динамически решает, кому доверять, на основе данных из токена.

{
  "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 попадут все client_idклиенты, "разрешенных"на клиентов в поле audience токена. Разрешенный клиент означает клиента, для которогокоторые у пользователя есть хотядоступ бычерез одна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.

Механизм LoAуказывающий способ (уровень аутентификации)или сметод) параметромаутентификации пользователя, а не просто факт. Claim acr. 

{
  "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"