Подключить внешний OIDC-провайдер

Платформа “Штурвал” поддерживает подключение Keycloak и Blitz как внешних OIDC-провайдеров.

Когда в кластере управления работают такие сервисы, как Kubeflow, ArgoCD и Grafana, при изменении OIDC-провайдера изменения в ssc не потребуются.

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

Подготовка к настройке подключения в платформе

Требования к Access Token внешнего OIDC-провайдера

Для корректной интеграции с платформой “Штурвал” на стороне внешнего OIDC-провайдера (Blitz, Keycloak) в access_token должны быть настроены поля:

Claim в токене	Значение	Источник значения
`aud`	Идентификатор клиента, для которого выпущен токен. Должен соответствовать `CLIENT_ID`, например, `backend`.	Настройки клиента в OIDC-провайдере
`sub`	Уникальное имя пользователя.	Например, `sAMAccountName` пользователя в AD
`preferred_username`	Имя учётной записи пользователя.	Например, `sAMAccountName` пользователя в AD
`name`	Отображаемое имя пользователя.	Например, `displayName` или `sAMAccountName` пользователя в AD
`email`	Email пользователя.	Например, `mail` пользователя в AD
`claims`	Список групп, в которые входит пользователь.	Например, `claims` в AD
`iss`	Issuer URL внешнего OIDC-провайдера.	Настройки OIDC-провайдера
`jti`, `exp`, `iat`	Обязательные claim токена. Должны присутствовать и формироваться в соответствии с RFC 7519.	Настройки OIDC-провайдера

Для Keycloak в маппере групп клиента (Group Membership) параметр Full group path должен быть выключен (Off). Если оставить его включённым, в токене вместо имени группы, например, developers, придёт полный путь /parent/developers, и интеграция завершится ошибкой.

При настройке интеграции в GUI можно сопоставить поля access_token внешнего OIDC-провайдера с полями, которые ожидает платформа. Используйте эту настройку, если в токене вашего OIDC-провайдера поля называются не aud, sub, preferred_username, name, email, а иначе.

Корневой CA сертификат внешнего OIDC-провайдера

Если необходимо устанавливать TLS соединение при аутентификации, получите корневой CA сертификат внешнего OIDC-провайдера, закодированный в base64. Вы можете запросить сертификат у администратора OIDC-провайдера или получить его способом, приведенным далее.

В интерфейсе командной строки подключитесь по SSH к OIDC-провайдеру и получите сертификат, закодированный в base64.

Команда — иллюстрация

cat <путь до файла сертификата внешнего OIDC-провайдера> | base64

Например, путь до файла сертификата внешнего OIDC-провайдера: /usr/share/keycloak/cert/keycloak.shturval.crt.

Пример ответа

LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tClvRgdC10YDRgtC40YTQuNC60LDRgiDQstC90LXRiNC90LXQs9C+INGB0LXRgNCy0LjRgdCwINCw0YPRgtC10L3RgtC40YTQuNC60LDRhtC40LhdCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=

Подключение внешнего OIDC-провайдера в платформе

Вы можете настроить интеграцию с внешним OIDC-провайдером в графическом интерфейсе (GUI) или в интерфейсе командной строки (CLI), создав Secret auth-provider в неймспейсе shturval-backend.

Для интеграции платформы с новым OIDC-провайдером рекомендуется использовать настройки в GUI.

Если интеграция с OIDC-провайдером настроена через ssc Модуля управления аутентификацией (shturval-auth), редактирование в GUI будет недоступно.

В графическом интерфейсе

Как перейти к настройке интеграции

В платформе перейдите на страницу Интеграция с OIDC провайдером одним из способов:
- В платформе откройте раздел Управление доступом → страница Интеграция с OIDC провайдером;
- На вкладке Платформа из блока Доступ к платформе перейдите по кнопке Интеграция с OIDC провайдером.

На вкладке Платформа в строке Провайдер аутентификации отображается статус подключения провайдера:

если подключен внутренний провайдер, отображается Внутренний;
если подключен внешний OIDC-провайдер, отображается его имя. Нажатие на имя открывает страницу просмотра Интеграция с OIDC провайдером.

