Единый вход через корпоративный IdP (OIDC)

Единый вход (SSO) позволяет пользователям входить в Stronghold под корпоративной учётной записью, а администраторам — управлять доступом через группы в провайдере идентификации (IdP). Stronghold поддерживает любой IdP, совместимый с OpenID Connect.

Цель

После настройки:

• Пользователи входят в веб-интерфейс и CLI Stronghold через корпоративный IdP.
• Политики назначаются по группам IdP через внешние группы Identity.
• Вход разрешён только членам определённых групп.

Общая схема

Что нужно настроить в любом IdP:

1. Клиент (приложение) OIDC с типом confidential и секретом клиента.
2. URI перенаправления: для веб-интерфейса — https://<STRONGHOLD_ADDRESS>/ui/stronghold/auth/<METHOD_PATH>/oidc/callback, для CLI — http://localhost:8250/oidc/callback. Здесь <STRONGHOLD_ADDRESS> — адрес, по которому пользователи открывают Stronghold, а <METHOD_PATH> — путь, по которому включён метод OIDC.
3. Утверждение (claim) со списком групп пользователя в ID-токене.

Выбор провайдера

Выберите провайдера в зависимости от того, где ведутся учётные записи пользователей:

Предварительные требования

Перед началом подготовьте:

• Stronghold доступен пользователям по HTTPS, например https://stronghold.example.com.
• IdP доступен узлам Stronghold по HTTPS, сертификат IdP выдан доверенным УЦ.
• Токен Stronghold с правами на настройку методов аутентификации, политик и Identity.
• Подготовленный аварийный доступ на случай недоступности IdP.

Пример: Keycloak

В примере пользователи из группы Keycloak stronghold-admins получают политику admin, а из группы stronghold-users — политику user-read.

Шаг 1. Настройте клиент в Keycloak

Создайте в Keycloak клиент OIDC для Stronghold.

1. В Realm corp создайте клиент stronghold с протоколом openid-connect, включите Client authentication и Standard flow.

2. В Valid Redirect URIs укажите:

   https://stronghold.example.com/ui/stronghold/auth/oidc/oidc/callback
   http://localhost:8250/oidc/callback

3. Добавьте в клиент маппер Group Membership с именем утверждения groups и отключите Full group path.

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

Подробности настройки — в разделе «OIDC-провайдер Keycloak».

Шаг 2. Настройте метод OIDC

Включите метод OIDC в Stronghold и создайте роль для входа.

1. Включите метод и настройте подключение к Realm:

   d8 stronghold auth enable oidc
   d8 stronghold write auth/oidc/config oidc_discovery_url="https://keycloak.example.com/realms/corp" oidc_client_id="stronghold" oidc_client_secret="<CLIENT_SECRET>" default_role="corp"

   <CLIENT_SECRET> — секрет клиента, скопированный на шаге 1.

2. Создайте роль. bound_claims пропускает только участников двух групп, groups_claim передаёт группы в Identity:

   d8 stronghold write auth/oidc/role/corp -<<EOF
   {
     "role_type": "oidc",
     "allowed_redirect_uris": [
       "https://stronghold.example.com/ui/stronghold/auth/oidc/oidc/callback",
       "http://localhost:8250/oidc/callback"
     ],
     "oidc_scopes": ["openid", "profile", "email"],
     "user_claim": "preferred_username",
     "groups_claim": "groups",
     "bound_claims": { "groups": ["stronghold-users", "stronghold-admins"] },
     "token_policies": ["default"],
     "token_ttl": "1h",
     "token_max_ttl": "8h"
   }
   EOF

Шаг 3. Сопоставьте группы с политиками

Для каждой группы создайте внешнюю группу Identity и псевдоним. Значение name псевдонима должно совпадать с именем группы в утверждении groups:

OIDC_ACCESSOR=$(d8 stronghold auth list -format=json | jq -r '."oidc/".accessor')

ADMINS_ID=$(d8 stronghold write -field=id identity/group name="corp-admins" type="external" policies="admin")
d8 stronghold write identity/group-alias name="stronghold-admins" mount_accessor="$OIDC_ACCESSOR" canonical_id="$ADMINS_ID"

USERS_ID=$(d8 stronghold write -field=id identity/group name="corp-users" type="external" policies="user-read")
d8 stronghold write identity/group-alias name="stronghold-users" mount_accessor="$OIDC_ACCESSOR" canonical_id="$USERS_ID"

Политики admin и user-read должны существовать заранее. Примеры политик приведены в разделе «Примеры политик».

Шаг 4. Проверьте вход

Проверьте вход через CLI и веб-интерфейс.

1. Войдите через CLI — откроется браузер со страницей входа Keycloak:

   d8 stronghold login -method=oidc role=corp

2. Проверьте политики токена:

   d8 stronghold token lookup

   У члена stronghold-admins в identity_policies должна быть политика admin.

3. В веб-интерфейсе выберите метод OIDC, укажите роль corp и войдите.

Вход через Dex в DP

Если Stronghold установлен как модуль DP в режиме Automatic, после инициализации Stronghold модуль сам настраивает вход через Dex — провайдер аутентификации DP, который получает пользователей и группы из подключённого внешнего IdP или LDAP.

• Метод OIDC включается по пути oidc_deckhouse, для входа создаётся роль по умолчанию deckhouse_dex_authenticated (claim групп — groups), а администраторам назначается политика deckhouse_administrators (полный доступ).
• Администраторы задаются в параметре settings.management.administrators в ModuleConfig stronghold — группами (type: Group) или отдельными пользователями (type: User). Пользователь должен входить хотя бы в одну группу.

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: stronghold
spec:
  enabled: true
  version: 1
  settings:
    management:
      mode: Automatic
      administrators:
      - type: Group
        name: admins

Вход пользователя:

d8 stronghold login -path=oidc_deckhouse -method=oidc -no-print

Чтобы выдать права не только администраторам, создайте внешние группы Identity с псевдонимами на accessor метода oidc_deckhouse/ так же, как в шаге 3 примера с Keycloak. Имена псевдонимов должны совпадать с именами групп, которые передаёт Dex.

Модуль периодически (по умолчанию каждые 60 секунд) применяет конфигурацию заново, поэтому ручные изменения в auth/oidc_deckhouse перезаписываются:

• OIDC-конфигурация метода (discovery URL, ID и секрет клиента, роль по умолчанию) и роль deckhouse_dex_authenticated (audience, redirect URI, claim’ы email и groups, scopes) переписываются безусловно; свои изменения вносите в отдельной роли или по отдельному пути;
• описание метода и видимость unauth в списке восстанавливаются, если вы их измените;
• политика deckhouse_administrators снимается с сущностей и групп на accessor’е oidc_deckhouse/, которых нет в settings.management.administrators; остальные политики не затрагиваются.

Все пользователи входят с одной ролью deckhouse_dex_authenticated. Других ролей для них модуль не создаёт: права определяются политиками групп Identity, как описано выше.

Подробнее — в разделах «Настройка Stronghold» и «Настройка доступа и первый вход».

Устранение неполадок

Типовые ошибки и способы их устранения:

Очистка

Отключите метод OIDC:

d8 stronghold auth disable oidc

Удалите внешние группы corp-admins и corp-users через identity/group/name/<GROUP_NAME> и клиент stronghold в Keycloak.

Дополнительные ресурсы

• Метод OIDC
• OIDC-провайдер Keycloak
• OIDC-провайдер GitLab
• Настройка Stronghold в DP
• Идентификационные данные (Identity)
• Аварийный доступ (break-glass)