Keycloak: что это такое и как работает система управления доступом

Что такое Keycloak и зачем он нужен

Keycloak — это open-source решение для управления доступом (IAM), изначально созданное компанией Red Hat. Оно предназначено для централизованной аутентификации и авторизации в веб-приложениях, мобильных сервисах и микросервисных архитектурах. Вместо того чтобы разрабатывать собственную систему логинов, паролей, ролей и токенов, разработчики могут подключить Keycloak и получить готовый функционал «из коробки».

Основные сценарии использования Keycloak включают:

• Единый вход (SSO) — пользователь проходит аутентификацию один раз и получает доступ ко всем подключенным приложениям без повторного ввода пароля.
• Социальные логины — авторизация через внешние сервисы: Google, VK, GitHub и другие.
• Централизованное управление пользователями — создание, редактирование, удаление учетных записей, управление ролями и правами доступа.
• Поддержка стандартов OAuth 2.0, OpenID Connect и SAML 2.0 — обеспечивает совместимость с большинством современных приложений и сервисов.
• Интеграция с корпоративными каталогами — подключение к LDAP и Active Directory для синхронизации пользователей.

Keycloak подходит как для небольших стартапов, так и для крупных корпоративных сред. Он помогает снизить риски безопасности, связанные с ненадежным хранением учетных данных, и упрощает сопровождение приложений.

Как работает Keycloak: архитектура и основные сущности

Keycloak функционирует как самостоятельный сервис с собственной панелью управления, REST API и клиентами для популярных языков и фреймворков. Его архитектура построена вокруг нескольких ключевых сущностей:

• Реалмы (Realms) — это единицы изоляции. Внутри каждого реалма хранятся свои пользователи, роли и настройки доступа. Объекты из одного реалма не пересекаются с объектами из другого. Это позволяет использовать один экземпляр Keycloak для нескольких независимых проектов.
• Пользователи — учетные записи людей или сервисов. При попытке входа Keycloak сверяет указанные данные с сохраненными и при совпадении выдает токен доступа.
• Роли — сущности, описывающие права доступа. Роли могут быть realm-уровня (действуют внутри всего реалма) или client-уровня (относятся к конкретному приложению). Один пользователь может иметь несколько ролей.
• Клиенты — приложения и сервисы, которые делегируют Keycloak задачи аутентификации и авторизации. Примеры: backend-сервисы, веб- и мобильные приложения.

Когда пользователь пытается войти в приложение, клиент перенаправляет его на сервер Keycloak. После успешной проверки Keycloak выдает токены:

• Access token — для доступа к защищенным ресурсам.
• Refresh token — для получения нового Access token без повторного ввода пароля.
• ID token — содержит информацию о личности пользователя.

Приложения доверяют этим токенам и предоставляют доступ в соответствии с назначенными правами.

Установка Keycloak: пошаговая инструкция

Keycloak можно развернуть различными способами: через Docker-контейнер, из архива, в Kubernetes или на облачном сервере. Рассмотрим самый распространенный и быстрый способ — установка через Docker.

Шаг 1. Создайте сервер (VPS) Выберите образ Ubuntu 22.04 и минимальную конфигурацию CPU/RAM для тестирования. Подключитесь по SSH.

Шаг 2. Установите Docker и Docker Compose Выполните команды:

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

Для ускорения загрузки образов можно настроить зеркало Docker Hub.

Шаг 3. Создайте Docker Compose файл Создайте папку проекта и файл docker-compose.yml:

services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.3.2
    command: start-dev
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin
    ports:
      - "8080:8080"
    restart: always

Шаг 4. Запустите Keycloak Выполните docker compose up -d. Через минуту Keycloak будет доступен по адресу http://<ваш_IP>:8080.

Шаг 5. Отключите требование HTTPS (только для теста) По умолчанию Keycloak требует HTTPS. Для тестового окружения выполните в контейнере:

docker exec -it keycloak-keycloak-1 /opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password admin
docker exec -it keycloak-keycloak-1 /opt/keycloak/bin/kcadm.sh update realms/master -s sslRequired=NONE

После этого можно авторизоваться в административной панели с логином и паролем admin.

Базовая настройка Keycloak: реалмы, пользователи и роли

