Эффективное управление доступом: работа с Realm

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

В предыдущей статье мы создали администратора в Keycloak, теперь перейдем к работе с Realm.

Realm в Keycloak — это изолированная область управления пользователями, ролями и клиентами, позволяющая разделять доступ и настройки между разными системами или продуктами.

В документации Keycloak в целом описаны настройки по разным вкладкам, поэтому в данном разделе вкладки описаны кратко. Описание передаёт основную суть. Возможны примеры.

Поле "Realm name"
Это уникальное наименование или идентификатор области (realm). Он используется внутри Keycloak для различения различных областей аутентификации. Наименование не должно содержать пробелов. Используется в URL, например: https://sso.example.com/auth/realms/app-realm.

Поле "Display name"
Отображаемое наименование "realm", которое будет отображаться пользователю в интерфейсе.

Поле "HTML Display name"
Отображаемое наименование с возможность использования html-тегов (например, добавление логотипа). Если задано, то имеет приоритет над Display name. Это удобно для кастомных страниц входа, где нужен более сложный дизайн.

Поле "Frontend URL"
Позволяет для "realm" задать отдельное доменное имя. Например, можно сделать такое сопоставление auth.example.com -> sso.example.com/auth/realms/myrealm. Обработкой занимается встроенный веб-сервер. То же самое можно реализовать через reverse-proxy, типа nginx, с установкой Host обработчика.

Поле "Require SSL"
Настройка политики использования HTTPS. Выбор влияет на требования к безопасности.
Опции:

• None — HTTPS не обязателен для любых запросов;
• External requests — HTTPS требуется только для внешних запросов, локальные могут идти по HTTP;
• All requests — HTTPS обязателен для всех запросов.

Поле "ACR to LoA Mapping"
Соответствует сопоставлению между ACR (Authentication Context Class Reference) — ссылкой на контекст аутентификации, и LOA (Level of Assurance) — уровень доверия (обычно числовой). Атрибут acr указывается в JWT токене, если по OpenId и в SAML Assertion, если по SAML, но уже под атрибутом AuthnContextClassRef.

В Keycloak нет встроенного системного параметра или поля с названием LOA (Level of Assurance) как отдельной сущности. LOA — это скорее концепция, которая описывает уровень уверенности в аутентификации пользователя (например, однофакторная аутентификация — LOA 1, двухфакторная — LOA 2 и т.п.). Проверка LOA и принятие решений на его основе — это ответственность клиента (приложения или бекенда).

Пример 1:
Если ACR равен urn:mace:incommon:iap:silver, то можно установить LOA = 2, а для urn:mace:incommon:iap:gold — LOA = 3.

Пример 2:
Ваша организация требует, чтобы для доступа к определённым системам использовался ACR с urn:mace:incommon:iap:gold (высокий уровень доверия). В настройках Realm вы указываете, что этот ACR отображается как LOA 3. При аутентификации пользователь, прошедший сильную аутентификацию, получит соответствующий токен с этим ACR. Система, проверяющая LOA, разрешит доступ только при LOA ≥ 3.

Как работать с числовым LOA:
1. На стороне клиента или сервера, который получает JWT, нужно:

• Считать из токена claim acr (строку).
• По своей внутренней логике (например, по таблице, совпадающей с ACR to LoA Mapping в Keycloak) преобразовать эту строку в числовой LOA.
• Принять решение об уровне доверия, доступе и т.п., основываясь на числовом LOA.

2. Если хочется, чтобы числовой LOA был прямо в JWT, можно:

• Сделать кастомный Protocol Mapper в Keycloak, который по значению acr добавит отдельный claim, например loa: 2.

Поле "User-managed access"
В случае включения пользователям разрешено управлять своими ресурсами и разрешениями, используя пользовательский интерфейс управления учетной записью.
Если включено, пользователи смогут делегировать права доступа к своим данным другим пользователям или системам.

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

