Интеграция сайта и внутренних систем с Keycloak: что нужно знать перед внедрением

В чём задача и кому полезна статья

Когда в компании есть сайт, личный кабинет, внутренний портал, CRM и ещё пара сервисов, у каждого свой логин и пароль — неудобно пользователям и рискованно для безопасности: пароли дублируются, у уволенных сотрудников не всегда вовремя отзывают доступ, а разработчикам приходится в каждом проекте заново писать формы входа и восстановление пароля.

Keycloak решает эту задачу централизованно: один вход — доступ ко всем связанным системам, а сами пароли и правила доступа хранятся и проверяются в одном месте. Статья полезна тем, кто прикидывает, стоит ли внедрять такую систему, какими силами это делается и на что обратить внимание в российских реалиях.

Что такое Keycloak простыми словами

Keycloak — это отдельный сервер, который берёт на себя вход пользователей и выдачу прав доступа для других приложений. Вместо того чтобы каждое приложение само проверяло пароли и хранило пользователей, оно доверяет эту работу Keycloak и получает от него подтверждение: «это пользователь Иван Иванов, у него такие-то роли».

Продукт изначально разрабатывался в Red Hat, с сентября 2014 года, а в апреле 2023-го был передан фонду Cloud Native Computing Foundation как инкубационный проект [2]. Актуальная стабильная версия на момент подготовки статьи — 26.7.x [1]. Коммерческую версию с долгосрочной поддержкой конкретных релизов предлагает Red Hat под названиями Red Hat Single Sign-On и Red Hat build of Keycloak — это стоит иметь в виду компаниям, которым нужна платная поддержка вендора, а не только community-версия [4].

Как работает единый вход через Keycloak

Realm, client, роли, токены

В Keycloak есть несколько базовых понятий:

• Realm — изолированное пространство со своими пользователями, ролями и настройками. Обычно один realm — это одна организация или один крупный проект; пользователи разных realm-ов не видят друг друга.
• Client — зарегистрированное приложение (сайт, мобильное приложение, внутренний сервис), которому разрешено запрашивать вход через Keycloak.
• Роли и группы — определяют, что пользователю разрешено делать после входа; роли можно синхронизировать с группами из LDAP/AD.
• Токены — после успешного входа Keycloak выдаёт JWT-токены (ID-токен, access-токен, refresh-токен), которые приложение проверяет по открытому ключу с эндпоинта /realms/{realm}/protocol/openid-connect/certs.

OpenID Connect vs SAML — когда что выбирать

Keycloak одновременно реализует два протокола, и для новых интеграций почти всегда выбирают OpenID Connect (OIDC) — надстройку над OAuth 2.0, которая добавляет стандартный ID-токен с данными о пользователе и удобный discovery-документ /.well-known/openid-configuration [5][6]. Для браузерных и мобильных приложений рекомендуемый сценарий — Authorization Code Flow с PKCE: пользователя перенаправляют на страницу входа Keycloak, после успешной аутентификации сервер возвращает временный код, который приложение обменивает на токены через отдельный защищённый запрос к серверу [5][6].

SAML 2.0 обычно оставляют для legacy-систем или партнёрских интеграций, где на другой стороне уже стоит SAML-совместимый сервис (например, некоторые корпоративные порталы и государственные системы) — сам Keycloak поддерживает и такие сценарии, включая identity brokering (вход через внешнего провайдера) [1].

Подключение LDAP/Active Directory

Если в компании уже есть Active Directory или другой LDAP-каталог, переносить пользователей вручную не нужно — Keycloak умеет подключаться к каталогу как к «user federation»: при входе пароль пользователя проверяется напрямую в AD, а не хранится в Keycloak [7][8]. Настройка включает:

• сервисную учётную запись с правом чтения на нужные OU;
• параметры подключения (LDAP или LDAPS-порт, доверенный сертификат AD для защищённого соединения);
• режим синхронизации — импорт при первом входе или периодическая полная/частичная синхронизация;
• маппер для групп AD в роли Keycloak, чтобы права доступа управлялись централизованно в каталоге [7][8].

