Keycloak для внутренних систем: SSO по OIDC и SAML без лицензий

С чем обычно сталкиваются при входе во внутренние системы

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

Добавьте удаленную работу и подрядчиков. Доступ нужно выдавать быстро, отзывать так же быстро и не гадать, кто и куда заходил. При этом сбой в одном сервисе не должен заставлять всех срочно менять пароли во всех остальных.

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

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

Подключать обычно приходится разнородный набор: кадровые сервисы, заявки и документооборот, CRM/ERP, ВКС и почту, внутренние админки, а иногда и самописные приложения. Хорошая SSO-схема должна закрывать и современные протоколы (OIDC), и более старые интеграции (SAML), чтобы не переписывать все сразу.

Keycloak: где он уместен

Keycloak решает базовую боль внутренних систем: один вход вместо десятков паролей и разрозненных экранов логина. Он берет на себя аутентификацию, хранит и проверяет учетные записи, умеет подключать внешний каталог (например, LDAP или Active Directory). Приложениям он выдает подтверждение входа в виде токенов или утверждений. Так вы централизуете вход, правила доступа и часть требований ИБ, не размазывая настройки по каждому сервису.

OIDC и SAML отличаются в первую очередь форматом обмена данными и типичным окружением. OIDC обычно проще для современных веб- и мобильных приложений: он строится вокруг токенов (JWT) и хорошо ложится на API. SAML чаще встречается в корпоративных системах и старых веб-приложениях: он передает подписанные XML-утверждения и подходит там, где SAML уже принят как стандарт.

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

Бывает и наоборот: если вам нужен строго управляемый облачный сервис без собственной эксплуатации, есть жесткие требования к сертификации конкретного продукта или ваша инфраструктура настолько простая, что хватает встроенной авторизации одного приложения, отдельный IAM может оказаться лишним.

До старта лучше проговорить ответственность. Иначе SSO быстро превращается в «ничей» критичный сервис. На практике обычно нужны три роли: владелец IAM (правила доступа и жизненный цикл учеток), администратор Keycloak (конфигурация, интеграции, обновления) и ИБ (MFA, пароли, аудит и расследования).

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

Подготовка: окружение, домен, пользователи и базовая гигиена

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

Окружения: dev, test, prod

Разделяйте хотя бы три среды. Иначе тестовые клиенты, роли и настройки неизбежно «протекут» в прод.

• dev: быстрые эксперименты, можно сбрасывать базу и realm
• test: максимально похоже на прод, проверка обновлений и миграций
• prod: изменения по процедуре, с резервной копией и планом отката

Дальше определитесь с доменным именем. Для SSO важно, чтобы адрес Keycloak был стабильным: пользователи к нему привыкают, а приложения жестко привязывают redirect/callback-адреса.

TLS-сертификат должен быть доверенным для всех рабочих устройств. Самоподписанные сертификаты часто дают неожиданные ошибки входа и предупреждения браузера.

Синхронизация времени (NTP) обязательна. Разница даже в пару минут ломает токены и подписи, и вы получаете «случайные» отказы входа.

Где держать пользователей

Если у вас уже есть LDAP/Active Directory, обычно проще подключить его как основной источник пользователей: единые пароли, увольнения, группы. Локальные пользователи в Keycloak удобны для пилота, сервисных учетных записей и аварийного доступа, но в масштабе их сложнее поддерживать.

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

Перед настройкой каждого приложения соберите минимум данных: базовый URL, точные redirect/callback URI, ответственного администратора со стороны приложения, список ролей/групп и требования к сессии (таймауты, выход, «запомнить устройство» для MFA).

Как подключить приложение по OIDC

Keycloak чаще подключают по OIDC, если приложение вебовое и умеет OpenID Connect (современные стеки и многие готовые корпоративные порталы).

Сначала задайте основу в Keycloak: создайте отдельный realm под организацию или среду (например, "intranet-dev" и "intranet-prod"). Сразу проверьте сроки жизни сессии и токенов (access/refresh), политику пароля и базовые требования к безопасности. Эти настройки потом сложно менять без влияния на пользователей.

Дальше подключение обычно укладывается в несколько шагов:

• Создайте Client с типом OpenID Connect и задайте Client ID (обычно имя приложения).
• Настройте Valid Redirect URIs, Web Origins и параметры выхода (если нужен post logout redirect).
• Выберите тип доступа: confidential (есть client secret) или public (без секрета, часто для SPA), и включите Authorization Code Flow.
• Решите, какие данные нужны приложению в токенах: минимум sub, часто email, а для прав доступа - роли или группы.
• Протестируйте вход и проверьте, что приложение читает нужные claims.

