Справочник по специальным утверждениям от поставщика

2025-05-25

В этом руководстве вы узнаете о схеме REST API и структуре политики сопоставления утверждений для событий пользовательского поставщика утверждений.

Событие начала эмиссии токена

Событие выпуска токенов кастомного провайдера утверждений позволяет обогатить или настроить токены приложений с информацией из внешних систем. Сведения, которые нельзя хранить в профиле пользователя в каталоге Microsoft Entra.

Обзор компонентов

Чтобы настроить и интегрировать пользовательское расширение с приложением, необходимо подключить несколько компонентов. На следующей схеме показано высокоуровневое представление точек конфигурации и связей, созданных для реализации пользовательского расширения.

У вас должен быть общедоступный REST API endpoint. На этой схеме она представлена функцией Azure. REST API создает и возвращает пользовательские утверждения для пользовательского расширения. Он связан с регистрацией приложения Microsoft Entra.
Необходимо настроить пользовательское расширение в идентификаторе Microsoft Entra, которое настроено для подключения к API.
Требуется приложение , которое получает настраиваемые маркеры. Например https://jwt.ms веб-приложение, принадлежащее Майкрософт, которое отображает декодированное содержимое токена.
Приложение, например https://jwt.ms, должно быть зарегистрировано в Microsoft Entra ID с помощью регистрации приложения.
Необходимо создать связь между приложением и пользовательским расширением.
Вы также можете защитить функцию Azure с помощью поставщика проверки подлинности, в этой статье мы используем идентификатор Microsoft Entra.

REST API

Конечная точка REST API отвечает за взаимодействие с подчиненными службами. Например, базы данных, другие REST API, каталоги LDAP или любые другие хранилища, содержащие атрибуты, которые нужно добавить в конфигурацию маркера.

REST API возвращает HTTP-ответ на идентификатор Microsoft Entra, содержащий атрибуты. Атрибуты, возвращаемые REST API, не добавляются в токен автоматически. Вместо этого необходимо настроить политику сопоставления утверждений приложения для включения любого атрибута в токен. В Microsoft Entra ID политика сопоставления утверждений изменяет утверждения, которые включены в токены, выданные для определенных приложений.

Запрос к REST API

Чтобы разработать собственный REST API для события запуска выпуска токенов, используйте следующий контракт на данные REST API. Схема описывает контракт для проектирования обработчика запроса и ответа.

Пользовательское расширение в Microsoft Entra ID выполняет HTTP-вызов к вашему REST API с загрузкой данных в формате JSON. Полезная нагрузка JSON содержит данные профиля пользователя, атрибуты контекста аутентификации и информацию о приложении, в которое пользователь хочет войти в систему. Значение id в следующем формате JSON — это приложение Майкрософт, представляющее службу событий проверки подлинности Microsoft Entra. Атрибуты JSON можно использовать для выполнения дополнительной логики API.

В следующем HTTP-запросе показано, как Microsoft Entra вызывает REST API. Этот HTTP-запрос можно использовать для отладки REST API путем имитации запроса из Microsoft Entra.

POST https://your-api.com/endpoint

Content-Type: application/json

[Request payload]

В следующем документе JSON приведен пример данных для запроса.

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/<Your tenant GUID>/applications/<Your Test Application App Id>",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "<Your tenant GUID>",
        "authenticationEventListenerId": "<GUID>",
        "customAuthenticationExtensionId": "<Your custom extension ID>",
        "authenticationContext": {
            "correlationId": "<GUID>",
            "client": {
                "ip": "30.51.176.110",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "user": {
                "companyName": "Casey Jensen",
                "createdDateTime": "2016-03-01T15:23:40Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "90847c2a-e29d-4d2f-9f54-c5b4d3f26471", 
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

Когда пользователь B2B из организации Fabrikam аутентифицируется в организации Contoso, полезные данные запроса, отправляемые в REST API, содержат элемент user в следующем формате:

"user": {
    "companyName": "Fabrikam",
    "createdDateTime": "2022-07-15T00:00:00Z",
    "displayName": "John Wright",
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "mail": "johnwright@fabrikam.com",
    "preferredDataLocation": "EUR",
    "userPrincipalName": "johnwright_fabrikam.com#EXT#@contoso.onmicrosoft.com",
    "userType": "Guest"
}

Ответ от REST API

Microsoft Entra ID ожидает ответ REST API в следующем формате HTTP.

HTTP/1.1 200 OK

Content-Type: application/json

[JSON document]

В ответе HTTP укажите следующий документ JSON, где утверждения DateOfBirth и CustomRoles возвращаются в Microsoft Entra:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "DateOfBirth": "01/01/2000",
                    "CustomRoles": [
                        "Writer",
                        "Editor"
                    ]
                }
            }
        ]
    }
}

Поддерживаемые типы данных

В следующей таблице показаны типы данных, поддерживаемые пользовательскими поставщиками утверждений для события начала выпуска токена:

Тип данных	Поддерживается
Строка	Истина
Массив строк	Истина
Логический	Неверно
JSON (JavaScript Object Notation)	Неверно

Ограничения размера утверждений

Максимальный размер утверждения, который может возвращать поставщик утверждений, ограничен до 3 КБ. Это сумма всех пар ключей и значений, возвращаемых REST API.

Политика сопоставления утверждений

В Microsoft Entra ID политика сопоставления утверждений изменяет утверждения, которые включены в токены, выданные для определенных приложений. Он включает утверждения от пользовательского поставщика утверждений и их включение в токен.

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "true",
        "ClaimsSchema": [{
            "Source": "CustomClaimsProvider",
            "ID": "dateOfBirth",
            "JwtClaimType": "birthdate"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "customRoles",
            "JwtClaimType": "my_roles"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "correlationId",
            "JwtClaimType": "correlation_Id"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "apiVersion",
            "JwtClaimType": "apiVersion"
        },
        {
            "Value": "tokenaug_V2",
            "JwtClaimType": "policy_version"
        }]
    }
}

Элемент ClaimsSchema содержит список утверждений, сопоставленных со следующими атрибутами:

Источник описывает источник атрибута.CustomClaimsProvider Обратите внимание, что последний элемент содержит фиксированное значение с версией политики для тестирования. Таким образом, source атрибут опущен.
Идентификатор — это имя утверждений, возвращаемых из созданной функции Azure.

Внимание

Значение атрибута ID чувствительно к регистру. Убедитесь, что вы вводите имя утверждения в том же виде, как оно представлено функцией Azure.
JwtClaimType — это необязательное имя утверждения в создаваемом токене для приложения OpenID Connect. Он позволяет указать другое имя, которое возвращается в токене JWT. Например, если ответ API имеет ID значение dateOfBirth, оно может быть использовано в виде birthdate внутри токена.

После создания политики сопоставления утверждений следующий шаг — загрузить её в клиентский сегмент Microsoft Entra. Используйте следующий Graph API claimsMappingPolicy в вашем тенанте.

Внимание

Элемент определения должен быть массивом с одним строковым значением. Строка должна быть строкифицированной и escape-версией политики сопоставления утверждений. Вы можете использовать такие средства, как https://jsontostring.com/, чтобы преобразовать политику сопоставления утверждений в строку.