使用 API 连接器通过外部标识数据源自定义和扩展注册用户流和自定义策略

概述

作为开发人员或 IT 管理员，可以使用 API 连接器将注册用户流与 REST API 集成，以自定义注册体验并与外部系统集成。 例如，使用 API 连接器，可以：

• 验证用户输入数据。 针对格式错误或无效的用户数据进行验证。 例如，可以根据外部数据存储或允许值列表中的现有数据验证用户提供的数据。 如果无效，你可以要求用户提供有效数据或阻止用户继续注册流。
• 验证用户标识。 使用身份验证服务或外部标识数据源向帐户创建决策添加额外的安全级别。
• 与自定义审批工作流集成。 连接到用于管理和限制帐户创建的自定义审批系统。
• 使用来自外部源的属性扩充令牌。 使用来自 Azure AD B2C 外部资源（如云系统、自定义用户存储、自定义权限系统、旧版标识服务等）的用户属性来扩充令牌。
• 覆盖用户属性。 重新格式化或为从用户收集的属性赋值。 例如，如果用户使用全小写或全大写字母输入了名字，则你可以设置该名字的格式，只将第一个字母大写。
• 运行自定义业务逻辑。 可以在云系统中触发下游事件，以发送推送通知、更新企业数据库、管理权限、审核数据库以及执行其他自定义操作。

API 连接器通过定义 API 调用的 HTTP 终结点 URL 和身份验证，为 Azure AD B2C 提供调用 API 终结点所需的信息。 配置 API 连接器后，可以为用户流中的特定步骤启用它。 当用户在注册流程中达到该步骤时，将调用 API 连接器，该连接器会以 HTTP POST 请求的形式连接到您的 API，并在 JSON 正文中以键值对的形式发送用户信息（“claims”）。 API 响应可能会影响用户流的执行。 例如，API 响应可以阻止用户注册、要求用户重新输入信息或覆盖用户属性。

可在其中启用用户流中的 API 连接器

用户流中有三个位置，可在其中启用 API 连接器：

• 在注册期间与标识提供者进行联合之后 - 仅适用于注册体验
• 创建用户之前 - 仅适用于注册体验
• 发送令牌之前（预览版） - 适用于注册和登录

在注册期间与标识提供者进行联合后

注册过程中此步骤中的 API 连接器在用户使用标识提供者（如 Google、Facebook 和 Microsoft Entra ID）进行身份验证后立即调用。 此步骤优先于属性集合页，后者是向用户显示的用于收集用户属性的表单。 如果用户正在使用本地帐户注册，则不会调用此步骤。 以下是可能在此步骤中启用的 API 连接器方案的示例：

• 使用用户提供的电子邮件或联合标识在现有系统中查找声明。 从现有系统返回这些声明，预先填充属性集合页，并使它们可在令牌中返回。
• 根据社交标识实现允许或阻止列表。

创建用户之前

在注册过程的此步骤中，在显示属性集合页之后，将调用 API 连接器（如果包含了连接器）。 在创建用户帐户之前始终会调用此步骤。 下面是你在注册过程中此时可能会启用的方案示例：

• 验证用户输入数据并要求用户重新提交数据。
• 阻止用户根据用户输入的数据进行注册。
• 验证用户标识。
• 在外部系统中查询有关用户的现有数据，以将其返回到应用程序令牌中或将其存储在 Microsoft Entra ID 中。

发送令牌之前（预览版）

在颁发令牌之前，会在注册或登录过程中调用此步骤中的 API 连接器。 下面是可在此步骤中启用的方案示例：

• 使用与目录不同的源（包括旧标识系统、HR 系统、外部用户存储等）中的用户属性扩充令牌。
• 使用在你自己的权限系统中存储和管理的组或角色属性扩充令牌。
• 将声明转换或操作应用于目录中声明的值。

标识体验框架是 Azure Active Directory B2C（Azure AD B2C）的基础，可以在用户旅程中与 RESTful API 集成。 本文介绍如何使用 RESTful 技术配置文件创建与 RESTful 服务交互的用户旅程。

使用 Azure AD B2C，可以通过调用自己的 RESTful 服务将自己的业务逻辑添加到用户流程中。 标识体验框架可以从 RESTful 服务发送和接收数据以交换声明。 例如，你能够：

• 使用外部标识数据源验证用户输入数据。 例如，可以验证用户提供的电子邮件地址是否存在于客户的数据库中，如果不存在，则会出现错误。 也可以将 API 连接器视为一种出站 Webhook 的支持方式，因为在发生事件（例如注册）时会进行调用。
• 处理索赔。 如果用户在所有小写字母或全部大写字母中输入其名字，则 REST API 只能使用首字母大写格式设置名称的格式，并将其返回到 Azure AD B2C。 但是，使用自定义策略时， ClaimsTransformations 优先于调用 RESTful API。
• 通过进一步与企业业务线应用程序集成来动态扩充用户数据。 RESTful 服务可以接收用户的电子邮件地址、查询客户的数据库，并将用户的会员号返回到 Azure AD B2C。 然后，返回声明可以存储在用户的 Microsoft Entra 帐户中，在接下来的编排步骤中进行评估，或包含在访问令牌中。
• 运行自定义业务逻辑。 可以发送推送通知、更新公司数据库、运行用户迁移过程、管理权限、审核数据库和执行任何其他工作流。