Важный нюанс для сетевой архитектуры: если Keycloak развёрнут в облаке, а AD — в локальной сети компании, потребуется VPN или выделенный канал связи между ними [7].

Российская специфика

Реестр отечественного ПО и статус Keycloak

Сам по себе community-Keycloak — зарубежный open source продукт и в Единый реестр российского ПО не входит [9][10]. При этом существует зарегистрированный вариант «Keycloak.ЕСИА» — доработанный форк с интеграцией ЕСИА (портал Госуслуг), внесённый в реестр Минцифры под номером 22440 по решению от 14 мая 2024 года [3]. Если для проекта критично формальное наличие продукта в реестре (например, из-за требований 44-ФЗ/223-ФЗ или внутренней политики импортозамещения), стоит явно разбираться, какой именно продукт и в какой конфигурации нужен — «Keycloak» и «Keycloak.ЕСИА» для реестровых целей не одно и то же.

152-ФЗ, ФСТЭК и требования к ИБ

Требования 152-ФЗ и приказа ФСТЭК №21 касаются не выбора конкретного IAM-продукта, а того, как организована защита персональных данных вокруг системы аутентификации:

• персональные данные российских пользователей должны обрабатываться с использованием баз данных, находящихся на территории РФ [11];
• уровень защищённости ИСПДн (по постановлению правительства №1119) определяет обязательный набор мер — от журналирования доступа до многофакторной аутентификации для наиболее чувствительных категорий данных [12];
• сертификации самого Keycloak по требованиям ФСТЭК не существует — это отдельно подчёркивают поставщики сертифицированных отечественных альтернатив [13].

На практике это означает: Keycloak можно использовать как технический компонент, но соответствие 152-ФЗ обеспечивается организационными мерами и настройкой всей инфраструктуры (хостинг в РФ, шифрование, MFA, аудит доступа), а не самим фактом установки IAM-сервера.

Когда стоит смотреть на российские альтернативы

На рынке есть зрелые российские IAM/SSO-решения, изначально спроектированные под локальные требования — например, Blitz Identity Provider (сертификат ФСТЭК, 4-й уровень доверия, поддержка входа через российские банки и Госуслуги) и RooX UIDM (в реестре отечественного ПО, заявленное соответствие ГОСТ) [13][9]. Поставщики этих решений указывают, что доработка Keycloak под сценарии ЕСИА, отечественные банковские интеграции и УКЭП потребует существенной кастомизации «из коробки» [13].

Разумный подход: если проект — коммерческий сайт или внутренний портал без обязательного реестра и без работы с ЕСИА/банковскими шлюзами, Keycloak обычно закрывает задачу быстрее и дешевле за счёт готовой экосистемы и бесплатной лицензии. Если же есть обязательные требования к сертификации, реестру или глубокой интеграции с российской государственной инфраструктурой — сравнение стоит начинать с локальных решений.

Варианты реализации интеграции

В зависимости от масштаба задачи возможны разные конфигурации:

• Один Keycloak-сервер для сайта и одного-двух внутренних сервисов — минимальная конфигурация: один realm, несколько клиентов, ручное управление пользователями или простая LDAP-федерация.
• Keycloak как центральная точка SSO для набора систем — сайт, личный кабинет, CRM/ERP, внутренние админки подключаются как отдельные клиенты одного realm-а, роли синхронизируются из AD.
• Keycloak + внешние провайдеры входа (identity brokering) — вход через соцсети, корпоративный SSO партнёра или государственный провайдер идентификации оформляется как федерация внешнего IdP внутри того же realm-а [1].
• Отказ от Keycloak в пользу отечественного IAM — если требования к реестру, сертификации или интеграции с ЕСИА перевешивают экономию на лицензии [13][9].

