向用户流添加 API 连接器

项目
02/05/2024

适用于：带白色勾号的绿色圆圈。员工租户带灰色 X 号的白色圆圈。外部租户（了解详细信息）

若要使用某个 API 连接器，首先需要创建该 API 连接器，然后在用户流中启用它。

重要

从 2021 年 7 月 12 日开始，如果 Microsoft Entra B2B 客户设置了新的 Google 集成，将其用于自定义应用程序或业务线应用程序的自助注册，则在身份验证转移到系统 Web 视图之前，无法使用 Google 标识进行身份验证。了解详细信息。
从 2021 年 9 月 30 日开始，Google 将弃用嵌入式 Web 视图登录支持。如果你的应用使用嵌入式 Web 视图对用户进行身份验证，而你将 Google 联合身份验证与 Azure AD B2C 或 Microsoft Entra B2B 配合使用来进行外部用户邀请或自助注册，则 Google Gmail 用户将无法进行身份验证。了解详细信息。

创建 API 连接器

提示

本文中的步骤可能因开始使用的门户而略有不同。

至少以用户管理员身份登录到 Microsoft Entra 管理中心。
浏览到“标识”>“外部标识”>“概述”。
依次选择“所有 API 连接器”、“新建 API 连接器”。
为调用提供显示名称。例如“检查审批状态”。
为 API 调用提供“终结点 URL”。
选择“身份验证类型”，并配置用于调用 API 的身份验证信息。了解如何保护 API 连接器。
选择“保存”。

发送到 API 的请求

API 连接器具体化为 HTTP POST 请求，在 JSON 正文中以键值对的形式发送用户特性（“声明”）。特性的序列化方式与 Microsoft Graph 用户属性类似。

示例请求

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

只有“标识”>“外部标识”>“概述”>“自定义用户特性”体验中列出的用户属性和自定义特性才可以在请求中发送。

自定义特性以 extension_<extensions-app-id>_AttributeName 格式存在于目录中。你的 API 应期望收到相同序列化格式的声明。有关自定义特性的详细信息，请参阅定义自助注册流的自定义特性。

此外，声明通常在所有请求中发送：

UI 区域设置（“ui_locales”）- 最终用户的区域设置，正如在其设备上配置的那样。 API 可以使用此设置返回国际化的响应。

电子邮件地址（“email”）或标识（“identities”）- API 可以使用这些声明来标识向应用程序进行身份验证的最终用户。

重要

如果调用 API 终结点时某个声明没有值，则不会将该声明发送到 API。应将 API 设计为显式检查并处理请求中没有声明的情况。

在用户流中启用 API 连接器

遵循以下步骤将 API 连接器添加到自助注册用户流。

至少以用户管理员身份登录到 Microsoft Entra 管理中心。
浏览到“标识”>“外部标识”>“概述”。
选择“用户流”，然后选择要将 API 连接器添加到的用户流。
选择“API 连接器”，然后选择要在执行用户流中的以下步骤时调用的 API 终结点：
- 在注册期间与标识提供者进行联合之后
- 创建用户之前
选择“保存”。

在注册过程的此步骤中，在用户使用标识提供者（例如 Google、Facebook 或 Microsoft Entra ID）进行身份验证之后，会立即调用 API 连接器。此步骤优先于属性集合页，后者是向用户显示的用于收集用户属性的表单。

执行此步骤时发送到 API 的示例请求

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

发送到 API 的确切声明取决于标识提供者提供的信息。始终会发送“email”。

执行此步骤时来自 Web API 的预期响应类型

在运行用户流期间当 Web API 从 Microsoft Entra ID 收到 HTTP 请求时，它可以返回以下响应：

继续响应
阻止响应

继续响应

继续响应表示用户流应继续下一步：特性收集页。

在继续响应中，API 可以返回声明。如果 API 返回了某个声明，该声明将执行以下操作：

预先填充特性收集页中的输入字段。

参阅继续响应的示例。

阻止响应

收到阻止响应会退出用户流。 API 可以有目的性地发出阻止响应，通过向用户显示一个阻止页来停止用户流的继续运行。阻止页将显示 API 提供的 userMessage。

参阅阻止响应的示例。

创建用户之前

在注册过程的此步骤中，在显示属性集合页之后，将调用 API 连接器（如果包含了连接器）。在 Microsoft Entra ID 中创建用户帐户之前，始终会调用此步骤。

执行此步骤时发送到 API 的示例请求

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

发送到 API 的确切声明取决于从用户收集的信息或者标识提供者提供的信息。

执行此步骤时来自 Web API 的预期响应类型

在运行用户流期间当 Web API 从 Microsoft Entra ID 收到 HTTP 请求时，它可以返回以下响应：

继续响应
阻止响应
验证响应

继续响应

继续响应表示用户流应继续下一步：在目录中创建用户。

在继续响应中，API 可以返回声明。如果 API 返回了某个声明，该声明将执行以下操作：

替代已在特性收集页中分配给声明的任何值。

参阅继续响应的示例。

阻止响应

参阅阻止响应的示例。

验证错误响应

