Keycloak: настройка многоуровневой аутентификации для безопасности корпоративных проектов

Читать такжеЭффективное управление доступом: делегируем безопасность приложения Keycloak

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

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

С помощью потоков аутентификации удается решать следующие задачи:

• Комбинировать разные способы аутентификации (пароль, одноразовый код, биометрия и т. д.);
• Настраивать многофакторную аутентификацию (MFA) и применять её выборочно для отдельных групп пользователей;
• Интегрировать внешние сервисы аутентификации (LDAP, OAuth, SAML);
• Создавать собственные методы проверки, например, вход через SMS-код;
• Контролировать логику аутентификации в зависимости от условий, например, включать 2FA только для администраторов.

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

Стандартные потоки аутентификации

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

Потоки аутентификации расположены в основном меню в разделе конфигурации realm:

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

Browser Authentication Flow

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

Применяется в следующих случаях:

• Вход пользователей через веб-интерфейс Keycloak;
• Использование одноразовых паролей (OTP) для дополнительной безопасности;
• Настройка адаптивной аутентификации, например, запроса 2FA только для определенных пользователей.

Client Authentication Flow

Поток предназначен для верификации приложений, которые обращаются к Keycloak от своего имени. Используется, например, в client credentials grant, когда сервис получает токен без участия пользователя.

Применяется в таких сценариях:

• Аутентификация микросервисов и бекенд-приложений;
• Безопасный доступ к API от имени зарегистрированных клиентов;
• Использование конфиденциальных клиентов: например, серверных приложений.

Direct Grant Flow

Аутентификация пользователя осуществляется без перенаправления на страницу входа Keycloak. Клиент отправляет запрос напрямую к Token Endpoint (/protocol/openid-connect/token) с логином, паролем и grant_type=password.

Используется в следующих случаях:

• CLI-инструменты и автоматизация, где браузерный вход невозможен;
• Мобильные и десктопные приложения, если вход должен происходить внутри интерфейса;
• Читать такжеМикросервисы vs монолит: разница архитектур и руководство по переходу
• Микросервисная архитектура, если сервису необходимо аутентифицировать пользователя без редиректа.

Docker Authentication Flow

Поток используется для аутентификации в Docker Registry. Позволяет сервисам взаимодействовать с приватными Docker-репозиториями через Keycloak.

Применяется для:

• Аутентификации контейнеров в защищенных Docker-реестрах;
• Управления доступом к образам контейнеров с использованием ролей и политик Keycloak.

First Broker Login Flow

Механизм обработки первого входа пользователя обеспечивает интеграцию с внешними системами идентификации, включая SAML, OAuth и OpenID Connect.

Поддерживает такие сценарии:

• Соединение учетных записей пользователей из внешних систем;
• Добавление дополнительной верификации после входа через внешний провайдер;
• Автоматическое создание локального профиля после первого входа.

Registration Flow

Поток определяет процесс регистрации новых пользователей. Может включать такие шаги: ввод данных, проверка email и установка пароля.

Используется для:

• Регистрации новых пользователей через интерфейс Keycloak;
• Добавления дополнительных проверок (например, капчи или email-подтверждения);
• Валидации введенных данных перед созданием аккаунта.

Reset Credentials Flow

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

Применяется в случаях:

• Восстановление пароля через email или SMS;
• Повторная верификация пользователя перед сбросом учетных данных;
• Обновление MFA или других параметров безопасности.

Шаги потоков аутентификации

В Keycloak потоки аутентификации состоят из шагов (execution steps) — последовательность действий, выполняемых в процессе проверки подлинности. Эти шаги можно настраивать и объединять в цепочки для реализации гибких сценариев входа.

Основные элементы шагов

Каждый шаг представляет собой отдельное действие в процессе аутентификации и может включать:

• Формы ввода — запрос логина, пароля, OTP и других данных;
• Проверки условий — анализ роли пользователя, IP-адреса, устройства и других параметров;
• Дополнительные методы аутентификации — использование 2FA, биометрии или внешних провайдеров.

Режимы выполнения шагов

Шаги в потоке аутентификации могут работать в одном из четырех режимов:

• Required;
• Alternative;
• Conditional;
• Disabled.

Required (Обязательный шаг)

Шаг выполняется всегда. Если он не проходит успешно, процесс аутентификации прерывается.

Примеры:

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

Alternative (Альтернативный шаг)

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

Примеры:

• Вход по паролю или по внешнему провайдеру (например, Google);
• Использование OTP или одобрение через мобильное приложение.

Conditional (Условный шаг)

