設定權杖發行事件的自訂宣告提供者

本文說明如何設定權杖發行啟動事件 (部分機器翻譯) 的自訂宣告提供者。 您將使用現有的 Azure Functions REST API 註冊自訂驗證延伸模組，並新增其應該會從 REST API 剖析的屬性。 為了測試自訂驗證延伸模組，您將註冊範例 OpenID Connect 應用程式以取得權杖並檢視宣告。

必要條件

• 能夠建立 Azure Functions 的 Azure 訂用帳戶。 如果您沒有現有的 Azure 帳戶，請註冊免費試用帳戶，或是在建立帳戶時使用 Visual Studio 訂用帳戶權益。
• 為部署至 Azure Functions 的權杖發行事件所設定的 HTTP 觸發程序函式。 如果您沒有這樣的函式，請遵循在 Azure Functions 中建立權杖發行啟動事件的 REST API (部分機器翻譯) 中的步驟。
• 對自訂驗證延伸模組概觀 (部分機器翻譯) 中所涵蓋的概念有基本了解。
• Microsoft Entra ID 租用戶。 您可以使用客戶或員工租用戶來進行本操作指南。
  • 若為外部租用戶，請使用註冊和登入使用者流程。

步驟 1：註冊自訂驗證延伸模組

您現在會設定自訂驗證延伸模組，以供 Microsoft Entra ID 用來呼叫您的 Azure 函式。 自訂驗證延伸模組包含您 REST API 端點的相關資訊、其從您的 REST API 剖析的宣告，以及如何向您的 REST API 進行驗證。 請遵循下列步驟，向 Azure 函式應用程式註冊自訂驗證延伸模組。

注意

您最多可以有 100 個自訂延伸模組原則。

Azure 入口網站

註冊自訂驗證延伸模組

1. 至少以應用程式系統管理員 (部分機器翻譯) 和驗證系統管理員 (部分機器翻譯) 身分登入 Azure 入口網站。
2. 搜尋並選取 [Microsoft Entra ID]，然後選取 [企業應用程式]。
3. 選取 [自訂驗證延伸模組]，然後選取 [建立自訂延伸模組]。
4. 在 [基本資料] 中，選取 [TokenIssuanceStart] 事件類型，然後選取 [下一步]。
5. 在 [端點設定] 中，填入下列屬性：
   • [名稱]：自訂驗證延伸模組的名稱。 例如，「權杖發行事件」。
   • 目標 URL - Azure 函式 URL 的 {Function_Url}。 瀏覽至 Azure 函式應用程式的 [概觀] 頁面，然後選取您建立的函式。 在函式 [概觀] 頁面中，選取 [取得函式 URL]，並使用複製圖示來複製「customauthenticationextension_extension (系統金鑰)」URL。
   • 描述 - 自訂驗證延伸模組的描述。
6. 選取 [下一步]。
7. 在 [API 驗證] 中，選取 [建立新的應用程式註冊] 選項，以建立代表您函式應用程式的應用程式註冊。
8. 為應用程式命名，例如 Azure Functions 驗證事件 API。
9. 選取 [下一步]。
10. 在 [宣告] 中，輸入您預期自訂驗證延伸模組要從您的 REST API 剖析並且會合併到權杖中的的屬性。 新增下列宣告：
    • dateOfBirth
    • customRoles
    • apiVersion
    • correlationId
11. 選取 [下一步]，然後選取 [建立]，以註冊自訂驗證延伸模組和相關聯的應用程式註冊。
12. 記下 [API 驗證] 底下的 [應用程式識別碼]，需要此識別碼才能在 Azure 函式應用程式中為 Azure 函式設定驗證 (部分機器翻譯)。

Microsoft Graph

註冊應用程式

1. 使用帳戶來登入 Graph 總管，這個帳戶的主租用戶必須是您想要在其中管理自訂驗證延伸模組的租用戶。 此帳戶必須具有能在租用戶中建立和管理應用程式註冊的權限。

2. 執行下列要求。

   POST https://graph.microsoft.com/v1.0/applications
   Content-type: application/json
   
   {
       "displayName": "authenticationeventsAPI"
   }
   

