Справочник по поставщику пользовательских утверждений

Статья
02/06/2024

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

Событие запуска выдачи маркера

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

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

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

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

REST API

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

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

Схема REST API

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

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

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

{
    "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", // Client ID representing the Microsoft Entra authentication events service
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

Формат ответа REST API, который ожидаетСя в Azure, находится в следующем формате, где утверждения DateOfBirth и CustomRoles возвращаются в Azure:

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

Когда пользователь 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"
}

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

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

Тип данных	Поддерживается
Строка	Истина
Массив строк	Истина
Логический	False
JSON	False

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

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

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

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

{
    "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.

Внимание

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

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

Внимание

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

Поделиться через