Оглавление

  1. Введение и дисклеймер
  2. Обзор Keycloak
  3. Подготовка окружения
  4. Установка и запуск (Docker)
  5. Админ-панель Keycloak: Базовые сущности
  6. Механизмы аутентификации
  7. Теория протоколов: OAuth 2.0 и OpenID Connect
  8. Гранты (Grant Types)
  9. Практика: Интеграция со Spring Boot
  10. Практика: Identity Brokering (GitHub и Auth0)
  11. Межсервисное взаимодействие (M2M)
  12. Заключение

Введение и дисклеймер

Цель — дать базовое понимание Keycloak, концепций безопасности и продемонстрировать практическую работу с инструментом.

Обзор Keycloak

Что такое Keycloak?

Keycloak — это Open Source продукт (сообщество JBoss, под управлением Red Hat) для реализации Single Sign-On (SSO) с возможностью управления доступом.

  • Используется как upstream-проект для Red Hat SSO.
  • Позволяет минимизировать написание кода для аутентификации и авторизации.
  • Выступает центральным компонентом безопасности в инфраструктуре компании (интегрирует внешних провайдеров, LDAP, внутренние приложения).

Основные возможности

  • SSO / Single Sign-Out для браузерных приложений.
  • Поддержка протоколов: OpenID Connect, OAuth 2.0, OAuth 1.0, SAML.
  • Identity Brokering: вход через внешние соцсети (Google, Facebook, GitHub).
  • User Federation: синхронизация с LDAP и Active Directory.
  • Kerberos Bridge: автоматическая аутентификация в доменных сетях.
  • Админская консоль и REST API для управления.

Подготовка окружения

Необходимое ПО

  • Docker и Git (обязательный минимум).
  • JDK 24 и Gradle 8.14+ (рекомендуется для повторения практических шагов).
  • Система сборки: Gradle (версия 8.14 необходима для поддержки Java 24).

Структура проекта (Gradle)

  • build.gradle: описание плагинов (Java) и зависимостей (JUnit, Spring Boot).
  • gradle.properties: хранение версий инструментов.
  • settings.gradle: описание модулей (EventApp, NotificationApp).

Установка и запуск (Docker)

Конфигурация Docker Compose

Keycloak требует базу данных. В примере используется PostgreSQL 15.

Параметры PostgreSQL:

  • Название БД: keyclock
  • Пользователь/Пароль: keyclock / keyclock
  • Внешний порт: 5433 (внутренний 5432).

Параметры Keycloak (образ версии 26.2):

  • Внешний порт: 9090 (внутренний 8080).
  • Переменные окружения: связь с БД, учетные данные админа (admin/admin).
  • Сеть: KeyClock-Net для связи контейнеров.

Режимы запуска: Dev vs Production

Keycloak запускается командой start-dev (режим разработки) или start-pro.

Функция Dev Mode (start-dev) Production Mode (start-pro)
HTTPS Не обязателен (HTTP разрешен) Обязателен (требует TLS/SSL)
Сертификаты Проверка отключена Строгая проверка
Логи Подробные (включая Stack Trace) Ограниченные
Пароли Слабые политики (admin/admin) Строгие политики
База данных Допускает встроенную H2 Только внешняя (PostgreSQL и др.)

База данных (PostgreSQL)

Keycloak использует библиотеку Liquibase для управления миграциями. При первом запуске в схеме public создается 88 таблиц.

  • Таблица Realm: хранит информацию об областях доступа.
  • Системные таблицы: databasechangelog (история миграций).

Админ-панель Keycloak: Базовые сущности

Realms (Реалмы)

Realm — это изолированная область управления пользователями, ролями и клиентами.

  • Пользователи одного реалма не могут войти в другой.
  • Master Realm: Главный административный реалм. Только из него можно создавать другие реалмы и глобальных админов.

Clients (Клиенты)

Clients — приложения или сервисы, которые запрашивают аутентификацию. Стандартные клиенты Keycloak:

  1. account: личный кабинет пользователя.
  2. admin-cli: для работы через консоль или API.
  3. broker: для федерации идентичности.
  4. security-admin-console: сама админ-панель.

Client Scopes (Области доступа)

Механизм, определяющий, какие данные попадут в токен.

  • Default: scope включается всегда.
  • Optional: включается только при явном запросе клиента.

Примеры стандартных scopes:

  • profile: имя, фамилия, дата рождения.
  • email: адрес почты и статус подтверждения.
  • roles: список ролей пользователя.
  • offline_access: позволяет выдавать refresh-токены для длительных сессий.

Roles (Роли)

  • Realm Roles: глобальные роли для всего реалма.
  • Client Roles: роли внутри конкретного приложения.
  • Composite Roles: роли-контейнеры, объединяющие в себе несколько других ролей (например, manage-users включает в себя read, edit, delete).

Users (Пользователи)

Вкладка управления учетными данными. Позволяет:

  • Задавать пароли (постоянные или временные).
  • Настраивать Required Actions (например, “Update Password” при первом входе).
  • Привязывать роли и группы.

Механизмы аутентификации

Authentication Flows

Потоки (шаги), через которые проходит пользователь:

  • Browser Flow: для входа через браузер (логин, 2FA, капча).
  • Direct Grant Flow: для входа по логину/паролю через REST (например, мобильные приложения).
  • Registration Flow: процесс регистрации новых пользователей.