Что при этом обычно нужно продумать: какие системы участвуют в обмене, какие данные передаются в токене (email, роль, подразделение), нужен ли доступ к внутренним API по этому же токену, как обрабатываются ошибки авторизации на стороне интегрируемых приложений, какие доступы нужны для настройки (административная роль в Keycloak, сервисная учётная запись в AD), как тестируется вся цепочка на отдельном стенде перед продакшеном.

Практические этапы внедрения

1. Анализ систем и требований. Составить список приложений, которые должны участвовать в SSO, и определить, какие данные о пользователе им нужны.
2. Развёртывание Keycloak. Выбор инфраструктуры (свои серверы, облако, Kubernetes), настройка HTTPS, при необходимости — кластеризация для отказоустойчивости [1].
3. Создание realm и клиентов. Для каждого приложения — отдельный client с корректным списком Valid Redirect URIs и типом доступа (confidential/public).
4. Подключение LDAP/AD (если есть). Настройка сервисного аккаунта, тестового соединения, маппинга групп на роли [7][8].
5. Интеграция приложений. Подключение сайта и сервисов по OpenID Connect (обычно — готовые библиотеки для популярных фреймворков) или SAML для legacy-систем.
6. Тестирование сценариев. Вход, выход, истечение токена, отзыв доступа, работа за reverse proxy — отдельно проверяется передача заголовка X-Forwarded-Proto, чтобы избежать несовпадения схемы http/https в redirect_uri [14][15].
7. Настройка мониторинга и процесса обновлений. Из-за регулярных CVE в Keycloak важно не «поставить и забыть», а следить за релизами безопасности [16][4].
8. Проверка соответствия требованиям ИБ. Если система обрабатывает персональные данные — согласовать конфигурацию хранения и логирования с требованиями 152-ФЗ и внутренней политикой ИБ [11][12].

Ограничения, ошибки и риски

Самые частые проблемы при внедрении — не архитектурные, а конфигурационные:

• Несовпадение redirecturi. Keycloak сверяет значение посимвольно, включая протокол, порт и завершающий слэш — типичная причина ошибки «Invalid parameter: redirecturi» [14][15].
• Reverse proxy не передаёт заголовок X-Forwarded-Proto. Приложение думает, что работает по http, а Keycloak ожидает https — токены и редиректы расходятся [14].
• Проблемы с cookie/SameSite при разных доменах Keycloak и приложения — сессия не сохраняется между переходами [15].
• Устаревшая версия без патчей. У Keycloak регулярно выходят обновления безопасности — например, за один только релиз 26.7.2 закрыто больше десяти CVE разного уровня критичности [16]. Отставание от цикла обновлений — реальный риск.
• Ожидание «сертификации из коробки». Community Keycloak не сертифицирован ФСТЭК и не включён в реестр отечественного ПО — если это требование заказчика, его нужно закрывать либо специализированным форком, либо переходом на сертифицированное решение [3][13].

Отдельно стоит учитывать: наличие у Keycloak богатого API не означает, что все операции безопасно открывать наружу без дополнительного контура защиты — административный REST API и account-эндпоинты стоит изолировать от публичного интернета и ограничивать по ролям.

Как выбрать решение

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

Если же проект связан с госзакупками, обязательным использованием реестра отечественного ПО, интеграцией с ЕСИА или требует сертификата ФСТЭК — разумнее сразу сравнивать Keycloak с отечественными IAM-платформами и закладывать это сравнение в техническое задание, а не выяснять несоответствие постфактум.

Про сроки и стоимость внедрения нельзя сказать заранее без конкретики: они зависят от числа интегрируемых систем, наличия/отсутствия LDAP-каталога, требований к отказоустойчивости и глубины кастомизации интерфейса входа.

Как может помочь «Пятый фактор»

Основная сложность интеграции Keycloak с сайтом и внутренними системами обычно не в самой установке сервера, а в согласовании потоков данных между всеми участниками: какие роли и атрибуты передаются в токене, как реагирует каждое приложение на истечение сессии, как выстроить связку с уже существующей 1С, CRM или внутренним порталом. Команда «Пятого фактора» может изучить текущий ландшафт систем, оценить, достаточно ли типовой настройки Keycloak или нужна дополнительная разработка (кастомные мапперы, интеграция с внутренними API, синхронизация с LDAP/AD), и помочь с реализацией интеграции.

