設定令牌發行事件的自定義宣告提供者
本文說明如何設定 令牌發行開始事件的自定義宣告提供者。 使用現有的 Azure Functions REST API，您將註冊自定義驗證延伸模組，並新增預期從 REST API 剖析的屬性。 若要測試自定義驗證延伸模組，您將註冊範例 OpenID 連線 應用程式，以取得令牌並檢視宣告。
必要條件
- 能夠建立 Azure Functions 的 Azure 訂用帳戶。 如果您沒有現有的 Azure 帳戶，請在建立帳戶時註冊免費試用或使用 Visual Studio 訂用帳戶權益。
- 已針對令牌發行啟動事件設定 HTTP 觸發程式函式的 Azure 函式應用程式。 如果您沒有令牌發行啟動事件 HTTP 觸發程式函式中的步驟，請遵循建立令牌發行啟動事件 HTTP 觸發程式函式中的步驟。
- 對自定義驗證延伸模組概觀中涵蓋的概念有基本瞭解。
- Microsoft Entra ID 租使用者。 您可以使用客戶或員工租用戶來進行本操作指南。
- 針對外部租使用者，請使用 註冊和登入使用者流程。
步驟 1：註冊自定義驗證延伸模組
您現在會設定自定義驗證延伸模組，Microsoft Entra ID 會使用此擴充功能來呼叫您的 Azure 函式。 自定義驗證延伸模組包含 REST API 端點的相關信息、它從 REST API 剖析的宣告，以及如何向 REST API 進行驗證。 請遵循下列步驟，向 Azure 函式應用程式註冊自定義驗證延伸模組。
注意
您最多可以有 100 個自定義擴充原則。
註冊自定義驗證延伸模組
- 以至少應用程式 管理員 istrator 和 Authentication 管理員 istrator 身分登入 Azure 入口網站。
- 搜尋並選取 [Microsoft Entra ID ]，然後選取 [ 企業應用程式]。
- 選取 [自定義驗證延伸模組]，然後選取 [ 建立自定義擴充功能]。
- 在 [ 基本概念] 中 ，選取 TokenIssuanceStart 事件類型，然後選取 [ 下一步]。
- 在 [端點組態] 中，填入下列屬性：
- 名稱 - 自訂驗證延伸模組的名稱。 例如， 令牌發行事件。
- 目標 URL -
{Function_Url}Azure 函式 URL 的 。 流覽至 Azure 函式應用程式的 [概觀 ] 頁面，然後選取您建立的函式。 在函式 [概觀] 頁面中，選取 [ 取得函式 URL ]，並使用複製圖示來複製 URL。 - 描述 - 自定義驗證延伸模組的描述。
- 選取 [下一步]。
- 在 [API 驗證] 中，選取 [ 建立新的應用程式註冊 ] 選項，以建立代表函 式應用程式的應用程式註冊。
- 為應用程式命名，例如 Azure Functions 驗證事件 API。
- 選取 [下一步]。
- 在 [宣告] 中，輸入您預期自定義驗證延伸模組要從 REST API 剖析的屬性，並將合併到令牌中。 新增下列宣告：
- dateOfBirth
- customRoles
- apiVersion
- correlationId
- 選取 [下一步]，然後 選取 [建立]，以註冊自定義驗證延伸模組和相關聯的應用程式註冊。
- 記下 [API 驗證] 底下的 [應用程式識別符]，這是在 Azure 函式應用程式中設定環境變數所需的標識碼。
1.2 授與系統管理員同意
建立自訂驗證延伸模組之後，您必須將許可權授與 API。 自訂驗證延伸模組會使用 client_credentials 許可權向 Azure 函式應用程式 Receive custom authentication extension HTTP requests 進行驗證。
開啟新自定義驗證延伸模組的 [ 概觀 ] 頁面。 記下 [API 驗證] 底下的 [應用程式識別符]，因為新增識別提供者時需要它。
在 [API 驗證] 底下，選取 [授與許可權]。
新的視窗隨即開啟，一旦登入，它會要求接收自定義驗證延伸模組 HTTP 要求的許可權。 這可讓自定義驗證延伸模組向 API 進行驗證。 選取 [接受]。
步驟 2：設定 OpenID 連線 應用程式以接收擴充的令牌
若要取得令牌並測試自訂驗證延伸模組，您可以使用 https://jwt.ms 應用程式。 這是 Microsoft 擁有的 Web 應用程式，可顯示令牌的已譯碼內容（令牌的內容永遠不會離開瀏覽器）。
2.1 註冊測試 Web 應用程式
請遵循下列步驟來註冊 jwt.ms Web 應用程式：
從 Azure 入口網站 的 [首頁] 頁面中，選取 [Microsoft Entra ID]。
選取 [應用程式註冊]>[新增註冊]。
輸入應用程式的 [名稱]。 例如， 我的測試應用程式。
在 [支援的帳戶類型] 底下，選取 [僅在此組織目錄中的帳戶]。
在 [重新導向 URI] 的 [選取平臺] 下拉式清單中，選取 [Web]，然後在 [URL] 文本框中輸入
https://jwt.ms。選取 [註冊 ] 以完成應用程式註冊。
在應用程式註冊的 [概觀] 頁面中，複製應用程式 （用戶端） 識別碼。 應用程式識別碼稱為
{App_to_enrich_ID}後續步驟中的 。 在 Microsoft Graph 中，appId 屬性會參考它。
2.2 啟用隱含流程
jwt.ms 測試應用程式會使用隱含流程。 在 我的測試應用程式 註冊中啟用隱含流程：
- 在 [管理] 底下，選取 [驗證]。
- 在 [Implicit grant and hybrid flows] \(隱含授與和混合式流程\) 下，選取 [ID tokens (used for implicit and hybrid flows)] \(識別碼權杖 (用於隱含和混合式流程)\) 核取方塊。
- 選取 [儲存]。
2.3 為宣告對應原則啟用您的應用程式
宣告對應原則可用來選取從自定義驗證延伸模組傳回的屬性會對應至令牌。 若要允許增加令牌，您必須明確啟用應用程式註冊以接受對應的宣告：
- 在 [我的測試] 應用程式註冊中，於 [管理] 底下，選取 [指令清單]。
- 在指令清單中，找出
acceptMappedClaims屬性，並將值設定為true。 - 將
accessTokenAcceptedVersion設定為2。 - 選取儲存以儲存變更。
下列 JSON 代碼段示範如何設定這些屬性。
{
"id": "22222222-0000-0000-0000-000000000000",
"acceptMappedClaims": true,
"accessTokenAcceptedVersion": 2,
...
}
警告
請勿針對多租使用者應用程式將 屬性設定 acceptMappedClaims 為 true ，這可讓惡意執行者為您的應用程式建立宣告對應原則。 請改為 設定自訂簽署金鑰。
繼續進行下一個步驟， 將自定義宣告提供者指派給您的應用程式。
步驟 3：將自定義宣告提供者指派給您的應用程式
若要將來自自定義驗證延伸模組的宣告發出令牌，您必須將自定義宣告提供者指派給應用程式。 這是以令牌物件為基礎，因此必須將提供者指派給用戶端應用程式，以接收標識元令牌中的宣告，以及要接收存取令牌中宣告的資源應用程式。 自訂宣告提供者依賴使用令牌發行啟動事件接聽程式所設定的自定義驗證延伸模組。 您可以選擇自訂宣告提供者中的所有宣告或宣告子集都對應至令牌。
注意
您只能在應用程式和自定義延伸模組之間建立 250 個唯一指派。 如果您想要將相同的自定義擴充功能呼叫套用至多個應用程式，建議您使用 authenticationEventListeners Microsoft Graph API 來建立多個應用程式的接聽程式。 Azure 入口網站 不支援此功能。
請遵循下列步驟，使用您的自訂驗證延伸模組來 連線我的測試應用程式 ：
將自定義驗證延伸模組指派為自定義宣告提供者來源;
從 Azure 入口網站 的 [首頁] 頁面中，選取 [Microsoft Entra ID]。
選取[企業應用程式]，然後在 [管理] 下，選取 [所有應用程式]。 從清單中尋找並選取 [我的測試應用程式 ]。
從 [我的測試] 應用程式的 [概觀] 頁面中，流覽至 [管理]，然後選取 [單一登錄]。
在 [屬性與宣告] 下，選取 [編輯]。
展開 [ 進階設定] 功能表。
在 [自定義宣告提供者] 旁，選取 [設定]。
展開 [ 自定義宣告提供者 ] 下拉式方塊，然後選取您稍早建立的 令牌發行事件 。
選取 [儲存]。
接下來，從自定義宣告提供者指派屬性，以宣告的形式發出令牌：
選取 [新增宣告 ] 以新增宣告。 提供您想要發出的宣告名稱，例如 dateOfBirth。
在 [來源] 下，選取 [屬性]，然後從 [來源屬性] 下拉式方塊中選擇 customClaimsProvider.dateOfBirth。
選取 [儲存]。
重複此程式以新增 customClaimsProvider.customRoles、 customClaimsProvider.apiVersion 和 customClaimsProvider.correlationId 屬性，以及對應的名稱。 最好將宣告的名稱與屬性的名稱相符。
步驟 4：保護您的 Azure 函式
Microsoft Entra 自定義驗證延伸模組會使用伺服器對伺服器流程，取得 HTTP 標頭中傳送至 Azure 函式的 Authorization 存取令牌。 將函式發佈至 Azure 時，特別是在生產環境中，您需要驗證在授權標頭中傳送的令牌。
若要保護您的 Azure 函式，請遵循下列步驟來整合 Microsoft Entra 驗證，以驗證傳入令牌與 Azure Functions 驗證事件 API 應用程式註冊。 根據您的租用戶類型選擇下列其中一個索引標籤。
注意
如果 Azure 函式應用程式裝載於與註冊自訂驗證延伸模組的租使用者不同的 Azure 租使用者中，請選擇 [開啟標識符 連線] 索引標籤。
4.1 使用 Microsoft Entra 識別提供者
使用下列步驟，將 Microsoft Entra 新增為識別提供者至 Azure 函式應用程式。
在 Azure 入口網站 中，尋找並選取您先前發佈的函式應用程式。
在 [設定] 底下，選取 [驗證]。
選取 [新增識別提供者]。
選取 [Microsoft ] 作為識別提供者。
選取 [員工 ] 作為租用戶類型。
在 [應用程式註冊] 下，選取 [在此目錄中挑選應用程式註冊類型的現有應用程式註冊]，然後挑選您在註冊自定義宣告提供者時先前建立的 Azure Functions 驗證事件 API 應用程式註冊。
輸入下列簽發者 URL，
https://login.microsoftonline.com/{tenantId}/v2.0其中{tenantId}是員工員工租使用者的租用戶標識碼。在 [未經驗證的要求] 下，選取 [HTTP 401 未經授權] 作為識別提供者。
取消選取 [令牌存放區 ] 選項。
選取 [新增 ] 以將驗證新增至您的 Azure 函式。
4.2 使用 OpenID 連線 識別提供者
如果您已設定 Microsoft 識別提供者，請略過此步驟。 否則，如果 Azure 函式裝載於與註冊自定義驗證擴充功能租使用者不同的租使用者之下，請遵循下列步驟來保護您的函式：
建立用戶端密碼
- 從 Azure 入口網站 的 [首頁] 頁面中，選取 [Microsoft Entra ID> 應用程式註冊]。
- 選取您先前建立的 Azure Functions 驗證事件 API 應用程式註冊。
- 選取 [憑證與秘密>] [客戶端密碼>] [新增客戶端密碼]。
- 選取秘密的到期日，或指定自定義存留期、新增描述，然後選取 [ 新增]。
- 記錄秘密的值，以用於用戶端應用程式程式碼。 離開此頁面後，就「不會再次顯示」此祕密值。
將 OpenID 連線 識別提供者新增至 Azure 函式應用程式。
尋找並選取您先前發佈的函式應用程式。
在 [設定] 底下，選取 [驗證]。
選取 [新增識別提供者]。
選取 [OpenID 連線] 作為識別提供者。
提供名稱，例如 Contoso Microsoft Entra ID。
在 [ 元數據] 專案底下，輸入檔URL的 下列URL。
{tenantId}將取代為您的 Microsoft Entra 租使用者識別碼。https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration在 [應用程式註冊] 底下，輸入您先前建立之 Azure Functions 驗證事件 API 應用程式註冊的應用程式識別碼（用戶端識別符）。
返回 Azure 函式，在 應用程式註冊下，輸入 客戶端密碼。
取消選取 [令牌存放區 ] 選項。
選取 [新增] 以新增 OpenID 連線 識別提供者。
步驟 5：測試應用程式
若要測試您的自定義宣告提供者，請遵循下列步驟：
開啟新的私人瀏覽器，然後瀏覽並透過下列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以您的租使用者識別碼、租使用者名稱或其中一個已驗證的功能變數名稱取代
{tenantId}。 例如：contoso.onmicrosoft.com。將取代
{App_to_enrich_ID}為 [我的測試] 應用程式 用戶端識別碼。登入之後，您會在 看到已譯碼的令牌
https://jwt.ms。 認證來自 Azure 函式的宣告是否顯示在已譯碼的權杖中， 例如dateOfBirth。