Пример: внутренний портал кадров хочет показывать ФИО и открывать разделы по роли. Тогда ему обычно достаточно email для привязки учетной записи и роли (например, "hr" или "manager") в ID token или через UserInfo.

Если после логина появляются ошибки редиректа, почти всегда причина в одном из типовых мест: redirect URI не совпадает посимвольно (лишний слэш, другой протокол), не добавлен домен в Web Origins, перепутан confidential/public, неверно указан realm или Client ID, либо приложению нужен claim (email/groups), но он не добавлен через mappers.

Как подключить приложение по SAML

SAML часто проще, когда у вас есть старые корпоративные порталы, самописные приложения или «коробки», которые давно умеют только SAML и не планируют OIDC. Для внутренних систем это обычная история: единый вход нужен, а переписывать приложение дорого.

Шаги настройки

Начните с минимально рабочего входа, а уже потом добавляйте подпись, шифрование и Single Logout.

1. В Keycloak создайте новый client и выберите протокол SAML.

2. Выгрузите metadata для клиента (оно понадобится владельцу приложения). Параллельно запросите metadata со стороны приложения, если оно выступает как Service Provider.

3. Настройте ключевые поля: ACS URL (куда Keycloak отправляет ответ после входа) и Entity ID (уникальный идентификатор приложения). Ошибка в одном символе здесь чаще всего и ломает интеграцию.

4. Если приложению нужен выход, договоритесь о подходе к Single Logout заранее. На практике SLO часто работает нестабильно, поэтому нередко выбирают простой вариант: выход только из приложения, без попытки разлогинить всю SSO-сессию.

5. Проверьте синхронизацию времени и часовые пояса на серверах. Из-за рассинхрона SAML-ответы могут считаться просроченными.

Сопоставление атрибутов

Дальше решите, какие данные Keycloak должен передавать в приложение. Чаще всего это имя и фамилия, email, логин, табельный номер и подразделение. Владелец приложения должен подтвердить, какие поля оно реально читает и какие обязательны при первой авторизации.

Затем согласуйте подпись и шифрование: что именно подписываем (response или assertion), нужен ли отдельный сертификат, какие алгоритмы допустимы, требуется ли шифровать assertion. Лучше зафиксировать это письменно, чтобы смена сертификатов или политик не превратилась в ночной инцидент.

Роли, группы и модель доступа без путаницы

Чтобы доступы не превратились в хаос, важно договориться о терминах.

• Realm - отдельная зона управления со своими пользователями, правилами входа и приложениями.
• Client - конкретное приложение, которое доверяет Keycloak и принимает вход по SSO.
• User - учетная запись человека или сервиса.
• Role - право (что можно делать).
• Group - способ выдавать права пакетом для группы пользователей.

Realm-roles и client-roles

Realm-role удобнее для общих, сквозных прав, которые одинаково трактуют разные приложения (например, "employee" или "security-auditor"). Client-role лучше подходит для прав внутри конкретного сервиса, где смысл завязан на его функции.

Если нужна простая логика, держитесь базовых правил: общие статусы и сквозные ограничения кладите в realm-roles, специфичные права приложения - в client-roles, а массовую выдачу прав делайте через группы. И не размножайте роли «на всякий случай»: оставляйте только те, которые приложение реально проверяет.

Группы особенно полезны, когда права повторяются. Например, вы заводите группу «Бухгалтерия», назначаете ей роли для портала заявок и отчетов, а дальше просто добавляете туда новых сотрудников.

Как права попадают в приложение (OIDC и SAML)

Для OIDC роли обычно уходят в токене как claims (часто это roles или блоки realm_access/client_access). Для SAML то же самое передается как attributes. В обоих случаях заранее решите, что именно приложение читает и на что опирается, иначе получите классическую ситуацию «роль есть, а доступа нет».

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

• portal-user - создавать и смотреть свои заявки
• portal-operator - обрабатывать заявки
• admin-console - управлять справочниками и настройками
• reports-read - читать отчеты

MFA в Keycloak: настройка, исключения и восстановление доступа

Второй фактор почти всегда окупается после первого же инцидента с украденным паролем. Его важно вводить так, чтобы не остановить работу: начать с небольшой группы, проверить типовые сценарии и только потом расширять охват.

Какие факторы выбрать