После запуска Keycloak необходимо выполнить базовую настройку. Всё начинается с создания реалма.

Создание реалма В административной панели перейдите на вкладку «Manage realms» и нажмите «Create realm». Введите имя реалма (например, myapp) и подтвердите создание. Реалм становится изолированным пространством для пользователей и настроек.

Создание ролей Роли определяют, какие действия доступны пользователю. Перейдите на вкладку «Realm roles» и нажмите «Create role». Введите название роли (например, admin, manager, viewer) и сохраните. Роли могут быть realm-уровня или client-уровня.

Создание пользователей На вкладке «Users» нажмите «Add user». Обязательно укажите имя пользователя, по желанию — email, имя и фамилию. После создания перейдите на вкладку «Credentials» и задайте пароль. Рекомендуется оставить опцию «Temporary» активной, чтобы пользователь сменил пароль при первом входе.

Назначение ролей пользователю На вкладке «Role mapping» нажмите «Assign role», выберите нужную роль из списка «Realm roles» и подтвердите назначение. Теперь пользователь обладает соответствующими правами.

Эти шаги позволяют быстро создать базовую структуру управления доступом для любого приложения.

Настройка клиентов и интеграция с приложениями

Клиенты в Keycloak — это приложения, которые подключаются к системе авторизации. Без клиента Keycloak не сможет понять, откуда пришел пользователь и куда его перенаправить после входа.

Создание клиента Перейдите на вкладку «Clients» и нажмите «Create client». Введите Client ID (например, my-frontend). На шаге «Login settings» укажите Valid Redirect URIs — адреса, на которые пользователь будет перенаправлен после авторизации. Для тестирования можно указать *. Остальные параметры можно оставить по умолчанию.

Типы клиентов Keycloak поддерживает различные типы клиентов:

• OpenID Connect — для веб-приложений, мобильных приложений и SPA.
• SAML — для интеграции с корпоративными системами.

Интеграция с приложением Процесс подключения стандартный:

1. Приложение перенаправляет пользователя на сервер Keycloak.
2. Keycloak запрашивает логин и пароль (или использует активную сессию).
3. После успешной аутентификации Keycloak возвращает код авторизации.
4. Приложение обменивает код на токены (Access, Refresh, ID).
5. Приложение использует токены для доступа к защищенным ресурсам.

Для быстрой проверки интеграции можно использовать готовый пример на Express + React.js. Склонируйте репозиторий, установите зависимости, укажите в .env IP-адрес сервера и имя реалма, затем запустите приложение. После нажатия кнопки входа вы будете перенаправлены в Keycloak, а после авторизации — обратно в приложение с токеном.

Возможности Keycloak: SSO, социальные логины и управление сессиями

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

Единый вход (SSO) SSO реализован на уровне реалма. Если пользователь успешно прошел аутентификацию в одном клиенте, Keycloak запускает сессию. При обращении к другому клиенту в том же реалме Keycloak проверяет наличие активной сессии и предоставляет доступ без повторного ввода пароля. При выходе из системы сессия закрывается сразу во всех подключенных приложениях.

Социальные логины Keycloak поддерживает авторизацию через внешние сервисы: Google, GitHub, VK и другие. Для настройки необходимо добавить Identity Provider в настройках реалма и указать Client ID и Client Secret, полученные от внешнего сервиса.

Управление политиками безопасности Администраторы могут настраивать:

• Парольные политики (минимальная длина, сложность, срок действия).
• Правила блокировки пользователей (после N неудачных попыток).
• Время жизни токенов (Access token, Refresh token).
• Правила принудительного выхода из приложения.

Управление сессиями Keycloak позволяет просматривать активные сессии пользователей, завершать их принудительно, а также настраивать ограничения на количество одновременных сессий для одного пользователя.

Эти возможности делают Keycloak подходящим для корпоративных сред, где требуется централизованное управление доступом и высокий уровень безопасности.

Интеграция с внешними каталогами: LDAP и Active Directory

Keycloak поддерживает интеграцию с корпоративными каталогами через протокол LDAP. Это позволяет синхронизировать пользователей из Active Directory (AD) или других LDAP-совместимых систем, что особенно важно для крупных организаций.

