自訂驗證擴充概觀

本文提供 Microsoft Entra ID 自訂驗證擴充的宏觀技術概觀。 自訂驗證擴充可讓您藉由與外部系統整合，自訂 Microsoft Entra 驗證體驗。

下圖描述與自訂驗證擴充整合的登入流程。

1. 使用者嘗試登入應用程式，並重新導向至 Microsoft Entra 登入頁面。
2. 使用者完成驗證中的特定步驟後會觸發事件接聽程式。
3. 您的自訂驗證擴充將 HTTP 要求傳送至 REST API 端點。 要求包含事件、使用者設定檔、工作階段資料的相關資訊，以及其他內容資訊。
4. REST API 會執行自訂工作流程。
5. REST API 會向 Microsoft Entra ID 傳回 HTTP 回應。
6. Microsoft Entra 自訂驗證擴充處理回應，並根據事件類型和 HTTP 回應承載自訂驗證。
7. 權杖會傳回應用程式。

自訂驗證擴充 REST API 端點

引發事件時，Microsoft Entra ID 會呼叫您擁有的 REST API 端點。 REST API 要求包含事件、使用者設定檔、驗證要求資料的相關資訊，以及其他內容資訊。

您可以使用任何程式設計語言、架構和主控環境來建立及裝載自訂驗證擴充 REST API。 若要快速開始使用，請使用 C# Azure 函式。 Azure Functions 可讓您在無伺服器環境中執行程式碼，而不需要先建立虛擬機器 (VM) 或發佈 Web 應用程式。

REST API 必須處理：

• 保護 REST API 呼叫的權杖驗證。
• 商務規則
• HTTP 要求和回應結構描述的傳入和傳出驗證。
• 稽核和記錄。
• 可用性、效能和安全性控制項。

對於在 Azure Functions 執行 REST API 的開發人員，請考慮使用 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet 程式庫，這有助於使用 Microsoft Azure 的內建驗證功能協助權杖驗證實作。 它提供不同事件類型的資料模型、起始傳入和傳出要求和回應處理，因此可以將更多焦點放在商務邏輯。

保護 REST API

為了確保自訂驗證擴充與 REST API 之間的通訊受到適當保護，必須套用多個安全性控制項。

1. 自訂驗證擴充呼叫 REST API 時，它會傳送 HTTP Authorization 標頭，其中包含由 Microsoft Entra ID 核發的持有人權杖。
2. 持有人權杖包含 appid 或 azp 宣告。 驗證個別宣告是否包含 99045fe1-7639-4a75-9d4a-577b6ca3810f 值。 此值可確保呼叫 REST API 的是 Microsoft Entra ID。
   1. 針對 V1 應用程式，請驗證 appid 宣告。
   2. 針對 V2 應用程式，請驗證 azp 宣告。
3. 持有人權杖 aud 對象宣告包含相關聯應用程式註冊的識別碼。 您的 REST API 端點必須驗證是否已針對該特定對象發出持有人權杖。
4. 持有人權杖 iss 簽發者宣告包含Microsoft Entra 簽發者 URL。 根據您的租用戶設定，簽發者 URL 會是下列其中一項：
   • 員工：https://login.microsoftonline.com/{tenantId}/v2.0。
   • 客戶：https://{domainName}.ciamlogin.com/{tenantId}/v2.0。

自訂宣告提供者

自訂宣告提供者是一種自訂驗證擴充，可呼叫 REST API 從外部系統擷取宣告。 自訂宣告提供者會將外部系統的宣告對應至權杖，並可指派給目錄中的一或多個應用程式。

深入了解自訂宣告提供者。

屬性集合開始和提交事件

屬性集合開始和提交事件可以搭配自訂驗證擴充使用，在從使用者收集屬性前後新增邏輯。 例如，您可以新增工作流程，驗證使用者在註冊期間輸入的屬性。 OnAttributeCollectionStart 事件會在屬性收集步驟的開頭，於屬性收集頁面呈現之前發生。 它讓您新增預先填入值和顯示封鎖錯誤之類的動作。 使用者輸入和提交屬性之後，OnAttributeCollectionSubmit 事件隨即觸發，讓您新增驗證項目或修改屬性等動作。

注意

屬性集合開始和提交事件目前僅適用於外部租用戶中 Microsoft Entra External ID 內的使用者流程。 如需詳細資料，請參閱新增您自己的商務邏輯。

另請參閱

• 了解如何使用範例 OpenID Connect 應用程式，為屬性集合開始和提交事件建立自訂驗證擴充。