关于 Azure AD B2C 中的 API 连接器

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

项目
04/11/2023

开始之前，可以使用“选择策略类型”选择器来选择要设置的策略类型。 Azure Active Directory B2C 提供了两种定义用户如何与应用程序交互的方法：通过预定义的用户流，或者通过可完全配置的自定义策略。对于每种方法，本文中所需的步骤都不同。

概述

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

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

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

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

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

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

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

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

创建用户之前

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

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

发送令牌之前（预览版）

注意

此功能目前以公共预览版提供。

将在颁发令牌之前调用注册或登录过程中的此步骤的 API 连接器。以下是可能在此步骤中启用的场景示例：

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

构成 Azure Active Directory B2C (Azure AD B2C) 的基础的 Identity Experience Framework 可在用户旅程中与 RESTful API 相集成。本文介绍如何使用 RESTful 技术配置文件创建与 RESTful 服务交互的用户旅程。

使用 Azure AD B2C 可以通过调用 RESTful 服务，将自己的业务逻辑添加到用户旅程中。 Identity Experience Framework 可以在 RESTful 服务中发送和接收数据，以交换声明。例如，你能够：

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

RESTful 服务声明交换示意图

注意

如果 RESTful 服务对 Azure AD B2C 的响应速度缓慢或没有响应，则超时为 30 秒，重试计数为 2 次（这意味着总共有 3 次尝试）。目前，无法配置超时和重试计数设置。

调用 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 请求正文中发送。
Header，在 HTTP GET 请求标头中发送。
QueryString，在 HTTP GET 请求查询字符串中发送。

配置 Body 选项时，REST API 技术配置文件允许将复杂的 JSON 有效负载发送到终结点。有关详细信息，请参阅发送 JSON 有效负载。

接收数据

RESTful 技术配置文件的 OutputClaims 元素包含 REST API 返回的声明列表。可能需要将策略中定义的声明名称映射到 REST API 中定义的名称。只要设置了 DefaultValue 特性，就还可以包含 REST API 标识提供者不会返回的声明。

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 数据类型，返回最小值 1970-00-00T00: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 技术配置文件，用户将通过相关的错误消息重定向回到信赖方应用程序。

开发 REST API

你可在任何平台开发并以任何编程语言编写 REST API，但前提是需保证它是安全的，并且可以发送和接收 JSON 格式的声明。

对 REST API 服务的请求来自 Azure AD B2C 服务器。必须将 REST API 服务发布到可公开访问的 HTTPS 终结点。 REST API 调用将从 Azure 数据中心 IP 地址抵达。

可使用无服务器云功能简化开发，如 Azure Functions 中的 HTTP 触发器。

应将 REST API 服务及其基础组件（例如数据库和文件系统）设计为高度可用。

重要

终结点必须符合 Azure AD B2C 安全要求。较旧的 TLS 版本和密码已弃用。有关详细信息，请参阅 Azure AD B2C TLS 和密码套件要求。

后续步骤

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

了解如何在与外部进程交互时构建复原能力
了解如何通过开发人员最佳做法构建复原能力。

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

概述