Настройка утверждений с помощью пользовательской политики утверждений Microsoft Graph (предварительная версия)

Статья
2025-04-08

Утверждение — это информация, заявленная поставщиком удостоверений о пользователе в токене, выпущенном для этого пользователя. Кастомизация утверждений используется администраторами клиента для настройки утверждений, добавленных в токены, для определенного приложения в своем клиенте. Настройка утверждений поддерживает настройку утверждений для приложений с помощью протоколов SAML, OAuth и OpenID Connect. Вы можете использовать настройку утверждений для:

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

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

Предварительные условия

Клиент Microsoft Entra.
Корпоративное приложение, настроенное в Центре администрирования Microsoft Entra.
Для пользователей PowerShell скачайте последний пакет SDK Для Microsoft Graph PowerShell. Этот шаг необязательный.

Настройка утверждений в идентификаторе Microsoft Entra

Идентификатор Microsoft Entra поддерживает два способа настройки утверждений с помощью Microsoft Graph/PowerShell для приложений:

Использование настраиваемой политики утверждений (предварительная версия)
Использование политики сопоставления утверждений

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

Откройте Microsoft Graph Explorer в браузере войдите в Microsoft Graph Explorer по крайней мере администратором приложений, выберите один из следующих сценариев.

Опустить основные утверждения из токенов
Включите EmployeeID и TenantCountry в качестве утверждений в токены
Используйте преобразование утверждений в токенах

После создания политики настраиваемых утверждений необходимо настроить приложение для подтверждения того, что маркеры содержат настраиваемые утверждения. Дополнительные сведения см. в рекомендациях по безопасности.

Пропуск базовых утверждений из токенов

В этом примере создается настраиваемая политика утверждений, которая удаляет базовый набор утверждений из токенов, выданных связанному субъекту-службе.

В Microsoft Graph Explorer найдите приложение, для которого вы хотите настроить настраиваемую политику утверждений с использованием API субъекта-службы.
Создайте политику настраиваемых утверждений, запустив указанный API. Эта политика, связанная с субъектом-службой, исключает основные утверждения из маркеров.
```
PUT https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy
```
Запрос текста.
```
{
    "includeBasicClaimSet": false
}
```

Чтобы просмотреть новую политику, выполните следующую команду.

GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

Ответ:

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222.",
    "includeBasicClaimSet": false,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": []
}

Включите `EmployeeID` и `TenantCountry` как утверждения в токены

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

В Microsoft Graph Explorer определите приложение, которое вы хотите настроить настраиваемую политику утверждений для использования API субъекта-службы.

Создайте политику пользовательских утверждений, с помощью следующего API-запроса. Эта политика, связанная с субъектом-службой, добавляет утверждения EmployeeID и TenantCountry в маркеры.

PUT https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

Тело запроса.

{
    "includeBasicClaimSet": true,
    "claims": [
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "employeeId",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": [
                {
                    "condition": null,
                    "attribute": {
                        "@odata.type": "#microsoft.graph.sourcedAttribute",
                        "id": " employeeId",
                        "source": "user",
                        "isExtensionAttribute": false
                    },
                    "transformations": []
                }
            ]
        },
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "country",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": [
                {
                    "condition": null,
                    "attribute": {
                        "@odata.type": "#microsoft.graph.sourcedAttribute",
                        "id": " tenantcountry",
                        "source": "user",
                        "isExtensionAttribute": false
                    },
                    "transformations": []
                }
            ]
        }
    ]
}

Чтобы просмотреть новую политику, выполните следующую команду:

GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

Ответ:

{
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "includeBasicClaimSet": true,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": [...]
}

Используйте преобразование утверждений в токенах

В этом примере вы обновляете политику, чтобы добавить пользовательское утверждение "JoinedData" в JWT, выданные подключенным субъектам-службам. Это утверждение содержит значение, созданное путем объединения данных, хранящихся в атрибуте extensionattribute1 в объекте пользователя с "-ext". В этом примере мы исключим набор базовых утверждений из токенов.

В Microsoft Graph Explorer определите приложение, для которого вы хотите настроить пользовательскую политику утверждений с использованием API субъекта-службы.

Создайте настраиваемую политику утверждений, вызвав следующий API. Эта политика вставляет пользовательское утверждение JoinedData в токены.

PATCH https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

Тело запроса.

{
    "includeBasicClaimSet": true,
    "claims": 
    [
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "JoinedData",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": 
            [
                {
                    "condition": null,
                    "attribute": null,
                    "transformations": 
                    [
                        {
                            "@odata.type": "#microsoft.graph.joinTransformation",
                            "separator": "-",
                            "input": 
                            {
                                "treatAsMultiValue": false,
                                "attribute": 
                                {
                                    "@odata.type": "#microsoft.graph.sourcedAttribute",
                                    "id": "extensionattribute1",
                                    "source": "user",
                                    "isExtensionAttribute": false
                                }
                            },
                            "input2": 
                            {
                                "treatAsMultiValue": false,
                                "attribute": 
                                {
                                    "@odata.type":"#microsoft.graph.valueBasedAttribute",
                                    "value": "ext"
                                 }
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

Примечание.

Настраиваемая политика утверждений — это строго типизированная политика, и каждое преобразование использует другое @odata.type значение.

Чтобы увидеть новую политику и получить политику ObjectId, выполните следующую команду:

GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

Ответ:

{
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "includeBasicClaimSet": true,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": [...]
}

Узнайте больше о различиях между политиками в настройке утверждений, используя политику
Входы в систему идентификации Microsoft Graph

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

Настройка утверждений с помощью пользовательской политики утверждений Microsoft Graph (предварительная версия)

Предварительные условия

Настройка утверждений в идентификаторе Microsoft Entra

Пропуск базовых утверждений из токенов

Включите EmployeeID и TenantCountry как утверждения в токены

Используйте преобразование утверждений в токенах

Связанный контент

Обратная связь

Дополнительные ресурсы

Включите `EmployeeID` и `TenantCountry` как утверждения в токены