Сравните контракт атрибутов у IdP и приложения, а не только подписи полей в административной панели. Отображаемое название может не совпадать с тем именем, по которому SP читает значение. Сначала получите безопасное описание уже проверенной assertion на стенде: имена, форматы и количество значений без реальных персональных данных и секретов.
Имена и кратность входят в контракт интеграции
В SAML-адаптере Keycloak для WildFly/EAP документация различает получение атрибута по name и friendly name, а также списка значений и первого значения. Источник проверен 24 октября 2026 года. Это конкретный пример API адаптера; в другой библиотеке названия методов и правила сопоставления могут отличаться. Не переносите конфигурацию между реализациями без проверки.
| Свойство | Вопрос для сопоставления |
|---|---|
| Name | Какое точное имя передано в assertion? |
| FriendlyName | Есть ли удобное имя и использует ли его библиотека? |
| NameFormat | Как объявлен формат имени? |
| Количество значений | Нужно одно значение или список? |
| Локальное поле | Профиль, группа или источник полномочий? |
Составьте таблицу для одного конкретного приложения и доверенного issuer. Не назначайте глобально любому атрибуту с удобным названием смысл административной роли. Одни и те же имена у двух поставщиков идентификации могут иметь разные договорённости. Поле email для отображения и устойчивый идентификатор учётной записи тоже решают разные задачи.
Переходное сопоставление должно замечать конфликт
Условная схема, не конфигурация Keycloak:
issuer A + старое имя -> локальное department
issuer A + новое имя -> локальное department
оба имени, значения совпали -> допустимый переходный случай
оба имени, значения различаются -> явная ошибка контракта
неизвестное имя -> не выдавать дополнительные полномочияНе исправляйте несовпадение поиском «первого похожего» поля или безусловным приведением всех имён к нижнему регистру. Такое преобразование может склеить разные ключи и скрыть смену контракта. Временные alias ограничьте известным IdP, назначением и сроком миграции. Запишите, какое правило сработало, без публикации полного содержимого assertion.
Многозначный атрибут нельзя молча превращать в строку через запятую, если принимающая сторона ожидает список групп. Иначе группа с запятой в названии станет двумя сущностями, а выбор первого значения потеряет часть данных. Задайте тип и поведение при пустом, единственном и нескольких значениях; для полномочий используйте согласованный разрешённый набор.
Извлекайте бизнес-поля только из результата штатной проверки SAML доверенной библиотекой. Mapper не заменяет проверку подписи, назначения и прочих условий протокола. Нельзя ради нового имени принять произвольный XML из запроса или отключить валидацию. Если проверка сообщения уже не проходит, это отдельная неисправность до сопоставления атрибутов.
Меняйте mapper на искусственных профилях
- Только старое имя и только новое имя.
- Два имени с одинаковым и разным содержимым.
- Пустое значение и отсутствующий атрибут.
- Несколько значений группы.
- То же имя от другого настроенного issuer.
Проверьте конечный профиль и доступ, а не только успешный callback. Новый mapper не должен создавать второго пользователя, затирать локально управляемые поля или добавлять роль из неизвестного значения. Откат возвращает предыдущую версию правил; данные, которые уже изменились при входе, требуют самостоятельной сверки.
На технический разбор принесите названия IdP/SP, версию библиотеки и обезличенную таблицу атрибутов до и после изменения. Успех миграции виден по понятному правилу для каждого поля и безопасному отказу при конфликте, а не по тому, что любой SAML-вход перестал показывать ошибку.