当 API 以验证错误响应做出响应时，用户流将停留在“属性集合”页面，并向用户显示 userMessage。然后，用户可以编辑并重新提交表单。这种类型的响应可用于输入验证。

参阅验证错误响应的示例。

示例响应

继续响应的示例

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

参数	类型	必需	说明
版本	字符串	是	API 的版本。
action	字符串	是	值必须是 `Continue`。
<builtInUserAttribute>	<属性类型>	否	如果已将值选作 API 连接器配置中的“要接收的声明”以及用户流的“用户特性”，则这些值可以存储在目录中。如果已将值选作“应用程序声明”，则可以在令牌中返回这些值。
<extension_{extensions-app-id}_CustomAttribute>	<属性类型>	否	声明不需要包含 `_<extensions-app-id>_`，它是可选的。返回的值可以覆盖从用户收集的值。

阻止响应的示例

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was an error with your request. Please try again or contact support.",
}

参数	类型	必需	说明
版本	字符串	是	API 的版本。
action	字符串	是	值必须是 `ShowBlockPage`
userMessage	字符串	是	要向用户显示的消息。

收到阻止响应时的最终用户体验

一个示例图像，显示 API 返回阻止响应后的最终用户体验的外观。

验证错误响应的示例

HTTP/1.1 400 Bad Request
Content-type: application/json

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code.",
}

参数	类型	必需	说明
版本	字符串	是	API 的版本。
action	字符串	是	值必须是 `ValidationError`。
状态	整数/字符串	是	其值必须为 `400` 或 `"400"`（表示验证错误响应）。
userMessage	字符串	是	要向用户显示的消息。

注意

HTTP 状态代码必须是“400”，此外，响应正文中必须包含“status”值。

收到验证错误响应时的最终用户体验

一个示例图像，显示 API 返回验证错误响应后的最终用户体验的外观。

最佳做法和故障排除方法

使用无服务器云函数

无服务器函数（例如 Azure Functions 中的 HTTP 触发器）可让用户创建与 API 连接器配合使用的 API 终结点。举例而言，可以使用无服务器云函数来执行验证逻辑，并仅限通过特定的电子邮件域进行注册。无服务器云函数还可以调用其他 Web API、数据存储和其他云服务，以实现复杂的方案。

最佳做法

请确保：

API 遵循上面所述的 API 请求和响应协定。
API 连接器的终结点 URL 指向正确的 API 终结点。
API 会显式检查它所依赖的已收到声明是否有 null 值。
你的 API 会实现保护 API 连接器中概述的身份验证方法。
API 可以尽快做出响应，以确保用户体验流畅。
- Microsoft Entra ID 最多会等待 20 秒来接收响应。如果未收到任何内容，它会再次尝试（重试）调用 API。
- 如果使用无服务器函数或可缩放的 Web 服务，请使用能够在生产环境中让 API 保持“清醒”或“热身”状态的托管计划。对于 Azure Functions，建议至少使用高级计划。
确保 API 的高可用性。
监视和优化下游 API、数据库或 API 的其他依赖项的性能。
终结点必须符合 Microsoft Entra TLS 和密码的安全要求。有关详细信息，请参阅 TLS 和密码套件要求。

使用日志记录

一般情况下，使用 Web API 服务（例如 Application insights）启用的日志记录工具来监视 API 是否出现意外错误代码、异常和性能不佳的情况会很有帮助。

监视非 HTTP 200 或 400 的 HTTP 状态代码。
401 或 403 HTTP 状态代码通常指示身份验证出现了问题。反复检查 API 的身份验证层以及 API 连接器中的相应配置。
如果需要，请在开发中使用更主动的日志记录级别（例如“跟踪”或“调试”）。
监视 API 的响应时间是否太长。

后续步骤

了解如何将自定义审批工作流添加到自助注册
参考快速入门示例帮助自己入门。

通过

向用户流添加 API 连接器

创建 API 连接器

发送到 API 的请求

在用户流中启用 API 连接器

执行此步骤时发送到 API 的示例请求

执行此步骤时来自 Web API 的预期响应类型

继续响应

阻止响应

创建用户之前

执行此步骤时发送到 API 的示例请求

执行此步骤时来自 Web API 的预期响应类型

继续响应

阻止响应

验证错误响应

示例响应

继续响应的示例

阻止响应的示例

验证错误响应的示例

最佳做法和故障排除方法

使用无服务器云函数

最佳做法

使用日志记录

后续步骤

反馈

其他资源

通过

向用户流添加 API 连接器

创建 API 连接器

发送到 API 的请求

在用户流中启用 API 连接器

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

执行此步骤时发送到 API 的示例请求

执行此步骤时来自 Web API 的预期响应类型

继续响应

阻止响应

创建用户之前

执行此步骤时发送到 API 的示例请求

执行此步骤时来自 Web API 的预期响应类型

继续响应

阻止响应

验证错误响应

示例响应

继续响应的示例

阻止响应的示例

验证错误响应的示例

最佳做法和故障排除方法

使用无服务器云函数

最佳做法

使用日志记录

后续步骤

反馈

其他资源