Профиль аутентификации

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

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

Правила, зависящие от метода запроса, заголовка, адреса клиента или от того, кто вошёл, задаются политиками и сценариями — см. Аутентификация в политиках и сценариях.

Вход через внешний сервис идентификации настраивается отдельно: адреса и ключи провайдера находятся в провайдере аутентификации, а порядок настройки — в статье Вход через внешний провайдер (OIDC).

Три блока настроек профиля

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

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

Как модули стыкуются

Модули разных блоков связывает роль учётных данных: Пароль, Bearer токен, Идентификационный токен, Готовая личность и Ничего. Модуль приёма роль даёт, модуль проверки — принимает, модуль передачи — использует. Окно выбора модулей группирует их по ролям с такими подписями.

Роль Готовая личность особая: её не нужно настраивать в блоке приёма, достаточно того, что аутентификация прошла. Поэтому header сочетается с любым способом приёма, а basic в блоке передачи требует именно пароля.

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

Окно выбора модулей заранее показывает, что с чем стыкуется, и убирает несовместимые сочетания. Недоступный модуль не удаляется, а снабжается пояснением причины — по ней видно, какой модуль мешает.

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

Приём учётных данных

basic — заголовок Authorization: Basic

Модуль без настроек. Пароль приходит в каждом запросе, передавать его в следующих запросах не нужно, поэтому сессии такому профилю не нужны. В ответ на требование WWW-Authenticate браузер покажет своё окно входа — это отдельный путь входа, а не страница входа системы 5А.

form — страница входа

Человек вводит логин и пароль один раз на HTML-странице. Модуль form работает только с сессией: без включённых сессий профиль не сохранится.

Поля, отмеченные , обязательны для заполнения.

• Заголовок страницы входа — текст в верхней части формы. Если поле пустое, берётся значение realm, а без него выводится «Вход».
• Адрес после выхода — адрес, на который клиент переходит после выхода. Если поле пустое, клиент переходит на страницу входа.
• Путь входа и Путь выхода — служебные адреса сервиса, на которых система 5А показывает страницу входа и обрабатывает выход. Если поля пустые, используются /auth/login и /auth/logout.
• Своя HTML-страница входа — разметка формы входа. Если поле пустое, используется встроенная страница.

Своя HTML-страница входа пишется, когда вход на сервис должен выглядеть как часть приложения. Балансировщик отдаёт эту разметку по пути входа, поэтому достаточно формы с полями username и password:

<form method="post">
  <input name="username">
  <input name="password" type="password">
  <button>Войти</button>
</form>

Три особенности такой формы:

• Форма без action отправляет данные на адрес самой страницы — это путь входа вместе с адресом возврата. С жёстко прописанным action="/auth/login" адрес возврата теряется, и после входа человек попадёт на корень сервиса.
• Скрытое поле с токеном против CSRF балансировщик добавляет в каждую форму сам.
• Разметка без тега <form> не принимается: такой странице нечем отправить токен, и вход с неё был бы отвергнут.

Кому нужно больше власти над разметкой, доступны подстановки:

Значения экранируются при подстановке. Есть в разметке {{csrf}} — скрытое поле само не добавляется, токен ставит автор. Незнакомые {{имена}} остаются в разметке как есть.

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

jwt — токен JWT

Модуль ищет токен в трёх источниках, каждый включается отдельным переключателем: Cookie, Заголовок и Параметр запроса. Имя источника задаётся в поле под его переключателем.

• Имя cookie — имя cookie, в которой лежит токен, например access_token. Обязательно, когда включён переключатель Cookie.
• Имя заголовка — имя заголовка, в котором лежит токен. Если поле пустое, используется Authorization. Обязательно, когда включён переключатель Заголовок.
• Имя параметра — имя параметра запроса, в котором лежит токен, например token. Обязательно, когда включён переключатель Параметр запроса.

Ни один источник не задан — токен берётся из заголовка Authorization по схеме Bearer. Заданный источник заменяет это умолчание, а не дополняет его: указав cookie, вы объявляете, что в этой установке токены лежат в cookie, и заголовок Authorization больше не просматривается. Чтобы принимать токен несколькими способами сразу, заполните нужные поля — источники просматриваются в фиксированном порядке: cookie, параметр запроса, заголовок. В заголовке префикс Bearer необязателен: он отбрасывается в любом случае.

Проверка

local_db — локальная база пользователей

• Набор пользователей — набор, пароли из которого сверяются. Рядом показывается число учётных записей в наборе, а ссылка Создать набор и кнопка Открыть набор позволяют завести набор или открыть его, не покидая профиль.

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