Настройка LDAP-провайдера В административной панели перейдите в раздел «User federation» и добавьте новый провайдер типа LDAP. Укажите:

• Connection URL (например, ldap://ad.example.com:389).
• Bind DN и Bind Credentials (учетные данные для подключения).
• Users DN (базовый DN для поиска пользователей).
• Атрибуты для маппинга (например, uid, mail, cn).

Режимы синхронизации Keycloak поддерживает два режима:

• Импорт пользователей — пользователи копируются в базу Keycloak и могут быть дополнены локальными атрибутами.
• Прямая аутентификация — Keycloak проверяет учетные данные напрямую в LDAP без хранения пользователей локально.

Преимущества интеграции

• Единая точка входа для всех корпоративных приложений.
• Автоматическая синхронизация учетных записей (создание, блокировка, удаление).
• Использование существующих парольных политик AD.

Интеграция с LDAP/AD делает Keycloak незаменимым для enterprise-сред, где уже развернута инфраструктура каталогов.

Производительность, масштабирование и ограничения Keycloak

Keycloak подходит для проектов любого масштаба, но при росте нагрузки могут возникать определенные сложности.

Производительность При небольшой нагрузке Keycloak «просто работает». Однако при большом количестве одновременных сессий кэш Keycloak (Infinispan) может начать вести себя нестабильно. В новых версиях (Keycloak X) кэш можно вынести в отдельное приложение, что улучшает управляемость.

Масштабирование Keycloak поддерживает кластеризацию и может быть развернут в Kubernetes. Для продакшен-окружений рекомендуется:

• Использовать внешнюю базу данных (PostgreSQL, MySQL).
• Настроить балансировку нагрузки.
• Отделить кэш от основного приложения.

Ограничения

• Keycloak строго следует стандарту OpenID Connect. Если ваша архитектура несовместима с этим стандартом, Keycloak может не подойти.
• При интеграции с приложениями часто возникают CORS-ошибки, если неправильно настроены Redirect URIs.
• Внешние зависимости (например, подключение к базе данных) требуют тюнинга при росте нагрузки.

Когда Keycloak не нужен Если вы разрабатываете небольшой проект (например, сайт для трех друзей), внедрение Keycloak может быть избыточным. В таких случаях достаточно простой аутентификации через логин/пароль или готового решения типа Auth0. Keycloak оправдан, когда требуется централизованное управление доступом для нескольких приложений или микросервисов.

Практические примеры: авторизация через Keycloak в веб-приложении

Рассмотрим пример интеграции Keycloak с веб-приложением на Express (Node.js) и React.js. Этот сценарий демонстрирует типовой flow авторизации.

Шаг 1. Настройка клиента в Keycloak Создайте клиент с типом OpenID Connect. Укажите Valid Redirect URIs (например, http://localhost:3000/*).

Шаг 2. Установка зависимостей В проекте установите библиотеку keycloak-connect для Express и @react-keycloak/web для React.

Шаг 3. Конфигурация В файле .env укажите:

• KEYCLOAK_URL=http://:8080
• KEYCLOAK_REALM=myapp
• KEYCLOAK_CLIENT_ID=my-frontend

Шаг 4. Защита маршрутов На сервере используйте middleware для проверки токена:

const Keycloak = require('keycloak-connect');
const keycloak = new Keycloak({}, {
  realm: process.env.KEYCLOAK_REALM,
  'auth-server-url': process.env.KEYCLOAK_URL,
  resource: process.env.KEYCLOAK_CLIENT_ID
});
app.use(keycloak.middleware());
app.get('/protected', keycloak.protect(), (req, res) => {
  res.json({ message: 'Доступ разрешен' });
});

Шаг 5. Клиентская часть На фронтенде используйте компонент ReactKeycloakProvider для управления состоянием авторизации. После входа пользователь получает токен, который можно использовать для запросов к API.

Результат Пользователь переходит на защищенную страницу, перенаправляется в Keycloak, вводит логин и пароль, после чего возвращается обратно с токеном. Приложение проверяет токен и предоставляет доступ.

Этот пример можно адаптировать для любого фреймворка: Django, Spring Boot, Flask и других.

Вопросы и ответы