3. 從回應中，記錄新建應用程式註冊的「id」和「appId」值。 本文會分別將這兩個值參考為 {authenticationeventsAPI_ObjectId} 和 {authenticationeventsAPI_AppId}。

在租用戶中為 authenticationeventsAPI 應用程式註冊建立服務主體。

在 Graph 總管中執行下列要求。 將 {authenticationeventsAPI_AppId} 更換為您在上一個步驟中記錄的 appId 值。

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json
    
{
    "appId": "{authenticationeventsAPI_AppId}"
}

設定應用程式識別碼 URI、存取權杖版本和所需的資源存取權

更新新建立的應用程式，以設定應用程式識別碼 URI 值、存取權杖版本和所需的資源存取權。

在 Graph 總管中執行下列要求。

• 在 identifierUris 屬性中設定應用程式識別碼 URI 值。 將 {Function_Url_Hostname} 更換為稍早記錄的 {Function_Url} 主機名稱。
• 使用稍早記錄的 appId 設定 {authenticationeventsAPI_AppId} 值。
• 範例值為 api://authenticationeventsAPI.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444。 請記下此值，因為您會在本文稍後的地方使用此值來取代 {functionApp_IdentifierUri}。

POST https://graph.microsoft.com/v1.0/applications/{authenticationeventsAPI_ObjectId}
Content-type: application/json

{
"identifierUris": [
    "api://{Function_Url_Hostname}/{authenticationeventsAPI_AppId}"
],    
"api": {
    "requestedAccessTokenVersion": 2,
    "acceptMappedClaims": null,
    "knownClientApplications": [],
    "oauth2PermissionScopes": [],
    "preAuthorizedApplications": []
},
"requiredResourceAccess": [
    {
        "resourceAppId": "00000003-0000-0000-c000-000000000000",
        "resourceAccess": [
            {
                "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                "type": "Role"
            }
        ]
    }
]
}

註冊自訂驗證延伸模組

若要註冊自訂驗證延伸模組，請將其與 Azure 函式的應用程式註冊以及您的 Azure 函式端點 {Function_Url} 產生關聯。

1. 在 Graph 總管中執行下列要求。 將 {Function_Url} 更換為您 Azure 函數應用程式的主機名稱。 將 {functionApp_IdentifierUri} 更換為上個步驟中使用的 identifierUri。

   • 您需要「CustomAuthenticationExtension.ReadWrite.All」委派權限。

   POST https://graph.microsoft.com/beta/identity/customAuthenticationExtensions
   Content-type: application/json
   
   {
       "@odata.type": "#microsoft.graph.onTokenIssuanceStartCustomExtension",
       "displayName": "onTokenIssuanceStartCustomExtension",
       "description": "Fetch additional claims from custom user store",
       "endpointConfiguration": {
           "@odata.type": "#microsoft.graph.httpRequestEndpoint",
           "targetUrl": "{Function_Url}"
       },
       "authenticationConfiguration": {
           "@odata.type": "#microsoft.graph.azureAdTokenAuthentication",
           "resourceId": "{functionApp_IdentifierUri}"
       },
       "claimsForTokenConfiguration": [
           {
               "claimIdInApiResponse": "DateOfBirth"
           },
           {
               "claimIdInApiResponse": "CustomRoles"
           }
       ]
   }
   

2. 記錄所建立自訂宣告提供者物件的 id 值。 您會在本教學課程稍後的地方使用此值來取代 {customExtensionObjectId}。

1.2 授與管理員同意

在建立自訂驗證延伸模組後，必須向 API 授與權限。 自訂驗證延伸模組會使用 client_credentials，透過 Receive custom authentication extension HTTP requests 權限向 Azure 函式應用程式進行驗證。

1. 開啟新自訂驗證延伸模組的 [概觀] 頁面。 請記下 [API 驗證] 底下的 [應用程式識別碼]，因為在新增識別提供者時需要用到。

2. 在 [API 驗證] 底下，選取 [授與權限]。