Набор, привязанный к профилю, в котором нет local_db, тоже считается ошибкой: профиль сообщит, что набор привязан, но его никто не читает.

jwt — подпись JWT

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

• Источник ключа — откуда балансировщик берёт ключ проверки подписи. Значение Общий секрет подходит для токенов, подписанных тем же секретом; Открытый ключ провайдера (PEM) — для ключа, который вставляется в профиль; Набор ключей провайдера (JWKS) — для провайдера, который сам отдаёт свои ключи по адресу.
• Общий секрет — секрет, которым провайдер подписывает токены. Поле показывается только для источника Общий секрет. После сохранения вместо секрета выводится «Секрет сохранен»; чтобы сменить секрет, введите новый.
• Открытый ключ провайдера (PEM) — открытый ключ текстом или файлом. Принимаются обе формы, которые выдают провайдеры: BEGIN PUBLIC KEY и BEGIN RSA PUBLIC KEY. Ключ должен быть RSA или EC: RSA даёт подпись RS256, EC — ES256, ES384 или ES512 по кривой. Поле показывается только для источника Открытый ключ провайдера (PEM).
• Адрес набора ключей провайдера (JWKS) — адрес, с которого балансировщик забирает ключи, например https://idp.example.com/.well-known/jwks.json. Обязателен для этого источника. Это единственный режим, который переживает ротацию ключей у провайдера без правки профиля; нужен сетевой доступ с балансировщиков до провайдера.

Параметры обращений к провайдеру задаются только для источника Набор ключей провайдера (JWKS).

• Кэш ключей, с — как долго загруженный ключ хранится в памяти балансировщика. Если поле пустое или равно 0, применяется 300.

• Повторы — сколько раз повторить неудачный запрос ключей, от 0 до 5. Если поле пустое или равно 0, повторы не выполняются. Повторы идут подряд, без пауз, и всё это время запрос клиента ожидает ответа.

• Таймаут соединения, мс — сколько ждать установления соединения с провайдером. Если поле пустое или равно 0, применяется 2000.

• Таймаут отправки, мс — сколько ждать отправки запроса ключей. Если поле пустое или равно 0, применяется 2000.

• Таймаут ответа, мс — сколько ждать ответа с ключами. Если поле пустое или равно 0, применяется 5000.

• Проверка TLS-сертификата — Проверять или Не проверять. По умолчанию — Проверять. Значение Не проверять нужно провайдеру с самоподписанным или внутренним сертификатом: с проверкой соединение с ним не установится. С Не проверять балансировщик принимает любой сертификат, поэтому значение выбирают только при отсутствии пути постороннему к провайдеру.

• Имя сервера (SNI) — имя для TLS-рукопожатия с провайдером. Если поле пустое, имя берётся из адреса.

• Алгоритмы — какими алгоритмами принимается подпись. Если алгоритмы не выбраны, они выводятся из ключа: HS256 для общего секрета, RS256 для набора ключей, алгоритм по самому ключу для открытого. Допустимые сочетания «источник ключа → алгоритмы» система показывает в списке; выбрать алгоритм, несовместимый с ключом, нельзя. Список берётся из профиля, а не из поля alg самого токена, и так будет всегда: доверять полю alg нельзя.

Утверждения токена — именованные поля внутри токена, которые балансировщик читает, чтобы получить имя пользователя, группы и атрибуты. Имя утверждения может вести вглубь токена: точка разделяет уровни вложенности. Это и есть способ работать с провайдерами, которые не кладут роли в плоское поле:

Имя утверждения сначала ищется целиком, как есть, и только если такого утверждения нет — трактуется как путь. Поэтому адреса-имена находятся сами собой, а realm_access.roles работает как путь. Если утверждение с точками в имени и вложенная структура совпадут, побеждает плоское.

Точку внутри уровня экранируйте обратной косой чертой — это нужно, когда идентификатор клиента Keycloak сам содержит точки. В JSON косая черта удваивается: "groups": "resource_access.com\\.example\\.client.roles".

• Утверждение с именем пользователя — утверждение, значение которого становится именем клиента. Если поле пустое, используется sub.
• Утверждение со списком групп — утверждение со списком групп, по которому работают разрешённые группы в привязке. Если поле пустое, используется groups. Значение может быть и списком, и одной строкой через пробел или запятую.

Атрибуты из утверждений — соответствия «атрибут → утверждение», по которым балансировщик наполняет атрибуты личности.

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

• Утверждение токена — утверждение, значение которого попадёт в атрибут. Записывается так же, как имя пользователя, вглубь токена через точку.

• Издатель (iss) — ожидаемое значение утверждения iss. Если поле пустое, iss не проверяется.

• Получатель (aud) — ожидаемое значение утверждения aud. Если поле пустое, aud не проверяется.