На практике чаще всего начинают с TOTP в приложении-аутентификаторе. Если у сотрудников современные браузеры и корпоративные устройства, WebAuthn (ключи безопасности или встроенная биометрия) обычно дает меньше нагрузки на поддержку. Одноразовые коды полезны как запасной вариант на случай, когда основной фактор недоступен.

Где и как включать MFA

MFA в Keycloak обычно задают через потоки аутентификации (Authentication flows), а не одной «галочкой для всех». Удобный подход: базовый вход для всех и отдельное требование второго фактора для выбранных пользователей - по группам (например, «Админы», «Финансы») или точечно для конкретного приложения.

Рабочий порядок действий выглядит так: включить фактор и проверить привязку, сделать пилотную группу и обязать MFA для нее, прогнать сценарии (новое устройство, другой браузер, истекшая сессия), затем расширять охват, начиная с привилегированных ролей.

Не забывайте про исключения. Сервисные учетные записи и интеграции по токенам обычно не должны упираться в интерактивный MFA.

Восстановление доступа без паники

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

Пример: вы начинаете с группы ИБ и администраторов. В день пилота один сотрудник теряет доступ к TOTP. Если у него заранее есть резервные коды и понятный процесс перевыпуска, это займет минуты, а не поставит проект на паузу.

Логи и аудит для ИБ: что включить

SSO удобно до первого инцидента. Потом выясняется, что в приложении есть только «успешный вход», а кто, откуда и через какой клиент заходил, уже не восстановить. В Keycloak стоит заранее включить аудит так, чтобы он отвечал на простой вопрос: что произошло и кто это сделал.

Обычно включают события аутентификации и безопасности, а также админ-события. ИБ чаще всего нужны:

• входы и ошибки входа (успех/отказ), логаут, проблемы токенов и сессий
• события MFA (запрос, успех, отказ, блокировки, сброс и перепривязка)
• изменения доступа (назначение и снятие ролей, изменения групп, маппинг ролей)
• админ-действия (создание пользователей, сброс пароля, отключение учетной записи, изменения настроек realm и клиентов)

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

Для расследований важны поля, без которых запись почти бесполезна: пользователь (username/userId), время, исход (успех/отказ), IP, client (какое приложение), realm, тип события. Для админ-действий добавьте actor (кто менял) и target (кому меняли). Если есть прокси или балансировщик, проверьте, что в событиях сохраняется реальный IP, а не адрес промежуточного узла.

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

Чтобы разбор инцидентов не превращался в ручной поиск, приводите события к единому формату и связывайте их с логами приложений. Цепочка «неуспешные входы -> успешный вход -> выдача токена -> вызовы API» быстро показывает, был ли подбор пароля, обход MFA или ошибка в ролях.

Частые ошибки и ловушки при внедрении

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

Самая частая причина падения входа - redirect URI. Приложение живет на нескольких доменах (внутренний и внешний, тестовый и боевой, разные поддомены), а в клиенте прописан один адрес. В итоге часть пользователей получает ошибку после логина или попадает в круг переадресаций. Помогает единый канонический домен и список допустимых callback-адресов без лишних «на всякий случай».

Вторая ловушка - права доступа. Когда все раздают через одну широкую группу вроде «Сотрудники», роли быстро расползаются, и кто-то внезапно получает доступ к админке. Разделяйте роли (что можно делать) и группы (кому это нужно), и не смешивайте сервисные учетные записи с людьми.

Третья причина странных сбоев - время на серверах. Если часы на Keycloak, балансировщике и приложении расходятся, токены считаются «еще не действительными» или «уже просроченными». Это выглядит как случайные вылеты, особенно после обновлений.

С MFA часто перегибают: включают для всех, но не продумывают восстановление. Нужны сценарии на потерю телефона, понятная проверка личности, правила сброса MFA и фиксация этих действий.

Для ИБ критично не забыть про аудит админ-действий. Иначе в расследовании вы не ответите на вопрос, кто поменял маппинг ролей, отключил MFA или добавил новый redirect URI.

Перед подключением очередного сервиса полезно быстро проверить пять вещей: redirect URI покрывают реальные домены и окружения без лишних шаблонов, роли минимальные и группы понятные, время синхронизировано на всех узлах, для MFA есть процесс восстановления и ответственные, аудит админ-изменений и событий аутентификации включен и доступен.

Чеклист перед запуском в продакшн

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