Шаг 1. Заполните параметры подключения

На странице Интеграция с OIDC провайдером заполните поля:

Параметры блока «Конфигурация провайдера»

Поле в интерфейсе	Описание
Имя провайдера	Имя конфигурации провайдера. Отображается при аутентификации в графическом интерфейсе. Доступно к редактированию после сохранения настроек интеграции.
Отображать внутренний провайдер аутентификации	Определяет, будет ли внутренний провайдер доступен для аутентификации при подключении внешнего OIDC-провайдера. По умолчанию выбрано Да. Если не удалось проверить подключение по ID и секрету клиента, установленное значение Нет будет проигнорировано.
URL эмитента OIDC	URL issuer внешнего OIDC-провайдера. Например, для Keycloak, Issuer находится в разделе Identity providers в блоке OpenID Connect settings.
ID клиента OIDC	Идентификатор клиента OIDC-провайдера.
Секрет клиента	Секрет клиента внешнего OIDC-провайдера. Например, для Keycloak clientSecret находится в разделе Clients на странице клиента, вкладка Credentials в поле Client Secret
Метод PKCE	Выберите метод, если в провайдере включен Proof Key for Code Exchange (PKCE) Challenge Method. Доступные варианты: `plain` или `S256`. По умолчанию метод не выбран.
Включить верификацию CA	Определяет, нужно ли проверять CA-сертификат OIDC-провайдера. По умолчанию выбрано Нет. При включении верификации доступна загрузка корневого СА сертификата
Корневой CA сертификат	Закодированный в base64 корневой CA сертификат внешнего OIDC-провайдера

Шаг 2. Проверьте подключение

Когда все обязательные поля заполнены, нажмите Проверить подключение. Платформа проверит доступность well-known конфигурации OIDC-провайдера и endpoints аутентификации, необходимых для корректной работы внешней аутентификации в Штурвале.

Если проверка выполнена успешно, станут доступны:

поля для сопоставления полей Access Token OIDC-провайдера.
переключатель режима работы OIDC-провайдера в платформе.

В случае если при проверке подключения не удалось проверить client.clientId и client.clientSecret, то вернется предупреждение. В этом случае при подключении внешнего OIDC-провайдера внутренний провайдер останется доступен для безопасного входа в систему.

Шаг 3. Маппинг Access Token OIDC-провайдера

После успешной проверки подключения доступно задать Сопоставление полей Access Token OIDC-провайдера. Заполните параметры, только если в Access Token OIDC-провайдера используются названия claim, отличные от названий: sub, claims, preferred_username, aud, name, email.

Укажите в полях имена claim access_token OIDC-провайдера. Например, если группы пользователя передаются не в claim claims, а в claim groups, в поле Claims укажите groups.

Поле в интерфейсе	Claim по умолчанию	Описание	Что платформа ожидает получить	Пример
Sub	`sub`	Наименование поля с уникальным именем пользователя (UserID).	Уникальное имя пользователя	`sAMAccountName`
Claims	`claims`	Наименование поля с группами пользователя.	Список групп AD пользователя
Preferred Username	`preferred_username`	Наименование поля с именем учётной записи для входа (логин).	Логин пользователя	`sAMAccountName`
Aud	`aud`	Наименование поля с ID клиента.	`CLIENT_ID` сервиса	`backend`
Name	`name`	Наименование поля с полным именем пользователя.	Отображаемое имя пользователя	`displayName` или `sAMAccountName`
Email	`email`	Наименование поля с email-адресом пользователя с UPN-суффиксом и `@`.	Email пользователя	`mail`

Шаг 4. Включите и сохраните конфигурацию

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

Просмотр и редактирование настроек интеграции

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

Если в платформе настроено подключение OIDC-провайдера через ssc Модуля управления аутентификацией (shturval-auth), редактирование в интерфейсе недоступно.

В интерфейсе командной строки

Конфигурация внешнего OIDC-провайдера

До подключения внешнего OIDC-провайдера в платформе “Штурвал” подготовьте конфигурацию согласно примеру, использовав ваши значения параметров.