• Допустимый разброс часов, с — на сколько секунд расхождение часов балансировщика и провайдера считается допустимым при проверке сроков токена. Если поле пустое, применяется 60.

• Требовать exp — проверять ли срок действия токена. По умолчанию отметка стоит. Снимать её следует только для бессрочных токенов: их отзыв возможен лишь через смену ключа подписи у всего профиля.

Передача на бэкенд

Модули передачи решают, что именно клиентский сервер увидит вместо исходных учётных данных. Ни один из них не выбран — приложение не получит ни заголовка Authorization, ни идентификационных заголовков.

header — личность бэкенду заголовками

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

basic — пароль бэкенду заголовком Authorization: Basic

Приложение за балансировщиком продолжает видеть привычный Authorization: Basic и может проверять пароль само. Подходит для приложений, написанных под HTTP Basic. Модуль требует, чтобы учётные данные пришли именно паролем, поэтому в блоке приёма нужен basic.

bearer — токен бэкенду заголовком Authorization

Токен передаётся на клиентский сервер в исходном виде: балансировщик отправляет тот же токен, который прислал клиент и который проверил блок Проверка. Модуль ничего не выпускает и не подписывает.

• Имя заголовка — заголовок, в котором токен передаётся на клиентский сервер. Если поле пустое, используется Authorization.
• Префикс токена — как токен будет оформлен в заголовке: Bearer (по умолчанию) или Свой префикс.
• Свой префикс — текст, который ставится перед токеном. Поле показывается только для значения Свой префикс. Если поле пустое, токен передаётся без префикса, одним значением заголовка.

Сессии

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

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

• Имя cookie — под этим именем сессия хранится в браузере. Если поле пустое, имя производится от профиля, чтобы два профиля на одном домене не затирали сессии друг друга.
• Путь cookie — путь, на который cookie действует. Должен начинаться с /. Если поле пустое, используется /.
• Домен cookie — хост, на который cookie действует. Если поле пустое, используется точный хост запроса.
• Same site — атрибут SameSite cookie: lax, strict или none. Если поле пустое, используется lax.

Cookie сессии всегда недоступна скриптам страницы, а признак Secure ей ставится только тогда, когда каждый сервис, где работает профиль, слушает по HTTPS. Если профиль обслуживает и сервис с обычным HTTP, cookie останется без Secure.

• Таймаут простоя, с — через сколько секунд без запросов сессия считается неактивной. Если поле пустое или равно 0, таймаут отключается.
• Таймаут продления, с — через сколько секунд активности сессия продлевается. Если поле пустое или равно 0, таймаут отключается.
• Абсолютный таймаут, с — сколько секунд сессия живёт с момента входа, сколько бы активности ни было. Если поле пустое или равно 0, таймаут отключается.
• Размер хранилища, МБ — сколько памяти отводится под сессии на балансировщик, от 0 до 4096. Если поле пустое или равно 0, применяется 10 МБ, а для профиля с модулем oidc — 64 МБ. Место занимается по мере записи сессий, но не освобождается: пик числа одновременных сессий удерживает память до перезапуска балансировщика.
• Задержка выхода, с — сколько секунд выданная сессия ещё держится после выхода. Если поле пустое, применяется 5. Значение 0 выключает кеш: выход срабатывает мгновенно, но каждый запрос клиента обращается к хранилищу сессий.

Задайте хотя бы один из трёх таймаутов. Если не задан ни один, профиль сохраняется со значениями 900, 3600 и 86400 секунд: вечную сессию создать нельзя.

Размер хранилища выбирают по числу одновременных сессий. Ориентир — 20 тысяч сессий на 10 МБ у профилей без oidc: одна сессия занимает около 512 байт. Сессия с ID-токеном, которая появляется у модуля oidc, в 4–8 раз крупнее, поэтому умолчание для таких профилей и выше — 64 МБ.

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

Задержка выхода отмеряет, сколько балансировщик помнит уже проверенные сессии, чтобы не сверять их на каждом запросе. Запрос на выход попадает на один рабочий процесс, поэтому выход прекращает действовать не сразу, а через указанное число секунд. Обратная сторона: после выхода клиент ещё секунд 5 может пользоваться прежней сессией. Увеличьте задержку, чтобы сократить число обращений к хранилищу на нагруженном сервисе, уменьшите, чтобы выход действовал быстрее.

Переключатель Постоянная cookie добавляет ещё один срок жизни: клиенту выдаётся вторая cookie, которая переживает перезапуск браузера. На два таймаута ниже это правило не распространяется: у постоянной cookie своя пара значений, и 0 в ней означает умолчание.

