Подключить внешний 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-провайдера

При настройке интеграции в 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 будет недоступно. 

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

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

    1. В платформе перейдите на страницу Интеграция с 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-провайдера

    1. До подключения внешнего 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.

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

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

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

    2. Загрузите и сохраните действующие kubeconfigs кластеров (клиентских кластеров, кластера управления). Kubeconfig потребуется для подключения к кластеру из консоли.

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

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

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

    1. Подготовьте 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"
      1. Создайте в кластере Secret auth-provider
      Команда — иллюстрация 
      kubectl apply -f УКАЖИТЕ-ФАЙЛ-С-МАНИФЕСТОМ-SECRET.yaml

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

      1. Проверьте, что Secret auth-provider создан в неймспейсе shturval-backend и содержит конфигурацию внешнего OIDC-провайдера.
      Команда — иллюстрация 
      kubectl get secret auth-provider -n shturval-backend -o yaml

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

      ← Сессии пользователей
      Восстановление доступа при сбое внешнего сервиса →