Если вы хоть раз настраивали доступ к Grafana, Argo CD, Vault или Prometheus и сталкивались с аутентификацией «на костылях», значит, тоже задавались вопросом: почему бы не сделать это один раз и правильно — через SSO?

Эта пошаговый разбор мастер-класса с DevOpsConf 2025 в двух частях, из которых вы узнаете:

• Как разворачивать Keycloak в Kubernetes,

• Как настраивать Terraform-провайдера,

• Как интегрировать Keycloak с инфраструктурными сервисами,

• Как разграничивать доступ по ролям, группам и scopes,

• И главное — как не потерять контроль над системой и собой.

Всё по делу, с кодом, нюансами, и реальным опытом.

В первой части статьи пройдёмся по сущностям Keycloak, разберёмся, что это за зверь такой и какие у него особенности. Во второй — попрактикуемся и получим новые знания и умения. 

Поехали!

Зачем нужен SSO для инфраструктурных сервисов

Когда мы строим инфраструктуру для обслуживания наших приложений, используем различные инфраструктурные сервисы, такие, например, как Prometheus и Grafana, Hashicorp Vault, Argo CD и многие другие. Часть их них имеют встроенную аутентификацию  и авторизацию, некоторые — нет. В любом случае, тем, кто администрирует эту инфраструктуру, хотелось бы иметь единую систему контроля входа в эти сервисы. Эту проблему решают системы Single Sign-On (SSO). И в частности одну из них — Keycloak, мы и настроим в рамках нашей статьи.

Некоторые VPN сервисы также имеют возможность интеграции с Keycloak, например, Firezone, NetBird, что дает нам возможность расширить область единого входа и на эти сервисы.

На практике всё чаще выбор падает на Keycloak: с минимальными доработками он используется как в популярных open source решениях, так и в импортозамещённых продуктах. Сегодня Keycloak фактически стал стандартом, и знание его принципов и возможностей входит в базовый набор компетенций DevOps-инженера.

Ключевые возможности Keycloak:

• SSO для web-приложений.

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

  • OpenID Connect;

  • OAuth2;

  • SAML.

Дополнительные функции, которые есть в Keycloak:

• Аутентификация с помощью внешних SAML- и OIDC-провайдеров.

• Аутентификация через Google, GitHub, различные соцсети.

• Федерация через синхронизацию с LDAP и AD.

  • Keycloak в таком случае выступает как прокси, позволяющий интегрировать всю инфраструктуру через эти инструменты. 

• Поддержка двухфакторной аутентификации (TOTP/HOTP). В современных реалиях немаловажное требование. Инструменты TOTP/HOTP прекрасно интегрируются с Keycloak.

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

Основные понятия и термины Keycloak

Итак, что же из себя представляет Keycloak?

Realms

Установив Keycloak, мы попадаем в Master realm (на скриншоте). Он создаётся при установке.

Realms — это изолированные пространства для управления учётными записями, пользователями, клиентами, приложениями и так далее. Они позволяют на базе одного Keycloak разделять интегрируемые приложения и пользователей на независимые группы, будто управляемые разными Keycloak. То есть внутри Keycloak реализована мультитенантная система.

Одна из типичных ошибок при первом знакомстве с Keycloak — использовать Master-realm для всех задач. Делать этого не стоит. Master-realm предназначен исключительно для администраторов, управляющих самим Keycloak. Хотя технически он поддерживает весь функционал, использовать его для приложений, пользователей и клиентов — плохая практика. Лучше сразу выделить отдельные realms для изоляции окружений и повышения безопасности. Это базовый шаг к устойчивой и безопасной архитектуре.

В интерфейсе Keycloak в боковом меню всегда отображаются текущие realms, там же можно создать новые. На первый взгляд UI может показаться перегруженным: множество вкладок, вложенных параметров и всплывающих окон. Это может сбивать с толку, особенно при первом запуске. Но без знакомства с этими настройками работать с Keycloak не получится, их стоит изучить и освоить.