• Перевыпуск постоянной cookie, с — как часто продлевать постоянную cookie. Если поле пустое или равно 0, применяется неделя.
• Срок жизни постоянной cookie, с — сколько постоянная cookie живёт. Если поле пустое или равно 0, применяется 30 дней.

Дополнительно

Идентификационные заголовки. По умолчанию профиль затирает идентификационные заголовки всегда, даже когда модуль передачи не выбран. Так клиент не может подделать своё имя, прислав X-Auth-User.

• Пользователь — заголовок, в котором имя пользователя передаётся на клиентский сервер. Если поле пустое, используется X-Auth-User.
• Группы — заголовок, в котором группы передаются на клиентский сервер одной строкой через запятую. Если поле пустое, используется X-Auth-Groups.

Атрибуты — соответствия «атрибут → заголовок». Атрибут передаётся на клиентский сервер только при полном совпадении имени атрибута и заголовка, поэтому в наборе пользователей, в утверждениях токена и здесь имена должны совпадать.

• Атрибут — имя атрибута личности.
• Заголовок — заголовок, в который атрибут уйдёт на клиентский сервер.

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

• Способ — вид ответа: Только код ответа, Перенаправление или Своя страница. Значение по умолчанию — Только код ответа с кодом 403.
• Код ответа — код, который получает клиент. Показывается для способа Только код ответа. Если поле пустое или равно 0, применяется 403, иначе значение должно лежать в пределах от 100 до 599.
• Адрес перенаправления — адрес, на который клиент переходит вместо отказа. Показывается для способа Перенаправление.
• Своя страница отказа — разметка страницы, которую получит клиент. Показывается для способа Своя страница.
• Тип содержимого — заголовок Content-Type страницы отказа. Показывается для способа Своя страница вместе с ней. Если поле пустое, используется text/html; charset=utf-8.

Прочее.

• Realm — значение заголовка WWW-Authenticate (часть realm=), по которому браузер отличает одно приложение от другого. Задавайте разные значения на разных сервисах: иначе браузер предложит логин одного сервиса для другого. Поле требует модуля приёма, который отвечает заголовком WWW-Authenticate: иначе показать эту строку будет негде.
• Кэш успешной проверки, с — сколько секунд помнить результат успешной проверки. Если поле пустое, профилю, который принимает пароль модулем basic и сверяет его модулем local_db, система сама подставляет 30 секунд: такой пароль приходит в каждом запросе, а кеш убирает повторные хеширования. Остальным профилям кеш не включается. Значение 0 выключает кеш.
• Не затирать заголовки личности — оставлять X-Auth-User и X-Auth-Groups на путях, где профиль не применяется, в том виде, в каком их прислал клиент.
• Не отбирать заголовок Authorization клиента — передавать на клиентский сервер заголовок Authorization, который прислал клиент. По умолчанию балансировщик его удаляет, если профиль сам не ставит Authorization модулем передачи basic или bearer.

Порядок настройки

1. Откройте Главная → <Кластер> → Аутентификация → Профили и нажмите Добавить профиль.
2. Задайте Название и Описание — см. Название и описание.
3. В блоке Приём учётных данных нажмите Добавить модуль и выберите, как балансировщик получит учётные данные.
4. В блоке Проверка добавьте модуль, который эти данные проверит. Для пароля по логину это local_db с указанием набора пользователей, для токена, который клиент присылает сам, — jwt с ключом этого провайдера, для входа через внешнюю систему идентификации — oidc.
5. В блоке Передача на бэкенд выберите, что получит клиентский сервер. Если ничего не выбрано, приложение не получит ни имени пользователя, ни групп.
6. При необходимости включите сессии на вкладке Сессии и задайте имена идентификационных заголовков на вкладке Дополнительно.
7. Нажмите Сохранить, затем привяжите профиль к сервису — см. Аутентификация и авторизация сервиса.

Пока раздел Связанные сервисы на вкладке Общие настройки пуст, профиль не привязан ни к одной конфигурации и ни на что не действует.

Правила, зависящие от метода запроса, заголовка, адреса клиента или от того, кто вошёл, в профиль не помещаются: их задают политикой или сценарием — см. Аутентификация в политиках и сценариях.

Удаление профиля

Профиль, привязанный к сервису, удалить нельзя. То же — если на профиль ссылается сценарий или политика.

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

Проверка

1. Привяжите профиль к сервису и откройте защищённый путь в браузере без учётных данных — ожидается отказ, а не страница приложения.
2. Повторите запрос с корректными учётными данными — ожидается штатная страница приложения.
3. Посмотрите заголовки запроса, переданного на клиентский сервер: при модуле header там должны быть X-Auth-User и X-Auth-Groups.

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