自訂驗證延伸模組概觀
本文提供 Microsoft Entra ID 自定義驗證延伸模組的高階技術概觀。 自訂驗證延伸模組可讓您藉由與外部系統整合來自定義 Microsoft Entra 驗證體驗。
下圖描述與自定義驗證延伸模組整合的登入流程。
- 用戶嘗試登入應用程式,並重新導向至 Microsoft Entra 登入頁面。
- 使用者完成驗證中的特定步驟之後, 就會觸發事件接聽程式 。
- 您的 自訂驗證延伸模組 會將 HTTP 要求傳送至 REST API 端點。 要求包含事件、使用者配置檔、會話數據和其他內容資訊的相關信息。
- REST API 會執行自定義工作流程。
- REST API 會傳回對 Microsoft Entra ID 的 HTTP 回應。
- Microsoft Entra 自定義驗證延伸模組 會處理回應,並根據事件類型和 HTTP 回應承載自定義驗證。
- 令牌會傳回至應用程式。
自訂驗證延伸模組 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 之間的通訊受到適當保護,必須套用多個安全性控制件。
- 當自定義驗證延伸模組呼叫 REST API 時,它會傳送 HTTP
Authorization
標頭,其中包含 Microsoft Entra ID 所簽發的持有人令牌。 - 持有人令牌包含
appid
或azp
宣告。 驗證個別宣告是否包含99045fe1-7639-4a75-9d4a-577b6ca3810f
值。 此值可確保 Microsoft Entra 識別碼是呼叫 REST API 的人員。- 針對 V1 應用程式,驗證
appid
宣告。 - 針對 V2 應用程式,驗證
azp
宣告。
- 針對 V1 應用程式,驗證
- 持有人令牌
aud
物件宣告包含相關聯應用程式註冊的標識碼。 您的 REST API 端點必須驗證是否已針對該特定對象發出持有人令牌。 - 持有人令牌
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 外部 ID 的使用者流程。 如需詳細資訊,請參閱 新增您自己的商業規則。