Пример конфигурации внешнего OIDC-провайдера

{
  "name": "<ваше значение параметра>",
  "issuerUrl": "<ваше значение параметра>",
  "codeVerifyMethod": "<ваше значение параметра>",
  "client": {
    "clientId": "<ваше значение параметра>",
    "clientSecret": "<ваше значение параметра>"
  },
  "insecureSkipVerify": "<ваше значение параметра>",
  "caBundle": "<ваше значение параметра>",
  "tokenClaimMapping": {
    "sub": "<ваше значение параметра>",
    "name": "<ваше значение параметра>",
    "email": "<ваше значение параметра>",
    "preferredUsername": "<ваше значение параметра>",
    "claims": "<ваше значение параметра>",
    "aud": "<ваше значение параметра>"
  }

Параметр	Описание	Пример
`name`	Имя конфигурации (задайте любое)	keycloak
`issuerUrl`	URL issuer внешнего OIDC-провайдера. Например, для Keycloak, Issuer находится в разделе Identity providers в блоке OpenID Connect settings	https://keycloak.ip-XX-XX-XX-XX.shturval.link/realms/shturval
`codeVerifyMethod`	Если в Keycloak включен Proof Key for Code Exchange Code (PKCE) Challenge Method, укажите Challenge Method в параметре `codeVerifyMethod`. Поддерживаются только `S256` и `plain`. Когда Challenge Method не включен, оставьте `codeVerifyMethod` пустым или не указывайте его.	S256
`client.clientId`	ID клиента внешнего OIDC-провайдера	shturval_unikeycloak_backend_client_id
`client.clientSecret`	Секрет клиента внешнего OIDC-провайдера. Например, для Keycloak clientSecret находится в разделе Clients на странице клиента, вкладка Credentials в поле Client Secret	HG0rxJMKopmAGSasDxDtkJYQH
`insecureSkipVerify`	Устанавливать ли tls-соединение	true
`caBundle`	Закодированный в base64 корневой CA сертификат внешнего OIDC-провайдера. Добавьте в `caBundle` полученный сертификат, закодированный в base64.	`*`
`tokenClaimMapping`	Список соответствий между claim в `access_token` внешнего OIDC-провайдера и полями, которые ожидает платформа. Укажите значения, если в токене провайдера claim называются иначе	-
`tokenClaimMapping.sub`	Claim с уникальным идентификатором пользователя	sub
`tokenClaimMapping.name`	Claim с отображаемым именем пользователя	name
`tokenClaimMapping.email`	Claim с email-адресом пользователя	email
`tokenClaimMapping.preferredUsername`	Claim с именем учётной записи пользователя	sub
`tokenClaimMapping.claims`	Claim со списком групп пользователя	groups
`tokenClaimMapping.aud`	Claim с идентификатором клиента, для которого выпущен токен	aud

*LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tClvRgdC10YDRgtC40YTQuNC60LDRgiDQstC90LXRiNC90LXQs9C+INGB0LXRgNCy0LjRgdCwINCw0YPRgtC10L3RgtC40YTQuNC60LDRhtC40LhdCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=

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

Скриншот интерфейса платформы

Скопируйте конфигурацию, подготовленную на предыдущем шаге. При создании Secret через stringData кодировать конфигурацию в base64 не требуется.
Загрузите и сохраните действующие kubeconfigs кластеров (клиентских кластеров, кластера управления). Kubeconfig потребуется для подключения к кластеру из консоли.

Далее создайте Secret auth-provider в неймспейсе shturval-backend.

Подключение в платформе

Авторизуйтесь в платформе “Штурвал” по kubeconfig, полученному при инсталляции платформы или можно взять его с Control Plane узла платформы /etc/kubernetes/admin.conf.

Подготовьте YAML-файл с манифестом Secret именем auth-provider и лейблом auth.shturval.tech/oidc-provider: "". В Secret задайте требуемые параметры.

apiVersion: v1
kind: Secret
metadata:
  name: auth-provider
  namespace: shturval-backend
  labels:
    auth.shturval.tech/oidc-provider: ""
type: Opaque
stringData:
  active: "true"
  external_idp: |
        {"name":"shturval-keycloak","issuerUrl":"https://keycloak.example.com/realms/shturval","codeVerifyMethod":"plain","client":{"clientId":"shturval_keycloak","clientSecret":"<client-secret>"},"insecureSkipVerify":true,"tokenClaimMapping":{"sub":"sub","name":"name","email":"email","preferredUsername":"sub","claims":"groups","aud":"aud"}}
  skip_internal_auth: "false"

Параметр	Описание	Тип данных	Пример
`active`	Включение Keycloak как внешнего OIDC-провайдера	string	`"true"`
`external_idp`	JSON-конфигурация Keycloak. В примере указана конфигурация с `issuerUrl` `https://keycloak.example.com/realms/shturval`, `clientId` `shturval_keycloak`, `clientSecret` `<client-secret>` и стандартным маппингом claim	string	`{"name":"shturval-keycloak",...}`
`skip_internal_auth`	Доступность внутреннего провайдера при включенном Keycloak	string	`"false"`

apiVersion: v1
kind: Secret
metadata:
  name: auth-provider
  namespace: shturval-backend
  labels:
    auth.shturval.tech/oidc-provider: ""
type: Opaque
stringData:
  active: "true"
  external_idp: |
        {"name":"shturval-blitz","issuerUrl":"https://blitz.example.com/realms/shturval","client":{"clientId":"shturval_blitz","clientSecret":"<client-secret>"},"insecureSkipVerify":true,"tokenClaimMapping":{"sub":"sub","name":"name","email":"email","preferredUsername":"sub","claims":"groups","aud":"aud"}}
  skip_internal_auth: "false"

Параметр	Описание	Тип данных	Пример
`active`	Включение Blitz как внешнего OIDC-провайдера	string	`"true"`
`external_idp`	JSON-конфигурация Blitz. В примере указана конфигурация с `issuerUrl` `https://blitz.example.com/realms/shturval`, `clientId` `shturval_blitz`, `clientSecret` `<client-secret>` и стандартным маппингом claim	string	`{"name":"shturval-blitz",...}`
`skip_internal_auth`	Доступность внутреннего провайдера при включенном Blitz	string	`"false"`

Создайте в кластере Secret auth-provider

Команда — иллюстрация

kubectl apply -f УКАЖИТЕ-ФАЙЛ-С-МАНИФЕСТОМ-SECRET.yaml

Пример имени файла с манифестом: auth-provider.yaml.

Проверьте, что Secret auth-provider создан в неймспейсе shturval-backend и содержит конфигурацию внешнего OIDC-провайдера.

Команда — иллюстрация

kubectl get secret auth-provider -n shturval-backend -o yaml

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

Изменено 2026-10-01 в 15:46

Подключить внешний OIDC-провайдер

Подготовка к настройке подключения в платформе #

Требования к Access Token внешнего OIDC-провайдера #

Корневой CA сертификат внешнего OIDC-провайдера #

Подключение внешнего OIDC-провайдера в платформе #

В графическом интерфейсе #

Как перейти к настройке интеграции #

Шаг 1. Заполните параметры подключения #

Шаг 2. Проверьте подключение #

Шаг 3. Маппинг Access Token OIDC-провайдера #

Шаг 4. Включите и сохраните конфигурацию #

Просмотр и редактирование настроек интеграции #

В интерфейсе командной строки #

Конфигурация внешнего OIDC-провайдера #

Подключение в платформе #

Подготовка к настройке подключения в платформе

Требования к Access Token внешнего OIDC-провайдера

Корневой CA сертификат внешнего OIDC-провайдера

Подключение внешнего OIDC-провайдера в платформе

В графическом интерфейсе

Как перейти к настройке интеграции

Шаг 1. Заполните параметры подключения

Шаг 2. Проверьте подключение

Шаг 3. Маппинг Access Token OIDC-провайдера

Шаг 4. Включите и сохраните конфигурацию

Просмотр и редактирование настроек интеграции

В интерфейсе командной строки

Конфигурация внешнего OIDC-провайдера

Подключение в платформе