调用 RESTful 服务

交互包括 REST API 声明与 Azure AD B2C 之间的声明交换信息。 可以通过以下方式设计与 RESTful 服务的集成：

• 验证技术配置文件。 对 RESTful 服务的调用在指定的自断言技术配置文件的验证技术配置文件，或是在显示控件的验证显示控件中发生。 在用户旅程推进之前，验证技术配置文件会验证用户提供的数据。 使用验证技术配置文件，可以：

  • 将声明发送到 REST API。
  • 验证声明，并抛出供用户查看的自定义错误消息。
  • 将 REST API 中的声明发送回下一个协调步骤。

• 索赔交换。 可以通过在用户旅程的编排步骤中直接调用 REST API 技术配置文件来配置直接声明交换。 此定义限制为：

  • 将声明发送到 REST API。
  • 验证声明并引发会返回给应用程序的自定义错误消息。
  • 将 REST API 中的声明发送回下一个协调步骤。

可以在自定义策略定义的用户旅程中的任何步骤中添加 REST API 调用。 例如，可以调用 REST API：

• 登录期间在 Azure AD B2C 验证凭据之前的那一刻。
• 登录后立即调用。
• Azure AD B2C 在目录中创建新帐户之前。
• Azure AD B2C 在目录中创建新帐户之后。
• 在 Azure AD B2C 颁发访问令牌之前。

发送数据

在 RESTful 技术配置文件中， InputClaims 该元素包含要发送到 RESTful 服务的声明列表。 可以将声明的名称映射到 RESTful 服务中定义的名称、设置默认值并使用 声明解析程序。

可以使用 SendClaimsIn 属性配置如何将输入声明发送到 RESTful 声明提供程序。 可能的值为：

• Body，以 JSON 格式在 HTTP POST 请求正文中发送。
• Form，以与号“&”分隔键值格式在 HTTP POST 请求正文中发送。
• 标头，在 HTTP GET 请求标头中发送。
• QueryString，在 HTTP GET 请求查询字符串中发送。

配置 “正文 ”选项后，REST API 技术配置文件允许向终结点发送复杂的 JSON 有效负载。 有关详细信息，请参阅 发送 JSON 负载。

接收数据

OutputClaimsRESTful 技术配置文件的元素包含 REST API 返回的声明列表。 可能需要将策略中定义的声明的名称映射到 REST API 中定义的名称。 还可以包含 REST API 标识提供者未返回的声明，前提是设置了 DefaultValue 属性。

RESTful 声明提供程序分析的输出声明始终应分析平面 JSON 正文响应，例如：

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

输出声明应类似于以下 xml 代码片段：

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

处理 null 值

当列中的值未知或缺失时，将使用数据库中的 null 值。 不要包含具有 null 值的 JSON 键。 在以下示例中，电子邮件返回 null 值：

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

当元素为 null 时，任一：

• 省略 JSON 中的键值对。
• 返回对应于 Azure AD B2C 声明数据类型的值。 例如，对于 string 数据类型，返回空字符串 ""。 integer对于数据类型，返回零值0。 dateTime对于数据类型，返回最小值0001-01-01T00:00:00.0000000Z。

以下示例演示如何处理 null 值。 从 JSON 中省略电子邮件：

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

分析嵌套的 JSON 正文

若要分析嵌套的 JSON 正文响应，请将 ResolveJsonPathsInJsonTokens 元数据设置为 true。 在输出声明中，将 PartnerClaimType 设置为要输出的 JSON 路径元素。

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@___domain.com"
        }
      ]
    }
  }
],

输出声明应类似于以下 xml 代码片段：

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

本地化 REST API

在 RESTful 技术配置文件中，你可能要发送当前会话的语言/区域设置，并在必要时引发本地化错误消息。 使用 声明解析程序，可以发送上下文声明，例如用户语言。 以下示例显示一个用于演示此方案的 RESTful 技术配置文件。

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

处理错误消息

REST API 可能需要返回错误消息，例如“在 CRM 系统中找不到用户”。如果发生错误，REST API 应返回 HTTP 409 错误消息（冲突响应状态代码）。 有关详细信息，请参阅 RESTful 技术配置文件。

只能通过从验证技术配置文件调用 REST API 技术配置文件来实现此行为。 让用户更正页面上的数据，并在页面提交时再次运行验证。

如果直接从用户旅程引用 REST API 技术配置文件，则会将用户重定向回信赖方应用程序，并显示相关的错误消息。

• 了解如何 添加 API 连接器以修改注册体验
• 了解如何 添加 API 连接器以使用外部声明扩充令牌
• 了解如何 保护 API 连接器
• 开始使用我们的示例

有关使用 RESTful 技术配置文件的示例，请参阅以下文章：

• 演练：将 API 连接器添加到注册用户流
• 演练：将 REST API 声明交换添加到 Azure Active Directory B2C 中的自定义策略
• 保护 REST API 服务
• 使用 Azure Active Directory B2C 自定义策略调用 REST API