Во-первых, описания должны быть не «в голове». Зафиксируйте, какие приложения подключены, кто владелец, и какие данные реально нужны приложению (email, табельный номер, подразделение). Если атрибуты не согласованы заранее, часть сервисов начнет плодить дубли учеток или выдавать доступ не тем людям.

Минимальный набор проверок:

• Для каждого приложения зафиксированы протокол (OIDC или SAML), адреса, ответственный владелец, нужные claims/атрибуты и группы, которые дают доступ.
• В тестовом контуре проверены логин, выход, таймауты сессии, обновление токенов и сценарий «уволенный сотрудник теряет доступ».
• Роли и группы описаны простыми словами и проверены по принципу «минимально нужные права».
• MFA включена по понятной политике: где обязательно, где исключения (например, сервисные учетные записи), и как восстанавливают доступ.
• Аудит и события безопасности включены, логи уходят в централизованное хранилище, хранение соответствует требованиям ИБ, доступ к журналам ограничен.

В конце сделайте короткий прогон сценария расследования. Возьмите тестового пользователя и попробуйте по логам ответить на вопросы: когда вошел, с какого IP и user-agent, в какие клиенты заходил, кто менял его роли. Если это не получается за 10-15 минут, в реальном инциденте будет тяжелее.

Пример: SSO для организации с несколькими внутренними сервисами

Представим организацию, где есть три внутренних сервиса: портал сотрудников (отпуска, приказы, заявки), Service Desk (инциденты и запросы) и система аналитики (отчеты по подразделениям). Пользователей удобно разделить на две группы: «Сотрудники» и «Операторы» (вторая группа работает в Service Desk и чаще имеет расширенный доступ).

Подключение обычно идет по нарастающей сложности. Сначала подключают портал по OIDC: это быстрый путь для современного веб-приложения и он дает видимый эффект. Затем добавляют Service Desk по SAML (так часто бывает с более старыми или коробочными системами). И только после того, как вход стабильно работает везде, включают MFA, чтобы не чинить сразу три вещи одновременно.

Роли лучше называть так, чтобы смысл был понятен владельцам процессов:

• Сотрудник: базовый доступ к порталу и своим данным
• Руководитель: согласование заявок, доступ к отчетам своего отдела
• Оператор: работа с тикетами в Service Desk
• Администратор: управление настройками, без «доступа ко всему подряд»

В спорных ситуациях ИБ почти всегда спрашивает два сюжета: «кто и почему увидел данные» и «не подбирали ли пароль». Для этого заранее включают и хранят события входа и админ-действий в Keycloak: успешные и неуспешные логины, блокировки brute force, выдачу токенов, смену пароля, привязку/сброс MFA, а также изменения ролей и групп. Важно, чтобы в событиях были время, пользователь, client (какое приложение), IP и user-agent.

Для пользователя итог выглядит просто: один экран входа для всех сервисов, а MFA запрашивается в понятные моменты (например, при первом входе за день или при входе с нового устройства).

Следующие шаги: пилот, запуск и поддержка

Начните с пилота, который даст быстрый результат и покажет реальную сложность интеграций. Выберите 2-4 внутренних приложения: одно по OIDC, одно по SAML и, по возможности, одно с повышенными требованиями (например, доступ к персональным данным). Для старта обычно хватает простой модели: 3-5 ролей под понятные сценарии (пользователь, руководитель, администратор, поддержка, аудит).

Чтобы пилот не превратился в вечную «песочницу», заранее определите критерии успеха: единый вход без повторных паролей, корректная выдача ролей, MFA для выбранных групп и воспроизводимые логи для ИБ.

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

Поддержку лучше закрепить простым регламентом: кто имеет право менять настройки клиентов OIDC/SAML и ролей, когда проходит окно изменений, кто утверждает исключения из MFA. Отдельно продумайте реакции на блокировки MFA: как пользователь восстановит доступ, сколько это займет и какие проверки личности нужны. Полезен аварийный сценарий (временный доступ или резервный метод), но с обязательной фиксацией в журнале и последующим разбором.

Если у вас много разных приложений, сложные SAML-настройки и строгие требования ИБ к аудитам и расследованиям, проще подключать интегратора. Здесь важны не «тонкости протокола», а дисциплина: жизненный цикл сертификатов, маппинг атрибутов, правила выдачи прав и стабильная эксплуатация.

Если нужна помощь именно на стороне инфраструктуры и эксплуатации (серверы под размещение, интеграция и поддержка 24/7), это можно закрыть через GSE.kz как системного интегратора и производителя серверов и рабочих станций.