自訂宣告提供者參考

發行項
07/31/2024

在本參考文章中，您可以了解自訂宣告提供者事件的 REST API 結構描述和宣告對應原則結構。

權杖發行開始事件

自訂宣告提供者權杖發行事件可讓您使用外部系統的資訊來擴充或自訂應用程式權杖。這項資訊無法儲存為 Microsoft Entra 目錄中使用者設定檔的一部分。

元件概觀

若要設定並將自訂延伸模組與您的應用程式整合，需要連線多個元件。下圖顯示組態點的概觀檢視，以及建立以實作自訂延伸模組的關聯性。

您應該已公開提供 REST API 端點。在此圖表中，它由 Azure 函式表示。 REST API 會產生自訂宣告，並將自訂宣告傳回至自訂延伸模組。它與 Microsoft Entra 應用程式註冊相關聯。
您必須在 Microsoft Entra ID 中設定已設定為連線到您 API 的自訂延伸模組。
您需要接收自訂權杖的應用程式。例如 Microsoft擁有的 Web 應用程式 https://jwt.ms，其中顯示已解碼的權杖內容。
應用程式如 https://jwt.ms，必須使用應用程式註冊，以註冊至 Microsoft Entra ID。
您必須建立應用程式與自訂延伸模組之間的關聯。
您可以選擇性地使用驗證提供者保護 Azure 函式，在本文中，我們會使用您的 Microsoft Entra ID。

REST API

REST API 端點負責與下游服務進行互動。例如資料庫、其他 REST API、LDAP 目錄或任何其他存放區，包含您想要新增至權杖組態的屬性。

REST API 會將 HTTP 回應傳回至包含屬性的 Microsoft Entra ID。 REST API 傳回的屬性不會自動新增至權杖中。相反地，必須針對要包含在權杖中的任何屬性設定應用程式的宣告對應原則。在 Microsoft Entra ID 中，宣告對應原則會修改針對特定應用程式所發行權杖中發出的宣告。

REST API 結構描述

若要針對權杖發行開始事件開發您自己的 REST API，請使用下列 REST API 資料合約。結構描述說明設計要求和回應處理常式的合約。

您在 Microsoft Entra ID 中的自訂延伸模組會使用 JSON 承載對 REST API 發出 HTTP 呼叫。 JSON 承載包含使用者設定檔資料、驗證內容屬性，以及使用者想要登入之應用程式的相關資訊。下列 JSON 中的 id 值是 Microsoft 應用程式，代表 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"
            }
        }
    }
}

Azure 預期的 REST API 回應格式為下列格式，其中宣告 DateOfBirth 和 CustomRoles 會傳回至 Azure：

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

當來自 Fabrikam 組織的 B2B 使用者向 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"
}

支援的資料類型

下表顯示自訂宣告提供者針對權杖發行開始事件所支援的資料類型：

資料類型	支援
String	True
字串陣列	True
Boolean	False
JSON	False

宣告大小限制

宣告提供者可以傳回的宣告大小上限為 3KB。這是 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 函式傳回的宣告名稱。

重要

識別碼屬性的值區分大小寫。請確定您輸入的宣告名稱與 Azure 函式所傳回的宣告名稱完全相同。
JwtClaimType 是 OpenID Connect 應用程式的發出權杖中宣告的選擇性名稱。它可讓您提供在 JWT 權杖中傳回的不同名稱。例如，如果 API 回應具有 dateOfBirth 的 ID 值，則可以在權杖中將其發出為 birthdate。

建立宣告對應原則之後，下一個步驟是將其上傳至您的 Microsoft Entra 租用戶。在您的租用戶中使用下列 claimsMappingPolicy 圖形 API。

重要

定義元素應該是具有單一字串值的陣列。字串應該是宣告對應原則的字串化和逸出版本。您可以使用 https://jsontostring.com/ 之類的工具來將宣告對應原則字串化。

共用方式為