Перейти к содержанию

Инструкция по интеграции OIDC-провайдера Identity Blitz и Платформы Боцман

Шаг 1: Подготовка и базовая настройка Identity Blitz

  1. Правильно задайте домен при установке

    Внимание

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

  2. Активируйте и настройте встроенный LDAP-сервер (389-ds)

    • Identity Blitz по умолчанию использует встроенное хранилище (build-in), которое не поддерживает группы. Для работы с группами необходимо подключить LDAP.
    • В инструкции по установке Blitz рекомендуется поставить встроенный 389-ds, но его недостаточно просто установить — требуется дополнительная настройка.

  3. Подготовьте LDAP-хранилище с помощью скриптов из дистрибутива Blitz

    • В дистрибутиве Identity Blitz есть папка scripts.
    • Запустите скрипты по порядку:
      • init-скрипт: Инициализирует домен, создает служебного пользователя (например, tree-reader) и настраивает базовые политики паролей.
      • group-скрипт (например, grlb): Подготавливает LDAP к работе с группами. Он создает необходимую структуру (Organizational Unit Groups), стандартную группу (например, ORGS) и настраивает атрибуты.

    Внимание

    Без выполнения этих скриптов функционал групп в Blitz работать не будет.

Шаг 2: Настройка хранилища данных (Data Source) в Blitz

  1. Добавьте новое хранилище.

    • В веб-интерфейсе Blitz перейдите в раздел Data Sources.
    • Нажмите "Добавить" и выберите тип "LDAP".

    blitz_source
    blitz_connect

  2. Заполните параметры подключения к LDAP.

    • Host/Port: Укажите хост и порт вашего LDAP-сервера (для 389-ds это localhost и стандартный порт).
    • Базовый DN: Базовый Distinguished Name, где находятся пользователи (напр., cn=users,dc=blitz,dc=local).
    • Пользователь (DN) & Пароль: Учетные данные пользователя с правами на чтение в LDAP (например, созданный tree-reader). Рекомендуется использовать отдельного служебного пользователя, а не суперадминистратора.

  3. Настройте маппинг атрибутов (Attribute Mapping). !!! warning "Внимание" Это ключевой этап. Необходимо сопоставить атрибуты пользователя в LDAP с внутренними атрибутами Blitz.

    • Пример маппинга:
      • sub (логин в Blitz) -> cn (Common Name в LDAP)
      • email -> mail
      • given_name -> givenName
    • Убедитесь, что для объекта класса пользователя в LDAP выбран расширенный класс, например, organizationalPerson, который поддерживает больше атрибутов и связь с группами.

    blitz_attribute

  4. Добавьте вычисляемый атрибут email_verified.

    • Боцман требует в JWT-токене наличие поля email_verified.
    • В Blitz перейдите в настройки атрибутов пользователя.
    • Добавьте новый атрибут:
      • Имя: email_verified
      • Тип: Boolean
      • Значение: Всегда true (Вычисляемый атрибут).

    blitz_attribute_2

Шаг 3: Настройка OAuth 2.0 / OIDC клиента в Blitz для Боцман

  1. Создайте нового клиента.

    • В веб-интерфейсе Blitz перейдите в раздел Приложения
    • Нажмите "Добавить приложение".

  2. Заполните основные параметры приложения:

    • Идентификатор: Уникальный идентификатор (напр., bootsman). Это неизменяемое поле, запишите его.
    • Client Secret: В разделе «Настройки взаимодействия с приложением» сгенерируйте и сохраните сложный секрет. Он понадобится для настройки Боцман.
    • Friendly Name / Domain: Внутреннее понятное имя и домен (напр., bootsman-test).

  3. Настройте Redirect URIs.

    • Это адреса, на которые Blitz может перенаправлять после аутентификации.
    • Обязательно укажите: https://<ВАШ_ДОМЕН_БОЦМАН>/verify-auth
    • Для удобства можно также указать общий домен с wildcard: https://<ВАШ_ДОМЕН_БОЦМАН>/* (это менее безопасно).

  4. Проверьте Разрешения.

    • Убедитесь, что клиенту передаются стандартные поля OIDC. Минимальный необходимый набор:
      • email
      • groups
      • profile
      • openid
    • Настройте маппинг атрибутов в полях (в разделе Scopes настроек Blitz), чтобы убедиться, что email и profile попадают в нужные поля.

    blitz_app_settings

  5. Настройте маппинг в JWT-токене.

    • В настройках клиента найдите раздел, отвечающий за содержимое ID-токена (JWT Claims).
    • Убедитесь, что передаются следующие поля. Это критически важно для правильного отображения пользователя в Боцман:
      • name
      • email
      • email_verified (был создан на шаге 2.4)
      • groups

    blitz_token