Поле "Admin Permissions"
Если включено, позволяет управлять разрешениями администратора в realm. Включите, если необходимо делегировать права администрирования.

Поле "Unmanaged Attributes"
Атрибуты пользователей, не управляемые стандартной конфигурацией профиля.

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

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

Установив Only administrators can write, неуправляемые атрибуты могут управляться только через консоль администрирования и API, полезные, если вы уже определили любой пользовательский атрибут, которым пользователи могут управлять, но вы не уверены в добавлении других атрибутов, которыми следует управлять только администраторами.

Установив Only administrators can view, неуправляемые атрибуты только для чтения и доступны только через консоль администрирования и API.

Поле "Signature algorithm SAML IdP metadata"
Алгоритм подписи для метаданных SAML-поставщика. Например, RSA_SHA256. Если не указано, метаданные не будут подписаны.

Поле "Endpoints"
Ссылки OIDC/SAML, где можно получить все доступные точки входа для протоколов.

Поле "User registration"
Включить/выключить страницу регистрации. Ссылка для регистрации будет также показана на странице входа.

Поле "Forgot password"
Показывать ссылку на странице входа, по которой пользователь может нажать, если забудет свои учетные данные.

Поле "Remember Me"
Показать чекбокс на странице входа, чтобы разрешить пользователю запомнить вход в учетную запись в случае, если браузерная сессия устареет.

Поле "Email as username"
Разрешить или запретить пользователям устанавливать электронную почту в качестве имени пользователя.

Поле "Login with email"
Разрешить или запретить вход пользователям используя электронную почту.

Поле "Duplicate emails"
Позвольте нескольким пользователям иметь один и тот же адрес электронной почты.

Поле "Verify email"
Позволяет включить проверку адреса электронной почты.

Поле "Edit username"
Разрешить или запретить редактировать имя пользователя

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

Настройка конкретного внешнего вида любого пользовательского интерфейса в Keycloak с помощью тем. Также можно создать свои темы.

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

Active
Список криптографических ключей, которым подписываются новые токены и по которым могут проверяться старые. Используются протоколами аутентификации. Например, для подписывания JWT-токенов

Passive
Список криптографических ключей, по которым могут проверяться старые токены. Новые от этих ключей не выпускаются.

Disabled
Список отключенных ключей

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

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

Event Listeners (Слушатели событий)
Это компоненты, которые получают уведомления о событиях и обрабатывают их. Keycloak поставляется с двумя встроенными слушателями:

• jboss-logging — пишет события в системный лог сервера Keycloak (обычно файл сервера).
• email — отправляет уведомления по электронной почте (если настроено).
• В настройках можно выбрать, какие слушатели активировать для обработки событий. Можно реализовать собственные слушатели. Для этого нужно создать расширение на языке Java, а именно реализовать интерфейсы: EventListenerProvider - дефолтный интерфейс провайдера для перехвата всех событий в системе или EventListenerProviderFactory - интерфейс фабрики для инициализации экземпляров провайдера EventListenerProvider.

User Events Settings (Настройки пользовательских событий)
Здесь настраивается логирование событий, связанных с действиями пользователей. Основные параметры:

• Save events — включить/выключить запись пользовательских событий и сохранение их в БД;
• Event saved type — список типов событий, которые нужно логировать (например, LOGIN, LOGOUT, REGISTER и др.). Можно выбрать все или только нужные;
• Expiration — время хранения событий в базе данных (например, 30 дней). По истечении события автоматически удаляются;
• Clear user events — кнопка для ручной очистки всех записей пользовательских событий.

Admin Events Settings (Настройки административных событий)
Отвечает за логирование действий администраторов и операторов, которые управляют realm, пользователями и настройками. Основные параметры:

• Save events — включить/выключить запись пользовательских событий и сохранение их в БД;
• Expiration — срок хранения административных событий;
• Include Representation — если включено, в логах будет сохраняться JSON-представление объекта, с которым производилось действие (например, данные пользователя при обновлении). Это полезно для аудита, но увеличивает размер логов;
• Clear admin events — кнопка для ручной очистки.

Настройки позволяют установить язык интерфейса.

Настройки, направленные на повышение безопасности, защита от атак и укрепление безопасности HTTP-заголовков. Она помогает защитить систему от распространённых угроз, таких как перебор паролей (brute force), а также улучшить безопасность взаимодействия браузера с сервером. Включает в себя раздел "Headers" и "Brute force detection".

Раздел "Headers" позволяет настроить HTTP-заголовки, которые помогают защитить браузер и пользователя от различных атак (например, clickjacking, XSS, MIME sniffing).

Разделе "Brute force detection" отвечает за защиту от атак перебора паролей и учётных записей. Позволяет ограничить количество неудачных попыток входа, чтобы предотвратить взлом путём угадывания пароля.

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

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

Вкладка Client Policies (Политики клиентов) позволяет создавать и управлять набором правил и ограничений, которые применяются к клиентам (applications) в рамках realm. Это мощный инструмент для централизованного контроля поведения клиентов, например, для управления настройками безопасности, проверки конфигураций клиентов, ограничения типов клиентов и т.д. Например, можно создать политики такие, при которой нельзя будет создать клиента, если не выполняются какие-то условия в настройках клиента.

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

Во вкладке User Registration в настройках realm Keycloak настраиваются параметры, связанные с процессом регистрации новых пользователей и их начальным состоянием в системе. Это важный раздел для управления тем, как пользователи создаются и какие права или принадлежность к группам они получают по умолчанию.

Необходимо перейти на вкладку "Manage realms", чтобы создать новый "realm".

Нажимаем на кнопку "Create realm" и переходим в модальное окно для создания "realm".

На рисунке показано модальное окно для создания "realm". Можно создать "realm" из готовой конфигурации, которая была экспортирована, если такой конфигурации нет, то ничего вводить не нужно в поле "Resource file". Указываем наименование "realm", например, "app-realm" и нажимаем кнопку "Create". Рекомендуется добавлять постфикс «-realm» для большей информативности. Ползунок "Enabled" необходим для того, если вы хотите отключить "realm" и не использовать его.

После создания "realm" вы сразу переключитесь на него. В "realm" master вы ничего создавать не должны, так как этот "realm" для администратора.

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

На рисунке показана возможность выгрузки конфигурации настроенного "realm" с клиентами, группами и другими параметрами. Необходимо перейти на вкладку "Realm settings" и в выпадающем меню "Action" выбрать пункт для экспорта "Partional export". Появится модальное окно, как показано на рисунке.

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

Создание роли в realm. Созданные роли будут доступны для всех клиентов.

На рисунках показан процесс, как создается роль.

На рисунке есть вкладки для дополнительной настройки роли.

Details
Здесь задаются основные параметры роли: наименование и описание.

Associated roles
Здесь можно управлять составными ролями. Например, добавить в текущую роль какую-то другую роль. Получается некая иерархия ролей.

Attributes
В этом разделе можно назначать произвольные пары ключ-значение, которые служат дополнительной информацией о роли. Например, завести ключ level и указать уровень доступа сотрудника.

Users in role
Здесь отображается список пользователей, которым назначена данная роль.

Admin events
Этот раздел показывает журнал изменений, связанных с ролью.

Наша команда уже более пяти лет занимается реализацией проектов на Java и усилением команд по направлениям

• DevOps;
• Java разработка;
• Тестирование.

За время существования компании, мы принимали участие в работе над более чем 100 проектами различного объема и длительности.

Если перед вами стоят вызовы, при которых вам может пригодится наша экспертиза, просто напишите нам,

• client@softwarecats.dev,
• https://t.me/alex_zarubin,
• или через любую форму на сайте.

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