使用自己的业务逻辑扩展身份验证流

适用于： 员工租户 外部租户（了解详细信息）

Microsoft Entra 外部 ID 用户流旨在提供灵活性。 在注册和登录用户流中，存在内置身份验证事件。 还可以在身份验证流中的特定点添加自定义身份验证扩展。 自定义身份验证扩展本质上是一个事件侦听器，激活后会对定义工作流操作的 REST API 终结点发出 HTTP 调用。 例如，可以添加属性收集工作流来验证用户在注册期间输入的属性，也可以使用自定义声明提供程序在颁发令牌之前将外部用户数据添加到令牌中。

需要配置两个组件：自定义身份验证扩展和 REST API。 自定义身份验证扩展指定 REST API 终结点、何时应调用该 REST API，以及调用 REST API 的凭据。 可以在身份验证流中的以下节点创建自定义身份验证扩展：

• 注册期间，属性集合之前或之后：
  • OnAttributeCollectionStart 事件发生在属性集合步骤的开始，在属性集合页面呈现之前。
  • OnAttributeCollectionSubmit 事件在用户输入并提交属性后发生。
• 使用 OnTokenIssuanceStart 事件颁发令牌时，该事件在向应用程序颁发令牌之前触发。

如果在其中一个节点配置了自定义身份验证扩展，则 Microsoft Entra ID 将调用定义的 REST API。 对 REST API 的请求包含有关事件、用户配置文件、身份验证请求数据的信息以及其他上下文信息。 REST API 进而会执行工作流操作。

本文概述了 Microsoft Entra 外部 ID 中的自定义身份验证扩展。

属性集合启动和提交事件

可以使用自定义身份验证扩展将工作流添加到自助注册用户流中的属性集合。 例如，可以使用自定义值预填充属性字段、验证用户的条目和修改属性，以及显示错误。 将启用两个事件：

• OnAttributeCollectionStart - OnAttributeCollectionStart 事件发生在属性集合过程的开始，在属性集合页面呈现之前。 此事件可用于根据域来阻止用户注册或添加要收集的属性等场景。 对于 OnAttributeCollectionStart 事件，可以配置以下场景：

  • continueWithDefaultBehavior - 像往常一样呈现属性集合页。
  • setPreFillValues - 预填充注册表单中的属性。
  • showBlockPage - 显示错误消息并阻止用户注册。

• OnAttributeCollectionSubmit - OnAttributeCollectionSubmit 事件在用户输入并提交属性后发生。 此事件可用于验证或修改用户提供的信息等场景。 例如，可以验证邀请码或合作伙伴编号、修改地址格式或返回错误。

  • continueWithDefaultBehavior - 继续执行注册流。
  • modifyAttributeValues - 覆盖用户在注册表单中提交的值。
  • showValidationError - 基于提交的值返回错误。
  • showBlockPage - 显示错误消息并阻止用户注册。

若要配置属性集合启动和提交事件，需创建自定义身份验证扩展 REST API。 当事件触发时，Microsoft Entra ID 会将一个 HTTP 请求发送到你的 REST API 终结点。 REST API 可以是 Azure 函数、Azure 逻辑应用或其他公开可用的 API 终结点。 REST API 终结点负责定义要采取的工作流操作。

有关详细信息，请参阅向用户流添加属性集合自定义扩展。

令牌颁发开始事件

在用户完成其所有身份验证质询后，并且即将颁发安全令牌之前，将会触发令牌颁发开始事件。

当用户使用 Microsoft Entra ID 向你的应用程序进行身份验证时，会将一个安全令牌返回到你的应用程序。 该安全令牌包含有关用户的声明，例如名称、唯一标识符或应用程序角色。 除了安全令牌中包含的默认声明集之外，还可以使用你开发的 REST API 从外部系统定义自己的自定义声明。

在某些情况下，关键数据可能存储在 Microsoft Entra 外部的系统中，例如辅助电子邮件、计费层级或敏感信息。 将外部系统中的信息存储在 Microsoft Entra 目录中并非始终可行。 对于这些情况，你可以使用自定义身份验证扩展和自定义声明提供程序将此外部数据添加到返回到应用程序的令牌中。

令牌颁发事件扩展涉及以下组件：

• 自定义声明提供程序。 自定义声明提供程序是一种自定义身份验证扩展，它会从外部系统提取数据。 自定义声明提供程序指定要添加到会返回到应用程序的安全令牌的属性。 多个声明提供程序可以共享相同的自定义扩展，因此可以将一组不同的属性添加到每个应用程序的安全令牌中。

• REST API 终结点。 当事件触发时，Microsoft Entra ID 会将一个 HTTP 请求发送到你的 REST API 终结点。 REST API 可以是 Azure 函数、Azure 逻辑应用或其他公开可用的 API 终结点。 REST API 终结点与各种数据存储（包括下游数据库、现有 API、轻型目录访问协议 (LDAP) 目录或包含要添加到令牌配置的属性的任何其他存储）相连接。

  REST API 向 Microsoft Entra ID 返回包含属性的 HTTP 响应或操作。 这些属性不会自动添加到令牌中。 相反，必须为要包含在令牌中的任何属性配置应用程序的声明映射策略。

有关详细信息，请参阅：

• 关于自定义身份验证扩展。
• 使用自定义声明提供程序为令牌颁发事件配置自定义声明提供程序。

另请参阅

• 若要详细了解自定义扩展的工作原理，请参阅自定义身份验证扩展。
• 使用令牌颁发启动事件创建 REST API。
• 为令牌颁发事件配置自定义声明提供程序。
• 通过示例 OpenID Connect 应用程序为属性集合启动和提交事件配置自定义身份验证扩展。
• 请参阅 Microsoft Entra 外部 ID 开发人员中心，了解可供开发人员使用的最新内容和资源。