3. 隨即會開啟新的視窗，一旦登入，其便會要求用來接收自訂驗證延伸模組 HTTP 要求的權限。 這可讓自訂驗證延伸模組向 API 進行驗證。 選取 [接受]。

   

步驟 2：設定 OpenID Connect 應用程式以接收擴充的權杖

若要取得權杖並測試自訂驗證延伸模組，您可以使用 https://jwt.ms 應用程式。 這是 Microsoft 擁有的 Web 應用程式，會顯示已解碼的權杖內容 (權杖內容永遠不會離開您的瀏覽器)。

2.1 註冊測試 Web 應用程式

請遵循下列步驟來註冊 jwt.ms Web 應用程式：

1. 從 Azure 入口網站的 [首頁] 頁面中，選取 [Microsoft Entra ID]。

2. 選取 [應用程式註冊]>[新增註冊]。

3. 輸入應用程式的 [名稱]。 例如，My Test application。

4. 在 [支援的帳戶類型] 底下，選取 [僅在此組織目錄中的帳戶]。

5. 在 [重新導向 URI] 的 [選取平台] 下拉式清單中選取 [Web]，然後在 URL 文字輸入框中輸入 https://jwt.ms。

6. 選取 [註冊] 完成應用程式註冊。

   

7. 在應用程式註冊的 [概觀] 頁面中，複製 [應用程式 (用戶端) 識別碼]。 後續步驟會將應用程式識別碼稱為 {App_to_enrich_ID}。 在 Microsoft Graph 中，此即為 appId 屬性。

   

2.2 啟用隱含流程

jwt.ms 測試應用程式會使用隱含流程。 在我的測試應用程式註冊中啟用隱含流程：

1. 在 [管理] 底下，選取 [驗證]。
2. 在 [Implicit grant and hybrid flows] \(隱含授與和混合式流程\) 下，選取 [ID tokens (used for implicit and hybrid flows)] \(識別碼權杖 (用於隱含和混合式流程)\) 核取方塊。
3. 選取 [儲存]。

2.3 為宣告對應原則啟用您的應用程式

宣告對應原則可用來選取哪些從自訂驗證延伸模組傳回的屬性會對應至權杖。 若要允許增加權杖，您必須明確啟用應用程式註冊以接受對應的宣告：

1. 在「我的測試應用程式」註冊中，於 [管理] 底下，選取 [資訊清單]。
2. 在資訊清單中，找出 acceptMappedClaims 屬性，並將值設定為 true。
3. 將 accessTokenAcceptedVersion 設定為 2。
4. 選取儲存以儲存變更。

下列 JSON 程式碼片段會示範如何設定這些屬性。

{
	"id": "22222222-0000-0000-0000-000000000000",
	"acceptMappedClaims": true,
	"accessTokenAcceptedVersion": 2,  
    ...
}

警告

若為多租用戶應用程式，請不要將 acceptMappedClaims 屬性設定為 true，此舉可讓惡意執行者為您的應用程式建立宣告對應原則。 請改為設定自訂簽署金鑰。

員工租用戶

繼續進行下一個步驟：將自訂宣告提供者指派給您的應用程式。

外部租用戶

3.4 將您的應用程式與使用者流程產生關聯

若為外部租用戶，您必須將應用程式與使用者流程產生關聯。 使用者流程會定義客戶可用來登入應用程式的驗證方法，以及他們在註冊期間所需提供的資訊。 請務必先完成將應用程式新增至使用者流程中的步驟，再繼續將「我的測試應用程式」新增至使用者流程。

步驟 3：將自訂宣告提供者指派給您的應用程式

若要使用來自自訂驗證延伸模組的宣告來發行權杖，您必須將自訂宣告提供者指派給應用程式。 這會以權杖對象作為基礎，因此必須將提供者指派給用戶端應用程式以接收識別碼權杖中的宣告，以及指派給資源應用程式以接收存取權杖中的宣告。 自訂宣告提供者會依賴使用權杖發行啟動事件接聽程式所設定的自訂驗證延伸模組。 您可以選擇是要將自訂宣告提供者中的所有宣告還是宣告子集對應至權杖。

注意

