通过

自定义身份验证扩展概述

  • 项目

本文从技术角度概述了 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 时，它会发送包含 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。

自定义声明提供程序

自定义声明提供程序是一种自定义身份验证扩展，它会调用 REST API 来从外部系统提取声明。 自定义声明提供程序会将声明从外部系统映射到令牌中，该提供程序可以分配给目录中的一个或多个应用程序。

详细了解自定义声明提供程序。

属性集合启动和提交事件

属性集合启动和提交事件可以与自定义身份验证扩展配合使用，以便在从用户收集属性之前和之后添加逻辑。 例如，可以添加一个工作流来验证用户在注册过程中输入的属性。 OnAttributeCollectionStart 事件发生在属性集合步骤的开始，在属性集合页面呈现之前。 它允许添加预填充值和显示阻塞错误等操作。 OnAttributeCollectionSubmit 事件在用户输入并提交属性后触发，允许添加验证条目或修改属性等操作。

注意

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

一次性密码发送事件

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

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

注意

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

相关内容