向用户流添加 API 连接器

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

若要使用 API 连接器，请先创建 API 连接器，然后在用户流中启用它。

创建 API 连接器

1. 以至少用户管理员身份登录到 Microsoft Entra 管理中心。

2. 请导航到 Entra ID>外部标识>概述。

3. 依次选择“所有 API 连接器”、“新建 API 连接器”。

   

4. 为调用提供显示名称。 例如“检查审批状态”。

5. 为 API 调用提供“终结点 URL”。

6. 选择“身份验证类型”，并配置用于调用 API 的身份验证信息。 了解如何 保护 API 连接器。

   

7. 选择“保存”。

发送到 API 的请求

API 连接器具体化为 HTTP POST 请求，在 JSON 正文中将用户属性（“claims”）作为键值对发送。 属性的序列化方式类似于 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"
}

只有 Entra ID>外部标识>概述>自定义用户属性 体验中列出的用户属性和自定义属性才能在请求中发送。

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

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

• UI 区域设置（“ui_locales”） - 在其设备上配置的最终用户区域设置，API 可用于返回国际化响应。

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

在用户流中启用 API 连接器

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

1. 以至少用户管理员身份登录到 Microsoft Entra 管理中心。

2. 请导航到 Entra ID>外部标识>概述。

3. 选择“用户流”，然后选择要将 API 连接器添加到的用户流。

4. 选择“API 连接器”，然后选择要在执行用户流中的以下步骤时调用的 API 终结点：

   • 在注册期间与标识提供者进行联合之后
   • 创建用户之前

   

5. 选择“保存”。

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

在注册过程的此步骤中，在用户使用标识提供者（例如 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 提供的 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。

请参阅 阻止响应的示例。

验证错误响应

当 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
}

阻止响应的示例

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.",
}

具有阻止响应的最终用户体验

验证错误响应的示例

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.",
}

具有验证错误响应的最终用户体验

最佳做法和故障排除方法

使用无服务器云函数

无服务器函数（例如 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 的响应时间是否太长。

后续步骤

• 了解如何 将自定义审批工作流添加到自助注册
• 请使用我们的快速入门示例开始。