Перейти к основному содержимому
Версия: 1.12

Настройка OIDC-провайдеров

Spirit IAM — поставщик идентификации (IdP) в составе Sage и необходимый компонент для процессов аутентификации и авторизации. Для Sage Spirit IAM является конечным IdP: выдает токены и формирует профиль пользователя, а также предоставляет интерфейс для выдачи ролей и управления группами доступа. В текущем релизе в Spirit IAM нет интерфейса для управления учетными записями пользователей, поэтому в базовой поставке рядом с ним развертывается Keycloak, который выполняет аутентификацию и предоставляет такой интерфейс.

Чтобы пользователи входили в Sage через вашу систему управления доступом, подключите ее в качестве провайдера аутентификации через протокол OIDC вместо стандартного Keycloak. Управление пользователями при этом выполняет ваш провайдер, а Spirit IAM по мапперу преобразует данные о пользователе в его профиль.

Важно

Подключение OIDC-провайдера решает только задачу входа в Sage: выдать роль новому пользователю по-прежнему можно только в интерфейсе Spirit IAM.

Чтобы передавать данные о входе/регистрации или сведения о ролях внешним системам, настройте вебхуки.

Все действия выполняются внутри контейнера установщика sage-trukk на контрольном хосте. Изменения в конфигурацию вносите в соответствии с инструкцией Работа с файлами конфигурации.

Чтобы добавить OIDC-провайдера, выполните следующие шаги:

  1. Подготовьте OIDC-клиент и получите его параметры.
  2. Создайте Jsonnet-маппер, который преобразует claims провайдера в профиль пользователя Spirit IAM.
  3. Опишите провайдера в переменных конфигурации.
  4. Примените конфигурацию.

Шаг 1. Подготовка OIDC-клиента​

  1. Создайте OIDC-клиент в вашем провайдере аутентификации и получите его параметры:

    • client_id — публичный идентификатор клиента, под которым Spirit IAM обращается к провайдеру;
    • client_secret — секрет клиента, подтверждающий, что запрос исходит именно от Spirit IAM;
    • issuer_url — базовый адрес провайдера, от которого Spirit получает его конфигурацию и ключи для проверки подписи токенов.

  2. Определите набор полномочий scope, которые Spirit IAM запрашивает у провайдера при аутентификации. Запрашиваемый набор полномочий влияет на то, какие данные о пользователе провайдер включит в токен. Например:

    • openid — обязательный для протокола OIDC;
    • email — доступ к адресу электронной почты (основной идентификатор пользователя в Spirit IAM);
    • profile — доступ к базовым данным профиля (имя, фамилия и прочее).

Обязательными являются openid и email. Полный набор полномочий зависит от того, какие данные нужны вашему мапперу, и от того, какие claims может вернуть провайдер. При необходимости список можно расширять.

Шаг 2. Создание Jsonnet-маппера​

Jsonnet-маппер преобразует claims OIDC-провайдера в структуру профиля пользователя в Kratos. Для каждого провайдера нужен собственный маппер, поскольку набор claims у разных провайдеров отличается.

Разместите файл маппера в директории spirit/kratos внутри контейнера установщика на контрольном хосте.

Ниже приведен пример маппера для стандартного Keycloak, который развертывается вместе с Sage:

local claims = std.extVar('claims');
if std.length(claims.sub) == 0 then
  error 'claim sub not set'
else {
  identity: {
    traits: {
      email: claims.email,                              // обязателен для Spirit: основной идентификатор пользователя
      preferred_username: claims.preferred_username,    // имя пользователя в Spirit
      given_name: if std.objectHas(claims, 'given_name') then claims.given_name else '',   // имя; пусто, если провайдер его не передал
      family_name: if std.objectHas(claims, 'family_name') then claims.family_name else '', // фамилия; пусто, если провайдер ее не передал
      name: if std.objectHas(claims, 'name') then claims.name else '',                      // полное имя; пусто, если провайдер его не передал
    },
  },
}

Шаг 3. Описание провайдера в переменных конфигурации​

  1. В конфигурационном файле, например, group_vars/sage/spirit_iam-apps.yml, определите переменную sage_spirit_oidc_providers. В поле mapper_url укажите полный путь к мапперу, созданному на шаге 2: file:///etc/config/kratos/{имя_файла_маппера}.

    Подробнее о настройках см. в документации ORY Kratos (selfservice.methods.oidc), а также в Справочнике переменных.

    Пример настройки для Keycloak:

    sage_spirit_oidc_providers:
      - id: keycloak              # внутренний идентификатор провайдера
        label: "Keycloak"         # название, которое увидит пользователь при входе
        provider: generic         # тип провайдера
        client_id: "ID"           # client_id, полученный на шаге 1
        client_secret: "SECRET"   # client_secret, полученный на шаге 1
        scope:                    # полномочия, запрашиваемые у провайдера (см. шаг 1)
          - openid
          - email
          - profile
        issuer_url: "https://example.org/realms/sage"   # issuer_url (см. шаг 1)
        mapper_url: file:///etc/config/kratos/oidc.keycloak.jsonnet   # путь до маппера

  2. Определите переменную sage_oidc_provider — укажите в ней идентификатор провайдера, на которого Sage перенаправляет пользователя при входе. Значение должно совпадать со значением id из переменной sage_spirit_oidc_providers (в примере выше — keycloak).

    Если подключено несколько провайдеров, то именно эта переменная определяет, на какого из них Sage направит пользователя при входе по умолчанию.

Шаг 4. Применение конфигурации​

Чтобы применить изменения к компонентам Spirit IAM, запустите плейбук установки в режиме update с тегами apps и spirit_iam:

export SAGE_DEPLOY_MODE=update
ansible-playbook sage-setup.yml --tags apps,spirit_iam

Подробнее о режимах установки см. в статье Работа с файлами конфигурации, о переходе на новую версию — в Руководстве по обновлению.

После применения конфигурации на странице Spirit появится кнопка входа через добавленного провайдера.

Примечание

OIDC-провайдер передает Spirit IAM только те данные, которые входят в claims. Если вам требуется уведомить внешние системы о входе или регистрации пользователя (например, для аудита операций) либо передать сведения о ролях и полномочиях пользователя из Spirit IAM, дополнительно настройте вебхуки.

Последнее обновление