Провайдеры аутентификации

Провайдер аутентификации — внешняя система входа (например, Keycloak, Entra ID, ADFS, GitLab). Его создают один раз, а профили с модулем oidc ссылаются на него.

В провайдере хранится то, что одинаково для всех приложений кластера: адреса, свойства, параметры подписи ID-токена и настройки подключения. Клиент и всё, что относится к конкретному приложению, задаются в профиле аутентификации.

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

Где настраивается

Главная → <Кластер> → Аутентификация → Провайдеры, кнопка Добавить провайдера. Название и описание — общие поля, см. Название и описание.

Провайдер создаётся с типом OpenID Connect. После создания тип изменить нельзя: поле заблокировано. Тип другой в системе пока нет, поэтому значение выбирается только для явности.

Получение сведений о провайдере

Главное поле провайдера — Адрес провайдера (issuer). Это базовый адрес внешней системы, по которому балансировщик получает метаданные и сверяет, что ID-токен выдан именно этим провайдером. Значение вида https://sso.example.ru/realms/employees. Укажите адрес в точности как в метаданных провайдера, включая завершающий слэш, если он там присутствует.

Кнопка Получить сведения выполняет запрос метаданных провайдера по адресу .well-known/openid-configuration и подставляет в форму:

адреса эндпоинтов авторизации, обмена кода на токен, набора ключей JWKS и, при наличии, эндпоинта завершения сессии;
свойства провайдера: умеемые алгоритмы подписи, способы приёма секрета клиента, поддержку параметра iss.

Кнопка доступна, когда Адрес провайдера (issuer) заполнен. Ничего не сохраняется до нажатия Сохранить — полученные сведения можно поправить вручную, а кнопку нажать повторно.

⚠️

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

Основные адреса

Адреса задаются полными URL с указанием схемы: http:// или https://.

Все поля, отмеченные , являются обязательными для заполнения.

Тип провайдера — тип внешней системы входа. Значение OpenID Connect, изменить его после создания нельзя.
Страница входа (authorization) — адрес, на который балансировщик перенаправляет браузер клиента. Заполняется из метаданных кнопкой Получить сведения.
Обмен кода на токен (token) — адрес, по которому балансировщик меняет полученный от провайдера код на ID-токен. Заполняется из метаданных кнопкой Получить сведения.
Ключи подписи (JWKS) — адрес набора ключей подписи ID-токена. Заполняется из метаданных кнопкой Получить сведения. Балансировщик берёт ключи по этому адресу и переживает ротацию ключей у провайдера без правки настроек.
Выход у провайдера (end session) — адрес завершения сессии на провайдере. Заполняется из метаданных, если провайдер объявил этот эндпоинт.

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

Свойства провайдера

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

Умеет подписывать ID-токены — алгоритмы подписи, которые провайдер объявляет в метаданных. Служит ориентиром при выборе Разрешенные алгоритмы подписи.
Принимает секрет клиента — способы передачи секрета клиента, поддерживаемые провайдером: в заголовке запроса или в теле. Служит ориентиром при заполнении Способ передачи секрета в профиле.
Возвращает ISS в ответе входа — поддерживает ли провайдер передачу параметра iss в ответе авторизации (RFC 9207). Балансировщик сверяет его с Адрес провайдера (issuer), когда проверка включена.

Подпись ID-токена

Разрешенные алгоритмы подписи — алгоритмы, которыми балансировщик принимает подпись ID-токена. Список берётся у провайдера: если тот объявил RS256, выбирается только он. Провайдер без RS256 даёт свой набор, из которого балансировщик оставляет те алгоритмы, которые может проверить.

Симметричные алгоритмы HS256, HS384, HS512 в списке нет: подпись ими проверяется общим секретом, а у провайдера OIDC секрет клиента для этого не предназначен. В списке только RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512.

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

Допуск расхождения часов, с — на сколько секунд расхождение часов балансировщика и провайдера считается допустимым при проверке сроков действия ID-токена (exp, nbf). Если поле пустое, применяется 60. Увеличьте, если у провайдера заметно расходятся часы: без запаса ID-токены будут отвергаться как просроченные.

Подключение к провайдеру

Настройки походов балансировщика к провайдеру: получение ключей JWKS и обмен кода на ID-токен.

Проверка сертификата провайдера — проверять ли TLS-сертификат провайдера при походе за ключами и обмене кода на токен: Проверять или Не проверять. По умолчанию — Не проверять.

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

⚠️

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

Имя сервера (SNI) — имя хоста для TLS-рукопожатия. Если поле пустое, имя берётся из адреса, по которому балансировщик обращается к провайдеру. Задавайте его, когда у провайдера несколько адресов, а сертификат выпущен только на один.
Кэш ключей, с — как долго балансировщик хранит загруженные ключи в памяти. Если поле пустое или равно 0, применяется 300.

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

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

Запрос обмена кода на токен повторов не имеет: код одноразовый, повторная отправка вернёт ошибку. При таймауте клиент начинает вход заново.

Удаление провайдера

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

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

Что проверить

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

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

Аутентификация и авторизация сервиса Вход через внешний провайдер (OIDC)