Clients

Следующий пункт в интерфейсе — клиенты. В Keycloak есть клиенты и есть пользователи (users). Это две разные сущности, которые ничего общего между собой не имеют.

Клиенты — это приложения и сервисы, которые запрашивают аутентификацию через Keycloak:

• Интерфейс для безопасной аутентификации.

• Токен доступа.

То есть это клиенты непосредственно Keycloak.

При интеграции с Keycloak каждый сервис — будь то Grafana, Argo CD, NetBird или внутренний продукт — регистрируется как отдельный клиент. Для каждого клиента необходимо задать credentials, параметры аутентификации, протоколы (например, OpenID Connect или SAML), client ID и секрет. Настройка может отличаться в деталях: разные сервисы ожидают разные поля в токенах и по-разному обрабатывают claims. Универсальной схемы нет — каждый случай индивидуален. Кроме того, стоит учитывать, что Keycloak активно развивается, и поддержка нужных функций может зависеть от версии. Поэтому важно синхронизировать требования клиента и возможности текущей сборки Keycloak.

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

• ID-токен — содержит информацию о пользователе, прошедшем аутентификацию.

• Access-токен — используется для авторизации доступа к защищённым ресурсам.

• Refresh-токен — позволяет обновить access- и ID-токены без повторной аутентификации.

Именно эти токены клиент передаёт в запросах, и на основе их содержимого определяется доступ к функциональности приложений.

Завести клиента очень просто:

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

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

Standard flow

• Приложение перенаправляет аутентификацию в браузере на Keycloak.

• При этом передаётся callback URL как параметр запроса.

• Keycloak при аутентификации создаёт короткоживущий одноразовый код и возвращает его на callback URL.

• Приложение использует этот код для получения токенов идентификации, доступа и обновления (identity, access, refresh).

Standard flow — это базовый и самый распространённый способ аутентификации для веб-приложений. Он работает по следующей схеме.

Пользователь пытается войти, например, в Grafana.

1. Grafana перенаправляет его на Keycloak с указанием callback URL.

2. Keycloak отображает форму входа с логином и паролем.

3. После успешной аутентификации Keycloak перенаправляет пользователя обратно на указанный callback URL, передавая одноразовый токен.

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

• ID-токен — с информацией о пользователе;

• Access-токен — для доступа к API;

• Refresh-токен — для продления сессии без повторного логина.

Этот одноразовый код действует ограниченное время и обеспечивает безопасную передачу токенов.

Какой именно токен будет использовать приложение для авторизации, зависит от приложения ​​и его требований. Это важно учитывать при интеграции.

Например, чаще всего  приложения извлекают данные из access-токена, в других случаях — из ID-токена. Редко, но возможно, что используются оба. Именно в эти токены Keycloak вставляет claims — утверждения о пользователе, такие как логин, email, роли, группы и прочее.

В случае инфраструктурных и open-source сервисов (например, Grafana, Argo CD, JupiterHub), документация обычно чётко указывает, какой именно токен требуется и какие claims должны быть в нём. Исходя из этого настраивается Keycloak — какие атрибуты включать, в какой токен, и в каком формате.

Implicit flow

• Токены идентификации, доступа и обновления передаются как параметры при перенаправлении на callback URL. Все токены (identity, access) возвращаются сразу при редиректе на callback URL, без дополнительного запроса на обмен кода на токены.

Неявный и ощутимо более короткий flow работает так же, как и стандартный, но без отдельного запроса на получение токенов после аутентификации. Токены передаются напрямую через URL-параметры при перенаправлении на клиент. Этот метод используется, например, в SPA-приложениях или в случаях, где нет возможности безопасно хранить client_secret. Он подходит для сценариев с минимальной логикой на стороне клиента и отсутствием серверной обработки.

Direct access grants

• Приложение напрямую передаёт логин и пароль в POST-запросе к Keycloak.

