Microsoft Entra ID 驗證管線包含數個內建驗證事件，例如使用者認證驗證、條件式存取原則、多重要素驗證、自助式密碼重設等等。
Microsoft Entra 自定義驗證延伸模組可讓您在驗證流程內的特定點使用自己的商業規則來擴充驗證流程。 自定義驗證延伸模組基本上是事件接聽程式，在啟用時，對定義工作流程動作的 REST API 端點進行 HTTP 呼叫。
例如，您可以使用自定義宣告提供者，在發出令牌之前，將外部用戶數據新增至安全性令牌。 您可以新增屬性集合工作流程，以驗證用戶在註冊期間輸入的屬性。 本文提供Microsoft Entra ID 自定義驗證延伸模組的高階技術概觀。
Microsoft Entra 自定義驗證延伸模組概觀影片提供自定義驗證延伸模組的主要特性和功能的完整大綱。
元件概觀
您需要設定兩個元件：Microsoft Entra 和 REST API 中的自定義驗證延伸模組。 自訂驗證延伸模組會指定 REST API 端點、應呼叫 REST API 的時機，以及呼叫 REST API 的認證。
這段影片提供設定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 必須可公開存取。 它可以使用 Azure Functions、Azure App Service、Azure Logic Apps 或其他公開可用的 API 端點來裝載。
您可以彈性地使用任何程式設計語言、架構或低程式代碼無程式代碼解決方案，例如 Azure Logic Apps 來開發和部署 REST API。 若要快速開始使用，請考慮採用 Azure 函式。 它可讓您在無伺服器環境中執行程序代碼，而不需要先建立虛擬機（VM）或發佈 Web 應用程式。
REST API 必須處理：
- 保護 REST API 呼叫的令牌驗證。
- 商務規則
- 傳回數據和動作類型
- HTTP 要求和回應結構描述的傳入和傳出驗證。
- 稽核和記錄。
- 可用性、效能和安全性控制。
觀看這段影片，瞭解如何使用 Azure Logic Apps 建立驗證延伸模組 REST API 端點，而不需撰寫程式代碼。 Azure 邏輯應用程式可讓使用者使用可視化設計工具建置工作流程。 影片涵蓋自定義驗證電子郵件，並適用於所有類型的自定義驗證延伸模組，包括自定義宣告提供者。
請求載荷
對 REST API 的請求包含 JSON 承載，其中包含事件、使用者個人資料、驗證請求數據及其他內容資訊的詳細數據。 JSON 承載內的屬性可用來執行 API 的邏輯。
例如，在 令牌發行開始 事件中，要求承載可能包含使用者的唯一標識碼，讓您從自己的資料庫擷取使用者配置檔。 要求承載數據必須遵循事件檔中所指定的架構。
傳回數據和動作類型
當您的 Web API 使用商業規則執行工作流程之後，它必須傳回 動作類型 ，以指示 Microsoft Entra 如何繼續進行驗證程式。
例如，在 屬性集合開始 和 屬性集合送出 事件的情況下，Web API 傳回的 動作類型 會指出是否可以在目錄中建立帳戶、顯示驗證錯誤，或完全封鎖註冊流程。
REST API 回應可能包含數據。 例如， 在令牌發行開始事件上 ，可能會提供一組可對應至安全性令牌的屬性。
保護 REST API
為了確保自訂驗證擴充與 REST API 之間的通訊受到適當保護，必須套用多個安全性控制項。
- 自訂驗證擴充呼叫 REST API 時，它會傳送 HTTP
Authorization標頭，其中包含由 Microsoft Entra ID 核發的持有人權杖。 - 持有者權杖包含
appid或azp聲明。 驗證個別宣告是否包含99045fe1-7639-4a75-9d4a-577b6ca3810f值。 此值可確保呼叫 REST API 的是 Microsoft Entra ID。- 針對 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。
- 勞動力：
自訂驗證事件類型
本節列出 Microsoft Entra ID 員工和外部租使用者中可用的自定義驗證延伸模組事件。 如需事件的詳細資訊，請參閱各自的檔。
| 事件 | 工作人員租戶 | 外部租戶 |
|---|---|---|
| 令牌發行開始 | 
|
|
| 屬性集合開始 |
|
|
| 屬性集合提交 |
|
|
| 一次性密碼傳送 |
|
令牌發行開始
當令牌即將發行至應用程式時，會觸發令牌發行啟動事件，OnTokenIssuanceStart。 這是 在自定義宣告提供者內設定的事件類型。 自定義宣告提供者是自定義驗證延伸模組，會呼叫 REST API 以從外部系統擷取宣告。 自訂宣告提供者會將外部系統的宣告對應至令牌，並可指派給目錄中的一個或多個應用程式。
小提示
若要試用此功能，請移至 Woodgrove Groceries 範例並啟動「從 REST API 新增宣告至安全憑證」的使用案例。
屬性集合開始
屬性集合啟動 事件可以與自定義驗證延伸模組搭配使用，以在從使用者收集屬性之前新增邏輯。 OnAttributeCollectionStart 事件會在屬性收集步驟的開頭，於屬性收集頁面呈現之前發生。 它讓您新增預先填入值和顯示封鎖錯誤之類的動作。
屬性集合提交
屬性集合送出 事件可以搭配自定義驗證延伸模組使用，以在從使用者收集屬性之後新增邏輯。 使用者輸入和提交屬性之後，OnAttributeCollectionSubmit 事件隨即觸發，讓您新增驗證項目或修改屬性等動作。
一次性密碼已發送
啟用一次密碼電子郵件時，會觸發 OnOtpSend 事件。 它可讓您 呼叫 REST API 以使用您自己的電子郵件提供者。 此事件可用來將自定義電子郵件傳送給使用電子郵件地址註冊的使用者、使用電子郵件單次密碼登入（電子郵件 OTP）、使用電子郵件 OTP 重設其密碼，或使用電子郵件 OTP 進行多重要素驗證（MFA）。
OnOtpSend 事件啟動時，Microsoft Entra 會將一次性密碼傳送至您擁有的指定 REST API。 REST API 接著會使用您選擇的電子郵件提供者，例如 Azure 通訊服務或 SendGrid，使用自訂電子郵件範本、地址和電子郵件主旨傳送單次密碼，同時支援當地語系化。
小提示
若要試用這項功能，請移至 Woodgrove Groceries 示範，然後啟動「使用自訂電子郵件提供者進行一次性程式碼」使用案例。