您只能在應用程式與自訂延伸模組之間建立 250 個唯一指派。 如果您想要將相同的自訂延伸模組呼叫套用至多個應用程式，建議您使用 authenticationEventListeners (英文) Microsoft Graph API 來為多個應用程式建立接聽程式。 Azure 入口網站不支援此操作。

請遵循下列步驟，使用您的自訂驗證延伸模組來進行「我的測試應用程式」連線：

Azure 入口網站

若要將自訂驗證延伸模組指派為自訂宣告提供者來源;

1. 從 Azure 入口網站的 [首頁] 頁面中，選取 [Microsoft Entra ID]。

2. 選取 [企業應用程式]，然後在 [管理] 底下，選取 [所有應用程式]。 從清單中尋找並選取 [我的測試應用程式]。

3. 從 [我的測試應用程式] 的 [概觀] 頁面中，瀏覽至 [管理]，然後選取 [單一登入]。

4. 在 [屬性與宣告] 底下，選取 [編輯]。

   

5. 展開 [進階設定] 功能表。

6. 選取 [自訂宣告提供者] 旁邊的 [設定]。

7. 展開 [自訂宣告提供者] 下拉式方塊，然後選取您稍早建立的 [權杖發行事件]。

8. 選取 [儲存]。

接下來，指派自訂宣告提供者中的屬性，這應會以宣告的形式發行至權杖：

1. 選取 [新增宣告] 以新增宣告。 提供您想要發行之宣告的名稱，例如 dateOfBirth。

2. 在 [來源] 底下，選取 [屬性]，然後從 [來源屬性] 下拉式方塊中選擇 [customClaimsProvider.dateOfBirth]。

   

3. 選取 [儲存]。

4. 重複此程序以新增 customClaimsProvider.customRoles、customClaimsProvider.apiVersion 和 customClaimsProvider.correlationId 屬性，以及對應的名稱。 宣告名稱與屬性名稱相符會比較好。

Microsoft Graph

首先，建立事件接聽程式，以使用權杖發行啟動事件來觸發「我的測試應用程式」的自訂驗證延伸模組。

1. 使用帳戶登入 Graph 總管，這個帳戶的主租用戶是您想要用來管理自訂驗證延伸模組的租用戶。

2. 執行下列要求。 將 {App_to_enrich_ID} 更換為稍早記錄之「我的測試應用程式」的應用程式識別碼。 將 {customExtensionObjectId} 更換為稍早記錄的自訂驗證延伸模組識別碼。

   • 您需要 EventListener.ReadWrite.All 委派權限。

   POST https://graph.microsoft.com/beta/identity/authenticationEventListeners
   Content-type: application/json
   
   {
       "@odata.type": "#microsoft.graph.onTokenIssuanceStartListener",
       "conditions": {
           "applications": {
               "includeAllApplications": false,
               "includeApplications": [
                   {
                       "appId": "{App_to_enrich_ID}"
                   }
               ]
           }
       },
       "priority": 500,
       "handler": {
           "@odata.type": "#microsoft.graph.onTokenIssuanceStartCustomExtensionHandler",
           "customExtension": {
               "id": "{customExtensionObjectId}"
           }
       }
   }
   

接下來，建立宣告對應原則，描述哪些宣告可以從自訂宣告提供者發行至應用程式。

1. 還是在 Graph 總管中執行下列要求。 您會需要 Policy.ReadWrite.ApplicationConfiguration 委派權限。

   POST https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies
   Content-type: application/json
   
   {
       "definition": [
           "{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"CustomClaimsProvider\",\"ID\":\"DateOfBirth\",\"JwtClaimType\":\"dob\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"CustomRoles\",\"JwtClaimType\":\"my_roles\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"CorrelationId\",\"JwtClaimType\":\"correlationId\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"ApiVersion\",\"JwtClaimType\":\"apiVersion \"},{\"Value\":\"tokenaug_V2\",\"JwtClaimType\":\"policy_version\"}]}}"
       ],
       "displayName": "MyClaimsMappingPolicy",
       "isOrganizationDefault": false
   }
   

2. 記錄回應中產生的 ID，稍後我們會將其稱為 {claims_mapping_policy_ID}。

