使用 Microsoft Graph 自訂宣告原則自訂宣告（預覽）

發行項
06/28/2024

宣告是識別提供者在發給使用者的權杖內用以描述使用者的資訊。租用戶系統管理員會使用自訂宣告，以針對其租用戶的特定應用程式自訂權杖中所發出的宣告。宣告自定義支援使用 SAML、OAuth 和 OpenID Connect 通訊協定來設定應用程式的宣告。您可以使用宣告自訂來：

選取令牌中包含哪些宣告。
建立不存在的宣告類型。
選擇或變更特定宣告中發出的數據源。

在本操作指南中，我們會討論幾個常見案例，可協助您瞭解如何使用自定義宣告原則。

必要條件

Microsoft Entra 租用戶。
Microsoft Entra 系統管理中心所設定的企業應用程式。
針對 PowerShell 使用者，下載最新的 Microsoft Graph PowerShell SDK。此為選用步驟。

Microsoft Entra 識別碼中的宣告自定義

Microsoft Entra ID 支援兩種方式，針對您的應用程式使用 Microsoft Graph/PowerShell 來自定義宣告：

使用自訂宣告原則（預覽）
使用宣告對應原則

在下列範例中，您會建立、更新和取代服務主體的原則。自定義宣告原則一律會連結至服務主體物件。在為應用程式/服務主體建立自定義宣告原則之前，請確定您已將企業應用程式設定為必要條件的一部分。

在瀏覽器中開啟 Microsoft Graph 總管以至少應用程式管理員身分登入 Microsoft Graph 總管，選擇下列其中一個案例。

省略權杖中的基本宣告
在權杖中包括 EmployeeID 和 TenantCountry 做為宣告
在權杖中使用宣告轉換

建立自定義宣告原則之後，您應該將應用程式設定為確認令牌包含自定義宣告。如需詳細資訊，請參閱安全性考慮。

省略權杖中的基本宣告

在此範例中，您會建立自定義宣告原則，從核發至連結服務主體的令牌中移除基本宣告集。

在 Microsoft Graph 總管中，識別您想要設定使用服務主體 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` 作為宣告

在此範例中，您會建立對將和 TenantCountry 新增EmployeeID至令牌之宣告的自定義。在此範例中，我們也會在令牌中包含基本宣告集。

在 Microsoft Graph 總管中，識別您想要設定使用服務主體 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 總管中，識別您想要設定使用服務主體 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` 作為宣告

在權杖中使用宣告轉換

意見反應

其他資源

共用方式為

使用 Microsoft Graph 自訂宣告原則自訂宣告 （預覽）

必要條件

Microsoft Entra 識別碼中的宣告自定義

省略權杖中的基本宣告

在權杖中包含 EmployeeID 和 TenantCountry 作為宣告

在權杖中使用宣告轉換

相關內容

意見反應

其他資源

使用 Microsoft Graph 自訂宣告原則自訂宣告（預覽）

在權杖中包含 `EmployeeID` 和 `TenantCountry` 作為宣告