• А также client id.

• При необходимости client secret.

Это поток авторизации, при котором приложение напрямую передаёт логин и пароль пользователя в теле POST-запроса к Keycloak. Также указывается client_id, а при необходимости — client_secret. Этот способ используется в сценариях, когда нет браузера (например, CLI, устройства, VPN-клиенты), или нужна прямая авторизация пользователя без редиректов и промежуточных шагов, или требуется реализовать внутрисервисную аутентификацию, или доступ от имени пользователя.

Приложение получает токены (access, refresh) напрямую от Keycloak. Работает только при включённой настройке Direct Access Grants Enabled у клиента. Требует высокого уровня доверия к клиенту, так как логин и пароль передаются напрямую.

Service accounts roles

Кратко особенности этого flow можно описать так:

• Позволяет использовать роли и права сервисного аккаунта, ассоциированного с клиентом.

• Требует аутентификации клиента.

• Запрашивается токен

/realms/{realm-name}/protocol/openid-connect/token

Итак, при настройке клиента нужно обязательно указать требуемый flow для взаимодействия. Конкретика обычно указана в документации конкретного сервиса.

Продолжаем настраивать клиента. Переходим к настройкам логина.

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

Теперь  рассмотрим наборы настроек для каждого клиента, а именно client scopes.

Client scopes

Клиент — самая простая сущность. В нём есть как раз тот самый client scopes. Для каждого клиента он может быть свой и настроен отдельно.

Client scopes — это набор общих настроек, которые можно назначать различным клиентам:

• Привязка к протоколу: OIDC, SAML.

• Набор сопоставлений (mappings), которые добавляются в токен по требованию (claims).

Scopes в Keycloak определяют, какие атрибуты пользователя и его групп будут включены в токен, выдаваемый клиенту. Это механизм сопоставления данных профиля с правами доступа, которые нужны приложению. На практике каждый клиент может иметь свой набор подключённых scopes. Также можно создать общий scope и повторно использовать его для нескольких клиентов.

В каждом scope настраиваются mappings — сопоставления атрибутов, которые необходимо передать в токене. Эти mappings могут включать, например, email, имя, роли, кастомные поля и префиксы групп. При создании нового Realm автоматически создаётся базовый набор стандартных scopes (например, profile, email, roles). Вы можете: использовать существующие scopes, отключить ненужные, создать собственные  с нужными вам атрибутами и назначать scopes глобально или индивидуально на уровне каждого клиента.

Хотя сначала это может показаться сложным, на практике достаточно один раз правильно сопоставить атрибуты с требованиями приложения — и всё будет работать стабильно. Я покажу, как это делать.

Выглядит это примерно так:

Это дефолтный набор различных scopes, то есть атрибутов, которые передаются клиенту, например, email, телефон. Или можно создать отдельный scope, и уже в нем назначать mappings. 

Чуть позже мы попробуем сделать и то и другое. У нас это делается в Terraform, я покажу кусок кода, который он создал, и что в итоге получилось.

Mappings

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

Включается одна галочка, и он выкладывает роли в токен. По умолчанию Keycloak действительно вкладывает роли в токен, но делает это в виде вложенной структуры (nested map). Многие приложения, особенно сторонние инфраструктурные сервисы (например, Argo CD.), такую вложенность не поддерживают. В результате клиент «не видит» роли, даже если они технически присутствуют.

Поэтому включить галочку "Add realm roles to ID token" или "Add client roles to access token" может быть недостаточно. Нужно создать ручной protocol mapper, который указывает точный claim name (например, roles), задаёт тип данных (обычно String или String array), позволяет «расплющить» вложенность и сделать список ролей удобным для клиента.

Таким образом, кастомный mappings обеспечивает совместимость с любыми клиентами и позволяет избежать проблем с авторизацией на их стороне.

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

• Группы;

• Роли;

• Почтовый адрес;

• Разрешенные сервисы (audience);

• ...

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