Шаг выполняется только при соблюдении определенных условий. Задается условие через Condition Execution, например:

• Запрашивать 2FA только для администраторов;
• Пропускать ввод пароля, если пользователь уже прошел аутентификацию по сертификату;
• Использовать разные механизмы входа в зависимости от типа устройства.

Disabled (Отключенный шаг)

Шаг временно исключен из процесса аутентификации. Это может быть полезно, если нужно протестировать систему без определенного этапа.

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

Использование под-потоков (Sub-flow)

В отличие от отдельных шагов, Sub-flow может содержать:

• Обычные шаги аутентификации (например, ввод пароля, OTP);
• Другие вложенные Sub-flow, которые формируют иерархическую структуру потоков.

Использование Sub-flow упрощает настройку и поддержку сложных процессов аутентификации, позволяя:

• Группировать логически связанные шаги аутентификации;
• Создавать универсальные под-потоки, которые можно переиспользовать в разных сценариях;
• Гибко управлять альтернативными вариантами входа;
• Упрощать поддержку и модернизацию аутентификационных механизмов.

Двухфакторная аутентификация в Keycloak

Читать такжеКонтроль доступа к IT-проекту: как не потерять управление при работе с подрядчиками

Теперь рассмотрим, как добавить двухфакторную аутентификацию (2FA), используя одноразовые пароли (OTP) через Google Authenticator. Добавление второго фактора значительно повышает уровень безопасности учетных записей, поскольку даже при компрометации пароля злоумышленник не сможет получить доступ без дополнительного кода.

Использование Google Authenticator и других приложений для генерации OTP — это один из самых удобных и распространенных способов реализации 2FA. Не требует отправки SMS, что делает его более быстрым, дешевым и защищенным от атак на подмену номера (SIM swap fraud).

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

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

Далее нужно выбрать поток browser и продублировать его:

Теперь перейдем в новый поток. В шаг аутентификации через форму добавим OTP Form с типом Required. Не интересующие нас шаги можно удалить.

Для активации аутентификации по одноразовому коду, нужно перейти на вкладку Required actions в разделе Authentication и разблокировать поле Configure OTP.

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

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

Для осуществления аутентификации по временному коду пользователю необходимо скачать приложение Google Authenticator и войти в свой аккаунт. На этом завершается подготовка по настройке двухфакторной аутентификации (пароль + код).

Читать такжеМониторинг Spring Boot приложений — актуальные инструменты в 2025 году

Для демонстрации аутентификации реализуем небольшое приложение на Spring Boot. 

Настроим его конфигурацию Spring Security в качестве клиента:

Бин OAuth2UserService настраиваем на получение списка ролей пользователя из заданного свойства JWT-токена app_roles.

Добавим конфигурацию клиента в файле свойств приложения:

Создадим самый простой контроллер, который будет возвращать HTML-страницу авторизованного пользователя:

Для проверки работы процесса входа в систему перейдем по адресу приложения, где нас переадресует на страницу аутентификации Keycloak:

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

После успешного ввода пароля пользователю открывается форма с QR-кодом для настройки аутентификатора и поле ввода одноразового пароля. 

Дальше сканируем QR-код в приложении Google Authenticator и копируем временный код для вставки:

После первичной настройки на этом шаге аутентификации пользователю предложат только поле для ввода пароля.

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

Так Keycloak существенно упрощает интеграцию двухфакторной аутентификации в процесс входа в ваше приложение.

Настройка кастомной аутентификации по SMS-коду

Не всегда удобно или есть возможность использовать приложения для генерации OTP. В некоторых сценариях пользователи не хотят или не могут устанавливать сторонние приложения для аутентификации, такие как Google Authenticator. В таких случаях более удобным станет отправка одноразового кода (OTP) через SMS.

Keycloak не предлагает встроенной поддержки аутентификации через SMS, так как эта реализация требует интеграции с провайдером SMS-рассылок. Интеграция же зависит от конкретных бизнес-требований и инфраструктуры. Разные компании используют различных поставщиков SMS-услуг: Twilio, AWS SNS, Nexmo, и другие. Поэтому реализация аутентификации через смс ложится на плечи разработчиков, которые могут адаптировать ее под свои нужды.

Keycloak предлагает широкие возможности для кастомизации благодаря Service Provider Interface (SPI) – механизму расширения, который позволяет изменять и дополнять функциональность Keycloak.

SPI применяется для кастомизации различных аспектов работы Keycloak:

• Аутентификация – добавление новых методов входа, например, через SMS-код;
• Авторизация – создание новых политик доступа;
• Хранение пользователей – интеграция с кастомными базами данных или сервисами;
• События – обработка действий пользователей, например, логирование входов в систему.