Шаг 4: Настройка аутентификации в Боцман

  1. Перейдите в настройки аутентификации Боцман.

    • В Боцмане откройте глобальные настройки (Settings).
    • В меню «Пользователи» перейдите в раздел «Провайдеры авторизации» и выберите провайдер аутентификации Identity Blitz.

  2. Заполните параметры провайдера данными из Blitz:

    • issuer: Базовый адрес переадресации из Шага 3.
    • Client ID: заданныйClient ID из Шага 3.2.
    • Client Secret: Сгенерированный Client Secret из Шага 3.2.
    • RedirectURI: https://<ВАШ_ ДОМЕН _БОЦМАН>/verify-auth адрес из «Префиксы ссылок возврата»
    • Scopes: email groups profile openid.

    Пример конфигуарции подключения: blitz_yaml_config

  3. Сохраните настройки и протестируйте вход.

Шаг 5: Включение и настройка синхронизации групп в Blitz

Внимание

Этот шаг необходим, чтобы группы из LDAP отображались в интерфейсе Blitz и, как следствие, передавались в Боцман.

  1. Включите функционал групп через конфигурационный файл.

    • Функционал групп по умолчанию отключен. Его необходимо включить через главный конфигурационный файл Blitz (blitz-config.json).
    • Найдите в файле секцию "groups". Она может быть закомментирована (например, с помощью символа _ в начале).
    • Раскомментируйте эту секцию, удалив символ комментария, и сохраните файл. После этого в интерфейсе Blitz должна появиться вкладка "Группы".

  2. Настройте хранилище для групп.

    • После включения функционала необходимо "привязать" только что созданное LDAP-хранилище (из Шага 2) к системе групп Blitz.
    • В конфигурационном файле, в секции groups, укажите store_id, соответствующий вашему LDAP-хранилищу, и настройте member_of и base_dn для корректного поиска групп.

Часто задаваемые вопросы:

  1. Пользователи в Blitz не отображаются без поиска.

    • Проблема: В Blitz на странице пользователей список пуст.
    • Решение: Используйте поиск с символом * (звездочка), чтобы отобразить всех пользователей.

  2. Проблемы с SSL-сертификатами.

    • Проблема: Ошибки из-за невалидных или самоподписанных сертификатов.
    • Решение:
      • Рекомендуемый путь: Используйте общий центр сертификации (например, cert-manager, входящий в состав Боцман) для выпуска валидных сертификатов как для Blitz, так и для Боцман. Настройте Ingress для обоих продуктов, чтобы использовать эти сертификаты.
      • Альтернатива: Можно настроить встроенный в Blitz Nginx, следуя инструкции из дистрибутива, но это требует более глубокой настройки маршрутизации между компонентами Blitz.

  3. Группы не отображаются в Blitz.

    • Убедитесь, что вы:
      • Выполнили скрипты инициализации групп (Шаг 1).
      • Включили функционал групп в файле конфигурации (Шаг 5).
      • Правильно настроили хранилище для групп (Шаг 5).
      • Правильно указали Group Base DN в настройках Data Source (Шаг 2).