Что такое Keycloak: SSO, OAuth 2.0 и управление учётными записями с открытым кодом

Что такое Keycloak

Keycloak — сервер идентификации с открытым исходным кодом: он берёт на себя вход пользователей, хранение учётных записей и выдачу прав для ваших приложений. Нужен он для того, чтобы не писать авторизацию в каждом сервисе заново: пользователь входит один раз (SSO), а приложения получают от Keycloak подтверждение по стандартным протоколам OpenID Connect, OAuth 2.0 или SAML 2.0.

Проект распространяется под лицензией Apache 2.0, работает на платформе Quarkus и входит в Cloud Native Computing Foundation в статусе инкубационного проекта. Актуальная версия на сентябрь 2026 года — 26.7.4.

Что умеет

• Единый вход (SSO). Пользователь входит один раз и получает доступ ко всем подключённым приложениям; выход тоже может быть общим.
• Стандартные протоколы. OpenID Connect и OAuth 2.0 для веб- и мобильных приложений и API, SAML 2.0 — для корпоративных систем, которые не умеют OIDC.
• Многофакторная аутентификация. Одноразовые коды из приложения-аутентификатора (TOTP), аппаратные ключи и ключи устройств по стандарту WebAuthn.
• Вход через внешних провайдеров. Google, GitHub, корпоративный SAML- или OIDC-провайдер, а также Active Directory и LDAP — Keycloak может брать пользователей из существующего каталога, не перенося их.
• Роли и группы. Права задаются на уровне realm и отдельных клиентов и передаются приложению в токене.
• Расширение. Темы оформления страниц входа и собственные провайдеры через Service Provider Interfaces (SPI).

Основные понятия

• Realm — изолированное пространство со своими пользователями, клиентами и настройками. Служебный realm master предназначен только для администрирования; для приложений создают отдельный realm.
• Client — приложение, которое доверяет Keycloak вход пользователей. Для веб-приложения с сервером используют конфиденциального клиента с секретом, для одностраничного приложения и мобильного — публичного клиента с PKCE.
• Роли бывают уровня realm (общие) и уровня клиента (для конкретного приложения). Роли удобнее назначать группам, а не отдельным пользователям.

Как запустить

Для знакомства достаточно одной команды из официального руководства — она запускает Keycloak в режиме разработки с учётной записью администратора:

docker run -p 127.0.0.1:8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.7.4 start-dev

Режим start-dev не годится для работы: он хранит данные во встроенной базе dev-file, которая, по документации, предназначена только для разработки, и не требует HTTPS. Для рабочей установки нужны:

• внешняя база данных — PostgreSQL, MySQL, MariaDB, Oracle или Microsoft SQL Server (параметры --db, --db-url-host, --db-username, --db-password);
• адрес сервера — в рабочем режиме обязателен параметр --hostname (лучше полным URL) либо явный --hostname-strict false;
• TLS — сертификат и ключ в формате PEM (--https-certificate-file, --https-certificate-key-file) или завершение TLS на обратном прокси; во втором случае нужны --http-enabled=true и --proxy-headers xforwarded (или forwarded).

Пример запуска за обратным прокси, который завершает TLS:

bin/kc.sh start \
  --hostname https://sso.example.ru \
  --db postgres --db-url-host db.internal \
  --db-username keycloak --db-password 'длинный-пароль' \
  --http-enabled=true --proxy-headers xforwarded

Документация рекомендует открывать наружу только пути /realms/, /resources/ и /.well-known/, а консоль администрирования /admin/, служебный realm /realms/master/, а также /metrics и /health держать доступными лишь из внутренней сети.

Ограничения

• Администрирование. Keycloak — ещё один критичный сервис: его нужно обновлять (новые версии выходят часто), резервно копировать вместе с базой и отслеживать. Если он недоступен, пользователи не могут войти ни в одно приложение.
• Ресурсы. Это Java-приложение: памяти ему нужно больше, чем лёгким серверам аутентификации, и на самом дешёвом VPS он будет работать с трудом.
• Порог входа. Настроек много, и часть из них неочевидна: сроки жизни токенов и сессий, типы клиентов, redirect URI, сопоставление атрибутов при подключении LDAP.

Типичные ошибки

• Рабочая установка в режиме start-dev со встроенной базой.
• Приложения в realm master и консоль администрирования, открытая в интернет.
• Redirect URI со звёздочкой (https://example.ru/* или просто *) — это позволяет перенаправить токен на чужую страницу.
• Отсутствие резервной копии базы Keycloak: при её потере пропадают все пользователи, клиенты и настройки.
• Обновление сразу через несколько версий без чтения заметок о миграции.

Когда выбирать

Keycloak подходит, если у компании несколько внутренних или клиентских приложений, нужен единый вход, двухфакторная аутентификация и связь с Active Directory или LDAP, а данные пользователей должны оставаться на собственных серверах — в том числе в России, где с 1 июля 2025 года первичный сбор персональных данных граждан допускается только в базы на территории страны. Для одного небольшого сайта с входом через соцсети он избыточен.

Если нужна помощь с установкой и подключением приложений, посмотрите услугу по настройке Keycloak и SSO.