取得服務主體物件識別碼：

1. 在 Graph 總管中執行下列要求。 將 {App_to_enrich_ID} 更換為「我的測試應用程式」的 appId。

   GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='{App_to_enrich_ID}')
   

記錄 id 的值。

將宣告對應原則指派給「我的測試應用程式」的服務主體。

1. 在 Graph 總管中執行下列要求。 您會需要 Policy.ReadWrite.ApplicationConfiguration 和 Application.ReadWrite.All 委派權限。

   POST https://graph.microsoft.com/v1.0/servicePrincipals/{test_App_Service_Principal_ObjectId}/claimsMappingPolicies/$ref
   Content-type: application/json
   
   {
       "@odata.id": "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/{claims_mapping_policy_ID}"
   }
   

步驟 4：保護您的 Azure 函式

Microsoft Entra 自訂驗證延伸模組會使用伺服器對伺服器流程，來取得在 HTTP Authorization 標頭中傳送至 Azure 函式的存取權杖。 將函式發佈至 Azure 時，特別是在生產環境時，您需要驗證在授權標頭中傳送的權杖。

若要保護您的 Azure 函式，請遵循下列步驟來整合 Microsoft Entra 驗證，以驗證隨「Azure Functions 驗證事件 API」應用程式註冊傳入的權杖。 根據您的租用戶類型，選擇下列其中一個索引標籤。

注意

如果 Azure 函式應用程式裝載所在的 Azure 租用戶，和您註冊自訂驗證延伸模組時所在的租用戶不同，請選擇 [OpenID Connect] 索引標籤。

4.1 使用 Microsoft Entra 識別提供者

使用下列步驟，將 Microsoft Entra ID 新增為 Azure 函式應用程式的識別提供者。

員工租用戶

1. 在 Azure 入口網站中，尋找並選取您先前發佈的函式應用程式。

2. 選取 [設定] 下方的 [驗證]。

3. 選取 [新增識別提供者]。

4. 識別提供者選取 [Microsoft]。

5. 租用戶類型選取 [員工]。

6. 在 [應用程式註冊] 底下，選取 [在此目錄中挑選現有的應用程式註冊] 作為 [應用程式註冊類型]，然後挑選您先前在註冊自訂宣告提供者時建立的 [Azure Functions 驗證事件 API] 應用程式註冊。

7. 輸入下列簽發者 URL：https://login.microsoftonline.com/{tenantId}/v2.0，其中 {tenantId} 是員工租用戶的租用戶識別碼。

8. 在 [用戶端應用程式需求] 下，選取 [允許來字特定用戶端應用程式的要求]，然後輸入 99045fe1-7639-4a75-9d4a-577b6ca3810f。

9. 在 [租用戶需求] 下，選取 [允許來自特定租用戶的要求]，然後輸入員工租用戶識別碼。

10. 在 [未驗證的要求] 底下，選取 [HTTP 401 未授權] 作為識別提供者。

11. 取消選取 [權杖存放區] 選項。

12. 選取 [新增] 以將驗證新增至您的 Azure 函式。

    

外部租用戶

1. 在 Azure 入口網站中，尋找並選取您先前發佈的函式應用程式。

2. 選取 [設定] 下方的 [驗證]。

3. 選取 [新增識別提供者]。

4. 選取 Microsoft 作為識別提供者。

5. 選取 外部設定 作為租用戶類型。

6. 在應用程式註冊下，選取提供現有應用程式註冊的詳細資訊作為應用程式註冊類型，並輸入 Azure Functions 驗證事件 API 的 client_id —您 先前在註冊自訂宣告提供者時建立的應用程式註冊。

7. 針對 [簽發者 URL]，輸入下列 URL：https://{domainName}.ciamlogin.com/{tenant_id}/v2.0，其中

   • {domainName} 是外部租用戶的網域名稱，格式為 {domainName}.contoso.com。
   • {tenantId} 是外部租用戶的租用戶識別碼。

8. 在 [用戶端應用程式需求] 下，選取 [允許來字特定用戶端應用程式的要求]，然後輸入 99045fe1-7639-4a75-9d4a-577b6ca3810f。

