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

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

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

Airlock выступает в роли SAML Service Provider (SP) и принимает аутентификацию от внешнего Identity Provider (IdP).

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

• Развёрнутый SAML IdP (например, Active Directory Federation Services) с пользователями в группах.
• Роль Airlock с правом управления ресурсами saml (доступна в роли editor).
• Установленная утилита airctl.

Общие принципы SAML

SAML-аутентификация включает:

1. IdP (Identity Provider) — провайдер, который аутентифицирует пользователя и выпускает SAML assertion.
2. SP (Service Provider) — Airlock, который принимает assertion и создаёт сессию.
3. ACS URL — endpoint Airlock, куда IdP отправляет SAML-ответ: https://<proxy>/v1/webapi/saml/acs.
4. Entity Descriptor — XML-метаданные IdP с сертификатами и endpoints.
5. Атрибуты (claims) — группы, email, имя пользователя — сопоставляются с ролями Airlock через attributes_to_roles.

Шаг 1. Настройка IdP (пример ADFS)

В Active Directory Federation Services настройте:

Claims Provider Trust — входящие claims от Active Directory:

• Name ID: LDAP-атрибут E-Mail-Addresses → Name ID
• Group: claim членства в группах для сопоставления с ролями
• При необходимости: SAM-Account-Name → Windows account name, E-Mail-Addresses → UPN

Relying Party Trust — доверие к Airlock:

• Display name: Airlock
• SAML 2.0 Web SSO URL: https://airlock.example.com/v1/webapi/saml/acs
• Relying party trust identifier: тот же ACS URL
• Claim Issuance Policy: отправлять как минимум Name ID и Group

Убедитесь, что у пользователей Active Directory заполнено поле email.

Шаг 2. Создание ролей Airlock

Создайте роли для администраторов и обычных пользователей.

# admin-role.yaml
kind: role
version: v3
metadata:
  name: admin
spec:
  options:
    max_session_ttl: "8h0m0s"
  allow:
    logins: [ root ]
    node_labels:
      "*": "*"
    rules:
      - resources: ["*"]
        verbs: ["*"]

# user-role.yaml
kind: role
version: v3
metadata:
  name: dev
spec:
  options:
    max_session_ttl: "1h"
  allow:
    logins:
      - '{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}'
      - ubuntu
    node_labels:
      "access": "relaxed"

Роль dev разрешает вход только на узлы с меткой access: relaxed. Шаблон {{external[...]}} подставляет значение SAML-атрибута как разрешённый OS-логин.

Шаг 3. Создание SAML-коннектора

Сгенерируйте конфигурацию коннектора:

airctl sso configure saml --acs https://airlock.example.com/v1/webapi/saml/acs \
  --preset adfs \
  --entity-descriptor https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml \
  --attributes-to-roles http://schemas.xmlsoap.org/claims/Group,teleadmins,editor \
  --attributes-to-roles http://schemas.xmlsoap.org/claims/Group,Users,access \
  > adfs.yaml

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

cat adfs.yaml | airctl sso test

Примените коннектор:

airctl create -f adfs.yaml

Экспорт ключа подписи

Экспортируйте сертификат подписи Airlock и добавьте его в IdP как certificate for signature verification:

airctl saml export adfs > saml.cer

Вход через SAML

airsh --proxy=airlock.example.com login

При нескольких SAML-коннекторах укажите имя:

airsh login --auth=adfs

Сопоставление атрибутов

Поле attributes_to_roles связывает SAML-атрибуты с ролями Airlock:

kind: saml
version: v2
metadata:
  name: saml-connector
spec:
  acs: https://airlock.example.com/v1/webapi/saml/acs
  entity_descriptor: |
    <?xml version="1.0"?>
    <!-- XML-метаданные IdP -->
  attributes_to_roles:
    - name: "groups"
      value: "admins"
      roles: ["editor"]
    - name: "groups"
      value: "developers"
      roles: ["access"]

Полное имя атрибута зависит от IdP. Для ADFS группы часто имеют URI http://schemas.xmlsoap.org/claims/Group.

Динамические traits

Значения SAML-атрибутов доступны в ролях через {{external["имя-атрибута"]}}. Это позволяет назначать OS-логины, метки окружений и другие параметры на основе данных IdP.

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

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

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

airctl get cap > cap.yaml
# отредактируйте cap.yaml
airctl create -f cap.yaml

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

• Убедитесь, что ACS URL в IdP и коннекторе совпадают.
• Проверьте, что IdP отправляет необходимые атрибуты (группы, email).
• Используйте airctl sso test для диагностики SAML-потока.
• При ошибках подписи проверьте, что сертификат Airlock добавлен в IdP.