Аутентификация OIDC

Это руководство описывает настройку SSO-провайдера на базе OpenID Connect (OIDC) для выдачи учётных данных Airlock группам пользователей. В сочетании с RBAC администраторы могут задавать политики:

• Только члены группы «DBA» могут подключаться к PostgreSQL.
• Разработчикам запрещён SSH-доступ к production-серверам.

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

• Административный доступ к SSO/IdP с пользователями, распределёнными по группам.
• Роль Airlock с правом управления ресурсами oidc (доступна в роли editor по умолчанию).
• Установленная утилита airctl и доступ к кластеру.

Регистрация приложения в IdP

Зарегистрируйте Airlock во внешнем провайдере идентификации и получите client_id и client_secret.

URL перенаправления OIDC

OIDC использует HTTP-редиректы для возврата управления в Airlock после аутентификации. URL перенаправления должен быть заранее согласован с IdP.

Формат URL:

https://<адрес-proxy>:443/v1/webapi/oidc/callback

Замените <адрес-proxy> на публичный адрес Proxy Service Airlock (например, airlock.example.com).

Настройка OIDC-коннектора

Коннекторы создаются, тестируются и удаляются через airctl или веб-интерфейс Airlock.

Создайте файл client-secret.txt, содержащий только client secret. Сгенерируйте YAML-конфигурацию коннектора:

airctl sso configure oidc --name keycloak \
  --issuer-url https://keycloak.example.com/realms/master \
  --id airlock \
  --secret $(cat client-secret.txt) \
  --claims-to-roles groups,/users,access \
  --claims-to-roles groups,/admins,editor > oidc-connector.yaml

Пример готового коннектора:

kind: oidc
metadata:
  name: keycloak
spec:
  claims_to_roles:
  - claim: groups
    roles:
    - access
    value: /users
  - claim: groups
    roles:
    - editor
    value: /admins
  client_id: airlock
  client_secret: abc123...
  issuer_url: https://keycloak.example.com/realms/master
  redirect_url: https://airlock.example.com:443/v1/webapi/oidc/callback
version: v3

Пример: Keycloak

В Keycloak на keycloak.example.com создайте клиент airlock. В client scope airlock-dedicated добавьте mapper «Group Membership», чтобы claim groups передавался в токен.

Тестирование и применение

Перед применением проверьте коннектор:

cat oidc-connector.yaml | airctl sso test

Команда откроет браузер и попытается выполнить вход через IdP. При ошибке изучите вывод — раздел «[OIDC] Claims» показывает все claims пользователя от IdP.

После успешного теста создайте коннектор:

airctl create -f oidc-connector.yaml

Вход через OIDC:

airsh --proxy=airlock.example.com login --auth=keycloak

Дополнительные параметры

ACR Values

Airlock может отправлять Authentication Context Class Reference (ACR) при получении authorization code. Если поле acr_values задано, Airlock ожидает то же значение в claim acr.

kind: oidc
version: v2
metadata:
  name: oidc-connector
spec:
  issuer_url: "https://oidc.example.com"
  client_id: "xxxxxxxxxxxxxxxxxxxxxxx.example.com"
  client_secret: "zzzzzzzzzzzzzzzzzzzzzzzz"
  redirect_url: "https://airlock.example.com/v1/webapi/oidc/callback"
  display: "Login with Example"
  acr_values: "foo/bar"
  scope: [ "group" ]
  claims_to_roles:
     - claim: "group"
       value: "editor"
       roles: [ "editor" ]
     - claim: "group"
       value: "user"
       roles: [ "access" ]

Max age

Поле max_age задаёт максимальный возраст сессии OIDC до принудительной повторной аутентификации. По умолчанию не задано. Значение 0s принуждает к повторной аутентификации при каждом входе.

spec:
  max_age: 24h

Prompt

Управляет поведением Authorization Server при повторной аутентификации и согласии. По умолчанию Airlock использует select_account.

spec:
  # Допустимые значения: none, select_account, login, consent
  prompt: 'login'

Отключение проверки email

По умолчанию Airlock проверяет claim email_verified. Для тестирования можно включить allow_unverified_email (снижает безопасность):

kind: oidc
version: v2
metadata:
  name: connector
spec:
  allow_unverified_email: true

Username claim

По умолчанию в качестве имени пользователя Airlock использует email. Альтернативный claim:

spec:
  username_claim: preferred_username

Аутентификация по умолчанию

Чтобы OIDC стал методом входа по умолчанию, обновите cluster_auth_preference:

airctl get cap > cap.yaml

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:
  type: oidc
version: v2

airctl create -f cap.yaml

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

При ошибке Failed to calculate user attributes проверьте сопоставление claims_to_roles — значения claim должны точно совпадать с тем, что возвращает IdP. Используйте airctl sso test для просмотра всех claims.