通过

自定义身份验证扩展概述

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 自定义身份验证扩展的详细说明，并提供最佳做法和有价值的技巧，以实现最佳实现。

登录流程

下图描述了与自定义身份验证扩展集成的登录流。

示意图显示使用来自外部源的声明扩充的令牌。

  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 必须可公开访问。 可以使用 Azure Functions、Azure 应用服务、Azure 逻辑应用或其他公开可用的 API 终结点托管它。

你可以灵活地使用任何编程语言、框架或低代码无代码解决方案，例如 Azure 逻辑应用来开发和部署 REST API。 若要快速开始使用，请考虑使用 Azure Function。 它允许在无服务器环境中运行代码，而无需先创建虚拟机（VM）或发布 Web 应用程序。

REST API 必须处理：

请求有效负载

对 REST API 的请求包括一个 JSON 有效负载，其中包含有关事件、用户配置文件、身份验证请求数据和其他上下文信息的详细信息。 JSON 有效负载中的属性可用于执行 API 的逻辑。

例如，在 令牌颁发启动 事件中，请求有效负载可能包括用户的唯一标识符，允许你从自己的数据库中检索用户配置文件。 请求有效负载数据必须遵循事件文档中指定的架构。

返回数据和动作类型

Web API 在完成业务逻辑的工作流后，必须返回一种 动作类型，该类型指示 Microsoft Entra 如何继续执行身份验证过程。

例如，对于 属性集合开始 和 属性集合提交 事件，Web API 返回 的作类型 指示是否可以在目录中创建帐户、显示验证错误或完全阻止注册流。

REST API 响应可能包括数据。 例如，令牌发行开始时事件可以提供一组可映射到安全令牌的属性。

保护 REST API

为了确保自定义身份验证扩展与 REST API 之间的通信得到适当的保护，必须采用多个安全控制措施。

  1. 当自定义身份验证扩展调用 REST API 时，它会发送包含 Microsoft Entra ID 颁发的持有者令牌的 HTTP Authorization 标头。
  2. 持有者令牌包含 appid 或 azp 声明。 验证相应的声明是否包含 99045fe1-7639-4a75-9d4a-577b6ca3810f 值。 此值可确保 Microsoft Entra ID 是调用 REST API 的 Microsoft Entra ID。
    1. 对于 V1 应用程序，请验证 appid 声明。
    2. 对于 V2 应用程序，请验证 azp 声明。
  3. 持有者令牌 aud 受众声明包含关联的应用程序注册的 ID。 REST API 终结点需要验证是否为该特定受众颁发了持有者令牌。
  4. 持有者令牌 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 事件发生在属性集合步骤的开始，在属性集合页面呈现之前。 它允许添加预填充值和显示阻塞错误等操作。

小窍门

立即试用

要试用此功能，请转到 Woodgrove Groceries 演示并启用“预填充登录属性”用例。

属性集合提交

属性集合提交 事件可用于自定义身份验证扩展，以在从用户收集属性后添加逻辑。 OnAttributeCollectionSubmit 事件在用户输入并提交属性后触发，允许添加验证条目或修改属性等操作。

小窍门

立即试用

要试用此功能，请转到 Woodgrove Groceries 演示并启动“验证登录属性”用例，或“阻止用户继续进行登录进程”用例。

一次性密码发送

激活一次性密码电子邮件时，将触发 OnOtpSend 事件。 它允许 调用 REST API 以使用自己的电子邮件提供程序。 此事件可用于向注册电子邮件地址的用户发送自定义电子邮件、使用电子邮件一次性密码登录（电子邮件 OTP）、使用电子邮件 OTP 重置其密码，或使用电子邮件 OTP 进行多重身份验证（MFA）。

激活 OnOtpSend 事件时，Microsoft Entra 会将一次性密码发送到你拥有的指定 REST API。 然后，REST API 使用所选的电子邮件提供商（例如 Azure 通信服务或 SendGrid）通过自定义电子邮件模板（地址和电子邮件主题）发送一次性密码，同时支持本地化。

小窍门

立即试用

若要试用此功能，请转到 Woodgrove Groceries 演示，并启动“使用一次性代码的自定义电子邮件提供程序”用例。

相关内容