Identity Brokering (Социальные логины)

Позволяет использовать внешние IDP (Google, GitHub, Auth0) для входа в ваше приложение. Keycloak выступает посредником: получает данные от внешней системы и создает/связывает пользователя локально.

User Federation (LDAP, Kerberos)

Интеграция с существующими корпоративными хранилищами.

  • LDAP/Active Directory: Keycloak читает пользователей из внешней базы.
  • Kerberos: обеспечивает беспарольный вход (SSO) в доменных сетях Windows через билеты (KDC).

Теория протоколов: OAuth 2.0 и OpenID Connect

OAuth 1.0 vs 2.0

  • OAuth 1.0: Сложный, требовал криптографической подписи каждого запроса.
  • OAuth 2.0: Упрощенный, опирается на безопасность транспортного уровня (HTTPS). Цель — дать приложению доступ к ресурсам без передачи пароля.

OpenID Connect (OIDC)

Надстройка над OAuth 2.0. OAuth отвечает за авторизацию (права), OIDC добавляет аутентификацию (кто этот пользователь).

  • Добавляет ID Token (формат JWT).

Типы токенов: Access, Refresh, ID

  1. Access Token: Короткоживущий токен для доступа к API.
  2. Refresh Token: Долгоживущий токен для получения нового Access токена без повторного ввода пароля.
  3. ID Token: Содержит информацию о профиле (имя, почту).

Виды Access токенов: Opaque vs JWT

  • Opaque (Oauth 2.0): “Непрозрачная” строка. Ресурсный сервер должен каждый раз обращаться к Keycloak (Introspection), чтобы проверить его.
  • JWT (JSON Web Token): Самодостаточный токен. Содержит заголовок, полезную нагрузку (payload) и подпись. Сервер может проверить его локально с помощью публичного ключа Keycloak.

Гранты (Grant Types)

Authorization Code Flow

Самый безопасный флоу для веб-приложений с Backend-ом.

  1. Приложение редиректит пользователя на Keycloak.
  2. Keycloak возвращает Code (код авторизации).
  3. Backend обменивает Code на токены, используя Client Secret.

PKCE (Proof Key for Code Exchange)

Модификация Authorization Code для мобильных и SPA-приложений, которые не могут безопасно хранить Client Secret.

  • Использует динамически генерируемые Code Verifier и Code Challenge.

Client Credentials (M2M)

Взаимодействие “машина-машина” (один сервис идет в другой). Пользователь в этой схеме отсутствует. Аутентификация происходит по Client ID и Client Secret.

Device Code Flow

Для устройств без клавиатуры (Smart TV). Пользователь вводит короткий код на другом устройстве (телефоне/ПК).

Refresh Token Flow

Обмен Refresh токена на новый Access токен.

Устаревшие гранты (Implicit, Password)

  • Implicit Flow: Токен передавался сразу в URL (небезопасно).
  • Resource Owner Password Credentials: Приложение напрямую запрашивает логин/пароль (крайне не рекомендуется).

Практика: Интеграция со Spring Boot

Настройка SecurityConfig

В Spring Security 6+ конфигурация реализуется через SecurityFilterChain.

  • Actuator Endpoints: часто делаются открытыми (permitAll()) или защищаются ролью ADMIN.
  • Business Endpoints: требуют аутентификации (authenticated()).
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(auth -> auth
        .requestMatchers("/actuator/**").permitAll()
        .requestMatchers("/api/v1/events/**").authenticated()
    )
    .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
    return http.build();
}

Маппинг ролей из JWT

По умолчанию Spring не видит роли Keycloak. Нужно создать конвертер, который достает роли из поля roles (или realm_access) в JWT и добавляет к ним префикс ROLE_.

Практика: Identity Brokering (GitHub и Auth0)

Интеграция с GitHub

  1. Регистрация OAuth App в настройках GitHub Developer Settings.
  2. Настройка Homepage URL и Authorization callback URL (берется из Keycloak).
  3. Копирование Client ID и Client Secret в Keycloak Identity Provider.

Интеграция с Auth0

  1. Создание приложения в панели Auth0.
  2. Использование Discovery Endpoint в Keycloak для автоматической подгрузки URL (авторизация, токены, ключи).

Использование мапперов ролей

Чтобы пользователи из GitHub/Auth0 могли пользоваться вашим приложением, им нужно автоматически назначать роли.

  • Используется Hardcoded Role Mapper: при входе через конкретного провайдера пользователю принудительно выдается роль (например, event_app_user).

Межсервисное взаимодействие (M2M)

Сценарий: EventApp вызывает NotificationApp.

  1. NotificationApp защищен и требует роль internal_access.
  2. EventApp должен получить технический токен в Keycloak (грант Client Credentials).
  3. В Keycloak для клиента event_app включается опция Service Accounts Roles.
  4. Клиенту event_app назначается роль internal_access от клиента notification_app.

Заключение

Keycloak — это мощный инструмент, который:

  • Решает вопросы безопасности “из коробки”.
  • Легко интегрируется с современными фреймворками (Spring Boot).
  • Позволяет гибко управлять доступом как для людей, так и для сервисов.