9. 在 租使用者需求下，選取 允許來自特定租用戶的要求 ，然後輸入您的外部租用戶識別碼。

10. 在 [未驗證的要求] 底下，選取 [HTTP 401 未授權] 作為識別提供者。

11. 取消選取 [權杖存放區] 選項。

12. 選取 [新增] 以將驗證新增至您的 Azure 函式。

    

4.2 使用 OpenID Connect 識別提供者

如果您已設定 Microsoft 識別提供者，請略過此步驟。 否則，如果 Azure 函式裝載所在的租用戶和您註冊自訂驗證延伸模組時所在的租用戶不同，請遵循下列步驟來保護您的函式：

建立用戶端密碼

1. 從 Azure 入口網站的 [首頁] 頁面中，選取 [Microsoft Entra ID]>[應用程式註冊]。
2. 選取您先前建立的 [Azure Functions 驗證事件 API] 應用程式註冊。
3. 選取 [憑證和祕密]>[用戶端密碼]>[新增用戶端密碼]。
4. 選取祕密的到期日或指定自訂存留期、新增描述，然後選取 [新增]。
5. 記錄祕密的值，以在用戶端應用程式的程式碼中使用。 離開此頁面後，就「不會再次顯示」此祕密值。

將 OpenID Connect 識別提供者新增至您的 Azure 函式應用程式。

1. 尋找並選取您先前發佈的函式應用程式。

2. 選取 [設定] 下方的 [驗證]。

3. 選取 [新增識別提供者]。

4. 選取 [OpenID Connect] 作為識別提供者。

5. 提供名稱，例如 Contoso Microsoft Entra ID。

6. 在 [中繼資料項目] 底下，將下列 URL 輸入至 [文件 URL]。 將 {tenantId} 更換為您的 Microsoft Entra tenant ID。

   https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration
   

7. 在 [應用程式註冊] 底下，輸入您先前建立之「Azure Functions 驗證事件 API」應用程式註冊的應用程式識別碼 (用戶端識別碼)。

8. 返回 Azure 函式，在 [應用程式註冊] 底下，輸入用戶端密碼。

9. 取消選取 [權杖存放區] 選項。

10. 選取 [新增] 以新增 OpenID Connect 識別提供者。

步驟 5：測試應用程式

若要測試您的自訂宣告提供者，請遵循下列步驟：

員工租用戶

1. 開啟新的私人瀏覽器，進行瀏覽並透過下列 URL 來登入。

   https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize?client_id={App_to_enrich_ID}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345
   

2. 將 {tenantId} 更換為您的租用戶識別碼、租用戶名稱或其中一個已驗證的網域名稱。 例如： contoso.onmicrosoft.com 。

3. 將 {App_to_enrich_ID} 取代為「我的測試應用程式」的用戶端識別碼。

4. 登入之後，您會在 https://jwt.ms 看到已解碼的權杖。 驗證來自 Azure 函式的宣告出現在已解碼的權杖中，例如 dateOfBirth。

外部租用戶

1. 開啟新的私人瀏覽器，瀏覽至下列 URL 登入。

   https://{domainName}.ciamlogin.com/{tenantId}/oauth2/v2.0/authorize?client_id={App_to_enrich_ID}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345
   

2. 將 {domainName} 更換為您的網域名稱，例如 contoso。

3. 將 {tenantId} 更換為您的租用戶識別碼、租用戶名稱或其中一個已驗證的網域名稱。 例如： contoso.onmicrosoft.com 。

4. 將 {App_to_enrich_ID} 更換為「我的測試應用程式」的用戶端識別碼。

5. 瀏覽您已設定的登入使用者流程，並接受所要求的權限。

6. 登入之後，您會在 https://jwt.ms 看到已解碼的權杖。 驗證來自 Azure 函式的宣告出現在已解碼的權杖中，例如 dateOfBirth。

另請參閱

• 設定 SAML 應用程式接收具有來自外部存放區宣告的權杖
• 自訂宣告提供者參考
• 針對自訂驗證延伸模組 API 進行疑難排解