Читать такжеАутсорсинг или заказная разработка на Java

Поэтому, если хочется использовать проверку подлинности через SMS-код, то нужно написать собственный аутентификатор с использованием Java, реализовав SPI-интерфейсы Keycloak, которые управляют процессом входа в систему. Это включает в себя создание Java-классов, отвечающих за генерацию и валидацию одноразовых кодов, интеграцию с провайдером отправки SMS, а также настройку аутентификационного потока в Keycloak. Такой подход позволяет нам полностью контролировать логику аутентификации, адаптировать ее под бизнес-требования и расширять возможности платформы.

Реализация аутентификатора

Для реализации SMS-аутентификатора нужно разработать небольшое Java-приложение, при этом использовать сборщики Maven или Gradle. Также нужно реализовать интерфейсы Authenticator и AuthenticatorFactory, которые предоставляет Keycloak SPI.

Для работы с Keycloak SPI потребуются зависимости:

Authenticator в Keycloak — это основной компонент, отвечающий за обработку процесса аутентификации. Именно он выполняет проверку учетных данных пользователя и решает, можно ли его допустить в систему. В данном примере в качестве учетных данных будет выступать временный код, отправленный пользователю по SMS.

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

Метод authenticate будет вызван при переходе на страницу ввода кода из SMS после успешного ввода логина и пароля. 

Принцип работы метода следующий:

1. Получение настроек пароля из конфигурации;
2. Генерация временного кода;
3. Сохранение кода в сессии;
4. Отправка кода на номер телефона пользователя.

Когда пользователь получит SMS, введет код и отправит форму, система активирует метод action. Здесь происходит двойная проверка: соответствие введенного кода отправленному и его актуальность по времени. При успешной валидации система отметит этап проверки подлинности как пройденный и продолжит процесс входа.

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

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

Создадим простую реализацию фейкового отправителя сообщений для разработки:

Для тестирования аутентификации код будет отображаться в логах Keycloak. При разработке собственного функционала следует использовать реальный SMS-провайдер.

Наконец, сконфигурируем разработанный аутентификатор. Для этого потребуется реализовать компонент AuthenticatorFactory.

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

На сниппете выше показаны основные методы интерфейса, включая определение настраиваемых параметров через getConfigProperties(). Особенно важным является метод create(), который создает и возвращает экземпляр нашего аутентификатора.

После реализации аутентификатора в Java также нужно создать пользовательский интерфейс для ввода кода аутентификации. В Keycloak для рендеринга страниц используется Freemarker Template Language (FTL), и нам нужно добавить соответствующий шаблон в ресурсы расширения, в директорию resources/theme-resources/templates:

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

• собрать и упаковать аутентификатор в JAR-архив, используя текущий сборщик;
• скопировать архив на сервер Keycloak в директорию /opt/keycloak/providers/;
• перезапустить Keycloak.

После этого можно настроить новый аутентификационный поток.

Продублируем стандартный браузерный поток, как это мы делали в предыдущем примере, и привяжем его к браузерному потоку аутентификации:

Далее перейдем в поток и добавим шаг SMS Authentication через раздел Add Step:

Добавим шаг в подпоток браузерных форм и сделаем его обязательным:

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

В конце настройки необходимо привязать наш новый поток к браузерному потоку, как мы делали это в предыдущем примере с OTP-кодом.

Использование верификации по SMS-коду

Перед запуском аутентификации по SMS пользователям необходимо добавить кастомный атрибут с кодом phone. Поле может быть любым, но наш аутентификатор настроен на получение номера телефона пользователя именно в данном поле. Добавить новый атрибут можно в настройках realm.

Аутентификатор сконфигурирован так, что при отсутствии данного поля у пользователя, шаг аутентификации по коду из SMS будет пропущен.

Далее выполним попытку входа в наше демонстрационное приложение. Начинаем с шага аутентификации по логину и паролю:

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

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

Заключение

На практических примерах мы рассмотрели возможности Keycloak: разработали небольшое демо-приложение на Spring Boot и настроили в нём двухфакторную аутентификацию, а также реализовали два варианта защиты — классический с Google Authenticator и через SMS.

Опыт работы с корпоративными проектами убеждает нас в эффективности Keycloak для задач с требованиями к гибкой системе безопасности. Платформа не требует переписывать код основного приложения для настройки процессов проверки подлинности. Особенно ценим возможности SPI-интерфейсов для расширения функционала под бизнес-требования — наш пример с SMS-верификацией хорошо это показывает.

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