通过

自定义身份验证扩展概述

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 的请求包含有关事件、用户配置文件、身份验证请求数据的信息以及其他上下文信息。

可以使用任何编程语言、框架和托管环境来创建和托管自定义身份验证扩展 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 时，它会发送包含 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 从外部系统提取声明。 自定义声明提供程序会将声明从外部系统映射到令牌中，该提供程序可以分配给目录中的一个或多个应用程序。

此视频概述了使用 Microsoft Entra 自定义声明提供程序将声明从外部系统映射到安全令牌的过程。

有关详细信息，请查看 自定义声明提供程序。

属性采集开始

属性集合启动事件可与自定义身份验证扩展一起使用，以在从用户收集属性之前添加逻辑。 OnAttributeCollectionStart 事件发生在属性集合步骤的开始，在属性集合页面呈现之前。 它允许添加预填充值和显示阻塞错误等操作。

注意

属性集合启动事件仅适用于外部租户中的 Microsoft Entra 外部 ID 下的用户流。 有关详细信息，请参阅添加自己的业务逻辑。

属性集合提交

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

注意

属性集合提交事件仅适用于外部租户中Microsoft Entra 外部 ID 中的用户流。 有关详细信息，请参阅添加自己的业务逻辑。

一次性密码发送事件

激活一次性密码电子邮件时，将触发 OnOtpSend 事件。 它允许调用 REST API 以使用自己的电子邮件提供程序。 此事件可用于向注册、重置密码或使用电子邮件和一次性密码登录的用户发送自定义电子邮件。

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

注意

一次性密码发送事件目前仅适用于 Microsoft Entra 外部 ID 中外部租户的用户流。 有关详细信息，请参阅为一次性密码发送事件配置自定义电子邮件提供程序

相关内容