Есть расширенное управление — это audience, когда конкретный клиент должен передать ещё один специальный параметр, из которого мы чётко понимаем, что ему можно этот scope запрашивать.

Так, атрибутов становится всё больше. Есть predefined mappers:

Всегда можно сконфигурировать новый mapper:

Пример: вы настраиваете клиента в Keycloak, создаёте пользователей, назначаете им группы и роли. Используете Group Membership, который по дефолту Keycloak вашей группы не передаёт как scope. После этого авторизуетесь пользователем и ожидаете, что информация о группах будет передана в токен. Однако в токене групп нет: Keycloak по умолчанию не включает группы в содержимое токена. Это необходимо настраивать вручную через protocol mappers.

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

Настройка mapping audience для NetBird

Обратите внимание на галочку  ^“Add to access token”. Мы хотим добавить этот mapping в содержимое access token, о котором я говорил ранее.

Осталось несколько сущностей.

Users 

Самая простая сущность — конечные пользователи, которые могут аутентифицироваться через Keycloak.

Чем удобен Keycloak?

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

У вас есть несколько инфраструктурных приложений (Grafana, Argo CD, VPN, Vault и пр.). Вы хотите, чтобы у вас был один пользователь на всех. А ещё вы у этого пользователя хотите определять, в какие группы он входит и в какие приложения может попасть. Всё это позволяет делать Keycloak.

Тут начинается не самый понятный момент, я тоже до сих пор не понял, почему сделано именно так.

• Users могут состоять в разных группах.

• Им могут назначаться роли.

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

Groups

В Keycloak возможна гибкая модель назначения прав. Пользователи могут состоять в нескольких группах, им могут назначаться роли напрямую. Группам — тоже могут назначаться роли. Кроме того, ролям могут назначать роли — роль-на-роль Также вы можете назначить создать иерархию ролей. Затем добавить роль в группу, пользователя — в группу. После этого необходимо проверить, что все соответствующие роли и группы корректно передаются в токен при авторизации.

Таким образом:

• Пользователей можно объединять в группы.

• Группам можно назначать атрибуты.

• Группам можно назначать роли.

• Пользователь будет наследовать атрибуты и роли группы.

Roles

Изначально роли логичнее, чем группы, потому что определяют некую категорию пользователя:

• Admin,

• Manager, 

• User, 

• etc...

Есть два уровня ролей:

1. Уровень клиента.

2. Уровень realm.

Роли можно создать на уровне клиента. Мы говорили про сущность клиента, внутри сущности могут быть свои роли. И этих ролей нигде, кроме этого клиента, не будет. Эти роли можно распространять на весь realm.

Роли можно назначать другим ролям, пользователям, группам (Role mappings).

Основной момент — ролевая модель предполагает, что есть встроенные роли с разрешёнными доступами внутри Keycloak, которые определяют права пользователя в самом интерфейсе Keycloak.

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

Когда мы заходим в клиента, попадаем в интерфейс:

Обратите внимание, что в клиенте можно открыть вкладку Client scopes и увидеть все существующие scopes.

Но самая главная вкладка, которой я и все мои коллеги чаще всего пользуются, это Evaluate — проверка, какой токен вам придёт. Вы выбираете пользователя, имитацию логина и токен. Здесь три вида токена: access, ID и user info. Чаще всего используется access, но иногда требования другие. Так вы тестируете, что получится.

В примере выше ко мне приехали группы NetBird, которые я вложил mapping’ами. Следом — роли как вложенные структуры. Затем — роли уровня аккаунта. У многих приложений есть завязки на то, что дефолтные роли тоже должны приходить в токене, иначе не сработает.

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

А пока подписывайтесь на телеграм-канал Hilbert Team.

Хотите прокачаться в DevOps? DevOps Conf — это место, где Terraform, Keycloak и Grafana оживают прямо на мастер-классах. Не пропустите — подробности следующего сезона скоро на официальном сайте конференции.