Что проверить перед переводом Keycloak в рабочий контур

Рабочий контур Keycloak требует больше, чем настройка страницы входа. До запуска нужно проверить права, сессии, восстановление и административный доступ.

• Настроить отдельные клиенты и точные redirect URI для каждого приложения, исключив широкие маски без необходимости.
• Проверить срок жизни токенов, выход из системы, отзыв сессии и поведение приложения при недоступности сервера авторизации.
• Разделить роли realm и приложения так, чтобы пользователю выдавались только нужные права.
• Подключить резервное копирование конфигурации и базы, а затем выполнить пробное восстановление на отдельном контуре.
• Настроить обновления, журналы событий и наблюдение за ошибками входа, задержкой и состоянием узлов.
• Ограничить административный интерфейс, разделить учётные записи администраторов и проверить аварийный доступ.

Вывод

Keycloak — зрелый и бесплатный инструмент для единого входа, который закрывает большинство типовых задач: подключение сайта, внутренних сервисов, LDAP/AD-каталога и внешних провайдеров идентификации. Ключевое, что стоит проверить до начала внедрения в российских условиях — не упирается ли проект в требования реестра отечественного ПО, сертификации ФСТЭК или обязательной интеграции с ЕСИА: в этих случаях стоит заранее сопоставить Keycloak с локальными альтернативами, а не дорабатывать его под эти сценарии постфактум.

Чтобы обсудить задачу или получить консультацию, свяжитесь с командой «Пятого фактора» любым удобным способом.

Источники

[1] keycloak.org — Keycloak 26.7.0 released — https://www.keycloak.org/2026/07/keycloak-2670-released

[2] en.wikipedia.org — Keycloak — https://en.wikipedia.org/wiki/Keycloak

[3] catalog.arppsoft.ru — Keycloak.ЕСИА: каталог совместимости российского ПО — https://catalog.arppsoft.ru/product/6340022

[4] endoflife.date — Keycloak — https://endoflife.date/keycloak

[5] keycloak.org — Securing applications and services with OpenID Connect — https://www.keycloak.org/securing-apps/oidc-layers

[6] skycloak.io — OpenID Connect Explained: A Developer's Guide with Keycloak — https://skycloak.io/blog/openid-connect-explained-developers/

[7] medium.com — Integrating Active Directory (AD) with Keycloak — https://medium.com/@serkanturan_79203/integrating-active-directory-ad-with-keycloak-for-user-federation-ee6d3974aba3

[8] wjw465150.gitbooks.io — LDAP/AD Integration (Keycloak documentation) — https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/user-federation/ldap.html

[9] uidm.ru — RooX UIDM — альтернатива Keycloak — https://uidm.ru/keycloak

[10] wissance.com — Чем заменить Keycloak: российская альтернатива — https://wissance.com/blog/chem-zamenit-keycloak/

[11] cloud.ru — 152-ФЗ: требования к хранению и обработке персональных данных — https://cloud.ru/blog/152-fz

[12] rtmtech.ru — Защита персональных данных: 152-ФЗ, приказ 21 ФСТЭК — https://rtmtech.ru/articles/chto-nuzhno-chtoby-zashhitit-pdn/

[13] identityblitz.ru — Альтернатива Keycloak — https://identityblitz.ru/keycloak-comparison/

[14] skycloak.io — Keycloak Redirect URI Mismatch: Complete Troubleshooting Guide — https://skycloak.io/blog/keycloak-redirect-uri-mismatch-troubleshooting/

[15] skycloak.io — Keycloak Troubleshooting: Fix the 10 Most Common Errors — https://skycloak.io/blog/keycloak-troubleshooting-top-10-errors/

[16] keycloak.org — Keycloak 26.7.2 released — https://www.keycloak.org/2026/08/keycloak-2672-released