Пользовательские claims в Microsoft Entra ID

Выпуск пользовательских claim через атрибуты расширения каталога в Microsoft Entra ID

Зачем это нужно

Если вам нужно добавлять специфичные для группы или пользователя данные (например, идентификатор спонсора, роль партнёра или внутренний идентификатор) в токен при входе, directory extension позволяет хранить такие значения в объекте приложения и выдавать их как claim только тем пользователям, которые состоят в определённой группе.

Ключевые достоинства:

Claim-ы доступны только выбранным группам.
Данные не попадают в токены посторонних пользователей.
Работает как для SAML, так и для OIDC.

Что требуется перед началом

Права администратора для управления регистрацией приложения и Enterprise Application в Entra ID.
AppObjectId и ClientId приложения (из App registrations).
Идентификаторы групп и пользователей (ObjectId).
Удобный инструмент для тестирования: Graph Explorer и https://jwt.ms.

Пошаговая инструкция

Шаг 1 — Зарегистрируйте атрибуты directory extension

Используйте Microsoft Graph для добавления extensionProperties в объект приложения. Пример запроса (Graph Explorer):

POST https://graph.microsoft.com/v1.0/applications/{AppObjectId}/extensionProperties
Content-Type: application/json

{
  "name": "sponsorid1",
  "dataType": "String",
  "targetObjects": ["User"]
}

Повторите для sponsorid2. После регистрации вы получите полные имена атрибутов в формате:

extension__sponsorid1
extension__sponsorid2

Важно: запишите эти точные имена — они потребуются при назначении и маппинге claim.

Шаг 2 — Назначьте значения пользователям

Обновите объекты пользователей через PATCH запрос, добавив ранее зарегистрированный attribute name.

PATCH https://graph.microsoft.com/v1.0/users/{UserObjectId}
Content-Type: application/json

{
  "extension__sponsorid1": "ABC123"
}

Повторите для каждого пользователя и соответствующего атрибута (sponsorid1 или sponsorid2).

Замечание: если у вас много пользователей, автоматизируйте это через скрипт PowerShell/CLI или пакетные запросы.

Шаг 3 — Создайте claim в Enterprise Application

В портале Entra ID: Enterprise applications > [Ваше приложение] > Single sign‑on > Attributes & Claims.

Нажмите Add new claim.
Дайте имя (например, sponsorClaim1).
В блоке Claim conditions выберите Member и укажите группу, которой нужно выдавать claim.
В source attribute укажите полное имя directory extension (например, extension__sponsorid1).

Повторите для второй группы/атрибута.

Шаг 4 — Исправление ошибки с маппингом claims

Если при добавлении claim вы видите ошибку: “Application requires custom signing key to customize claims”, временное решение — включить маппинг в манифесте регистрации приложения:

"acceptMappedClaims": true

Это позволяет настраивать маппинг claim без загрузки кастомного ключа подписи. В долгосрочной перспективе оцените варианты с управлением ключами и политиками подписи токенов.

Важно: включение acceptMappedClaims даёт приложению возможность принимать замапленные claim — убедитесь, что изменение согласовано с политикой безопасности.

Шаг 5 — Тестирование

Откройте в браузере:

https://login.microsoftonline.com/(Tenant ID)/oauth2/v2.0/authorize?client_id=(Client ID)&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345

Войдите пользователем из целевой группы. В https://jwt.ms вы увидите id_token или SAML токен с вашим claim (например, sponsorid1). Пользователи, не входящие в указанные группы, не получат этот claim.

Частые ошибки и способы их решения

Claim не появляется: проверьте точное имя extension (extension__sponsorid1) и что пользователь имеет назначенное значение.
Claim выдаётся всем: проверьте условия Claim conditions — должно быть указано «Member» + нужная группа.
Ошибка с подпиской токена: вернитесь к манифесту и проверьте acceptMappedClaims или настройку кастомного ключа.
Поле пустое или null: убедитесь, что dataType соответствует (String) и значение корректно назначено в объекте пользователя.

Когда этот подход не подходит

Если нужно передавать чувствительные персональные данные без дополнительной защиты — лучше использовать back‑channel APIs.
Для динамических атрибутов, которые меняются в реальном времени и не должны храниться в каталоге, предпочтительнее запрашивать данные на стороне приложения после аутентификации.

Альтернативные подходы

Использовать Azure AD B2C custom attributes для сценариев с внешними потребителями.
Пробрасывать роли и атрибуты через SCIM или сторонний identity provider, если каталог ведётся вне Entra.

Роль‑ориентированный чеклист

Администратор Entra ID:
- Имеет AppObjectId и ClientId.
- Регистрирует extensionProperties и редактирует манифест.
Владелец приложения:
- Настраивает Enterprise Application > Attributes & Claims.
- Тестирует вход и проверяет токены.
Команда безопасности:
- Проверяет воздействие на конфиденциальность и утверждает acceptMappedClaims.

Критерии приёмки

Для пользователей группы A в токене появляется claim sponsorClaim1 со значением из extension__sponsorid1.
Для пользователей группы B появляется sponsorClaim2.
У пользователей вне этих групп claim отсутствует.
Тестирование пройдено через https://jwt.ms и/или приложение корректно воспринимает claim.

Шаблоны запросов (быстрая шпаргалка)

Пример POST для регистрации атрибута:

POST https://graph.microsoft.com/v1.0/applications/{AppObjectId}/extensionProperties
Content-Type: application/json

{
  "name": "sponsorid1",
  "dataType": "String",
  "targetObjects": ["User"]
}

Пример PATCH для назначения пользователю значения:

PATCH https://graph.microsoft.com/v1.0/users/{UserObjectId}
Content-Type: application/json

{
  "extension__sponsorid1": "ABC123"
}

Безопасность и конфиденциальность

Минимизируйте размер и чувствительность данных в claim.
Ограничьте выдачу claim только нужным группам.
Документируйте, какие приложения получают эти claim и для чего они используются.

Диаграмма принятия решений

flowchart TD
  A[Нужно добавлять кастомный атрибут в токен?] -->|Да| B[Можно ли сохранить атрибут в каталоге?]
  B -->|Да| C[Использовать directory extension + claims]
  B -->|Нет| D[Использовать back-channel API после аутентификации]
  A -->|Нет| E[Оставить стандартные claims]

Короткое объявление (для рассылки, 100–200 слов)

Если вашей команде нужно передавать специфичные идентификаторы (например, sponsorId) в SAML или OIDC токенах только для отдельных групп, мы реализовали метод через directory extension attributes в Microsoft Entra ID. Процесс включает регистрацию атрибута в приложении, назначение значений пользователям через Graph API и создание условий выдачи claim в Enterprise Application. Это позволяет безопасно пробрасывать специализированные данные только тем пользователям, которым они действительно нужны. В гайде также описаны тестирование, распространённые ошибки и контрольный чеклист для ролей. Ознакомьтесь с инструкцией и согласуйте изменения в манифесте приложения перед внесением в прод.

Итог

Использование directory extension attributes в Entra ID даёт гибкий и контролируемый способ добавлять кастомные claim‑ы в токены при входе. Правильная регистрация атрибутов, аккуратный маппинг и тестирование гарантируют, что данные попадут только к нужной аудитории.

Важно: перед массовым внедрением согласуйте подход с командой безопасности и протестируйте все сценарии входа.

Выпуск пользовательских claims через directory extension в Microsoft Entra ID