Миграция с SAML на OIDC

Миграция с SAML на OIDC#

OIDC – рекомендуемый способ организации единого входа, поэтому единый вход Astra Automation, настроенный через SAML, со временем может потребоваться перевести на Generic OIDC. Такой переход необходимо выполнить без создания дублирующихся учетных записей: существующие учетные записи пользователей должны сохраниться.

Примечание

Приведенная далее инструкция протестирована с помощью Keycloak версии 26.5.1. В других версиях Keycloak отдельные параметры и поведение интерфейса могут отличаться.

Принцип сопоставления учетных записей#

Платформа сопоставляет учетную запись во внешней системе с учетной записью Astra Automation по стабильному идентификатору:

  • для метода SAML – по значению атрибута SAML, указанного в поле Постоянный ID пользователя (User Permanent ID);

  • для метода Generic OIDC – по значению утверждения sub, которое провайдер передает в ID token. Для Keycloak значение sub – это внутренний идентификатор пользователя (UUID). В проверенных сценариях идентификатором учетной записи всегда становится sub, даже если в поле Ключ ID (ID Key) указано другое значение.

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

Таким образом, для бесшовной миграции метод SAML должен передавать в поле Постоянный ID пользователя (User Permanent ID) тот же идентификатор, который метод OIDC затем получит в утверждении sub.

Подготовка метода SAML#

Настроить передачу стабильного идентификатора необходимо на этапе первоначальной настройки метода SAML. Изменить поле Постоянный ID пользователя (User Permanent ID) на методе с уже созданными учетными записями без их дублирования нельзя (см. предупреждение в конце секции).

Для передачи внутреннего идентификатора пользователя Keycloak через утверждение SAML в графической консоли Keycloak выполните следующие действия:

  1. Создайте client scope с протоколом SAML и произвольным названием, например aa-attrs, либо используйте выделенный client scope клиента с суффиксом -dedicated.

  2. Добавьте в client scope mapper типа User Property со следующими параметрами:

    • Property – id;

    • SAML Attribute Name – uid;

    • SAML Attribute NameFormat – Basic.

  3. Если использовался отдельный client scope, привяжите его к клиенту Astra Automation на вкладке Client scopes кнопкой Add client scope.

Затем в графической консоли Astra Automation в настройках метода аутентификации SAML укажите значение uid в поле Постоянный ID пользователя (User Permanent ID).

Предупреждение

Не изменяйте значение поля Постоянный ID пользователя (User Permanent ID) на работающем методе SAML с существующими учетными записями. После замены атрибута передаваемый идентификатор меняется, и при следующем входе по SAML платформа создает для существующей учетной записи дубликат с суффиксом. Штатного способа изменить сохраненные идентификаторы существующих привязок нет: API authenticator_users доступен только для чтения.

Порядок миграции#

Для перевода единого входа с SAML на OIDC выполните следующие действия:

  1. Убедитесь, что метод SAML передает стабильный идентификатор (см. Подготовка метода SAML).

  2. Создайте клиента OIDC в Keycloak и метод аутентификации Generic OIDC согласно инструкции по настройке OIDC. В поле Ключ ID (ID Key) укажите sub.

  3. В графической консоли Astra Automation в поле Автоматически мигрировать пользователей из (Auto migrate users from) метода Generic OIDC выберите метод SAML.

    Примечание

    При настройке через API поле называется auto_migrate_users_to: оно задается на старом методе (SAML) и содержит идентификатор нового метода (OIDC). Значение поля auto_migrate_users_from, переданное при создании нового метода через API, не сохраняется.

  4. Выполните вход тестовым пользователем через новый метод OIDC и убедитесь с помощью графической консоли Astra Automation в следующем:

    • вход выполнен в существующую учетную запись, ее название не содержит автоматически добавленного суффикса;

    • в списке учетных записей не появился дубликат;

    • сохранены роли, членство в организациях и командах, а также владение объектами.

  5. После успешной проверки сообщите пользователям о переходе и отключите метод SAML.

  6. Не удаляйте метод SAML до подтверждения корректной работы OIDC для всех учетных записей: включение метода обратно остается способом быстрого возврата.

Проверенные сценарии#

Бесшовная миграция подтверждена в следующей конфигурации:

SAML: User Permanent ID = uid (внутренний идентификатор пользователя Keycloak)
OIDC: sub
Результат: учетная запись переиспользована, привязка перенесена на метод OIDC

Конфигурации, приводящие к созданию дублирующихся учетных записей даже при включенной автоматической миграции, приведены в секции о миграции пользователей на странице OIDC. Основная причина дубликатов – использование адреса электронной почты в поле Постоянный ID пользователя (User Permanent ID): такое значение не совпадает с утверждением sub, которое передает OIDC.