本文档提供了 Microsoft Entra API 驱动的入站用户预配的概念性概述。
Introduction
如今，企业拥有各种权威的记录系统。 若要建立端到端标识生命周期、加强安全态势并遵守法规，Microsoft Entra ID 中的标识数据必须与这些记录系统中管理的员工数据保持同步。 记录系统可以是本地或云中托管的数据库中的 HR 应用、工资单应用、电子表格或 SQL 表。
With API-driven inbound provisioning, the Microsoft Entra provisioning service now supports integration with any system of record. Customers and partners can use any automation tool of their choice to retrieve workforce data from the system of record and ingest it into Microsoft Entra ID. IT 管理员可完全控制如何使用属性映射处理和转换数据。 Once the workforce data is available in Microsoft Entra ID, the IT admin can configure appropriate joiner-mover-leaver business processes using Lifecycle Workflows.
Supported scenarios
使用 API 驱动的入站预配启用多个入站用户预配方案。 此图演示了最常见的方案。
方案 1：允许 IT 团队使用任何自动化工具导入 HR 数据提取
平面文件、CSV 文件和 SQL 临时表通常用于企业集成方案。 员工、承包商和供应商信息会定期导出为其中一种格式，同时会使用自动化工具将此数据与企业标识目录同步。 借助 API 驱动的入站预配，IT 团队可以使用他们选择的任何自动化工具 (示例：PowerShell 脚本或 Azure 逻辑应用) 将集成现代化和简化。
方案 2：支持 ISV 与 Microsoft Entra ID 建立直接集成
借助 API 驱动的入站预配，HR ISV 可以提供本机同步体验，以便 HR 系统中的更改自动流入 Microsoft Entra ID 和已连接的本地 Active Directory 域。 例如，HR 应用或学生信息系统应用可以在事务完成或在一天结束批量更新时立即将数据发送到 Microsoft Entra ID。
方案 3：使系统集成商能够构建更多到记录系统的连接器
合作伙伴可以生成自定义 HR 连接器，以满足从记录系统到 Microsoft Entra ID 的数据流的不同集成要求。
在上述所有方案中，集成都得到了简化，因为 Microsoft Entra 预配服务接管了执行标识配置文件比较的责任，将数据同步限制为 IT 管理员配置的范围逻辑，并执行 Microsoft Entra 管理中心内托管的基于规则的属性流和转换。
End-to-end flow
工作流的步骤
- IT 管理员从 Microsoft Entra Enterprise 应用库配置 API 驱动的入站用户预配应用。
- IT 管理员向 API 开发人员/合作伙伴/系统集成商授予访问权限并提供终结点访问详细信息。
- API 开发人员/合作伙伴/系统集成商生成 API 客户端，用于将权威标识数据发送到 Microsoft Entra ID。
- API 客户端从权威源读取标识数据。
- The API client sends a POST request to provisioning /bulkUpload API endpoint associated with the provisioning app.
Note
API 客户端无需对源属性和目标属性值执行任何比较，就能确定 (创建/更新/启用/禁用) 调用的操作。 这会由预配服务自动处理。 API 客户端只需使用 SCIM 架构构造将其打包为批量请求，即可上传从源系统读取的标识数据。
- 如果成功，则会返回
Accepted 202 Status。 - Microsoft Entra 预配服务会处理收到的数据、应用属性映射规则并完成用户预配。
- 根据配置的预配应用，将用户预配到本地 Active Directory（混合用户）或 Microsoft Entra ID（纯云用户）。
- 然后，API 客户端会查询预配日志 API 终结点，以获取发送的每个记录的状态。
- 如果处理任何记录失败，API 客户端可以检查错误详细信息，并在下一个批量请求（第 5 步）中添加与失败操作对应的记录。
- IT 管理员可以随时检查预配作业的状态，并在预配日志中查看事件。
API 驱动的入站用户预配的主要功能
- Available as a provisioning app that exposes an asynchronous Microsoft Graph provisioning /bulkUpload API endpoint accessed using valid OAuth token.
- 租户管理员必须向与此预配应用交互的 API 客户端授予图形权限
SynchronizationData-User.Upload（SynchronizationData-User.Upload.OwnedBy对于 ISV）和ProvisioningLog.Read.All。 - 图形 API 终结点使用 SCIM 架构构造接受有效的批量请求有效负载。
- 使用 SCIM 架构扩展，可以发送批量请求有效负载中的任何属性。
-
/bulkUploadAPI 终结点强制实施以下限制：- 任何 5 秒窗口中的 API 调用限制为 40 个。 如果超出此阈值，服务将返回 HTTP 429（请求过多）响应。 若要避免限制，请实现客户端中的节奏逻辑以缩小请求空间，例如在提交之间添加延迟或速率限制处理。
- Entra ID P1/P2 许可证下，租户级别限制为每 24 小时 2,000 个 API 调用，在 Entra ID Governance 许可证下有 6,000 个 API 调用。 超过这些限制会导致 HTTP 429（请求过多）响应。 若要保持在配额范围内，请确保 SCIM 批量有效负载经过优化，以便每个 API 调用最多包含 50 个作。
- 每个 API 终结点都与 Microsoft Entra ID 中的特定预配应用相关联。 可以通过为每个数据源创建预配应用来集成多个数据源。
- 将近乎实时地处理传入的批量请求有效负载。
- Admins can check provisioning progress by viewing the provisioning logs.
- API 客户端可以通过查询预配日志 API 来跟踪进度。
License requirements
此功能适用于 Microsoft Entra ID P1、P2 和 Microsoft Entra ID 治理许可证。 如需查找符合要求的许可证，请参阅《Microsoft Entra ID 治理许可基础知识》。
API 使用指南
/bulkUpload API 终结点增加了你可以在 Microsoft Entra ID 中管理用户的方法数量。 若要确定 /bulkUpload API 终结点是否适合集成方案，请参阅下表，该表将其与其他基于 API 的集成选项进行了比较。
| 用例方案到 API 的映射 | 用户创建 API | HR 入站批量 API | 用户邀请 API | 直接分配 API |
|---|---|---|---|---|
| 当标识创建方案... | 在 Microsoft Entra ID 中为某个不与 HR 源中的任何工作者关联的用户创建临时用户 | 从权威的 HR 源获取员工记录，并且你希望这些员工在 Microsoft Entra ID 或本地 Active Directory 中拥有“成员”帐户 | 在 Microsoft Entra ID 中创建临时来宾用户，用于共享目的，来宾拥有独特的访问权限 | 为现有用户分配访问权限，并在 Microsoft Entra ID 中创建来宾（预览版），为新来宾提供标准化访问权限 |
| ...使用 API... | Create user | Perform bulkUpload. | Create invitation | Create accessPackageAssignmentRequest |
| 生成的用户首先在... | Microsoft Entra ID | 本地 Active Directory 或 Microsoft Entra ID | Microsoft Entra ID | Microsoft Entra ID |
| 生成的用户向... | Microsoft Entra ID，其中包含你提供的密码 | Microsoft Entra ID 的本地 Active Directory，其中包含 Entra 生命周期工作流提供的临时访问密码 | 主租户或其他标识提供者 | 主租户或其他标识提供者 |
| 对用户的后续更新可以通过 | 图形 API 或 Microsoft Entra 管理中心 | 图形 API 或 HR 入站批量 API 或 Microsoft Entra 管理中心 | 图形 API 或 Microsoft Entra 管理中心 | 图形 API 或 Microsoft Entra 管理中心 |
| 用户开始受雇时的生命周期取决于... | Manual processes | 基于 属性触发的 employeeHireDate |
Entitlement management | Automatic assignment using Entitlement management access packages |
| 用户终止雇佣关系时的生命周期取决于... | Manual processes | 基于 属性触发的 employeeLeaveDateTime |
Access reviews | 用户丢失上次的访问包分配时的权利管理，用户会被移除 |
推荐的学习路径
| # | Learning objective | Guidance |
|---|---|---|
| 1. | 您希望详细了解入站预配 API 规范。 | Refer to /bulkUpload API spec document. |
| 2. | 你希望更熟悉 API 驱动的预配概念、方案和限制。 | 请参阅有关 API 驱动的入站预配的常见问题。 |
| 3. | As an Admin user, you want to quickly test the inbound provisioning API. | * 创建 API 驱动的入站预配应用 * 使用 Graph Explorer 测试 API |
| 4. | 使用服务帐户或托管标识，需要快速测试入站预配 API。 | * 创建 API 驱动的入站预配应用 * Grant API permissions * 使用 cURL 测试 API |
| 5. | 你想要扩展 API 驱动的预配应用，以处理更多自定义属性。 | 请参阅教程扩展 API 驱动的预配以同步自定义属性。 |
| 6. | 你想要将数据从记录系统自动上传到入站预配 API 终结点。 | 请参阅教程 * PowerShell 快速入门 * Azure 逻辑应用快速入门 |
| 7. | 你想排查入站预配 API 问题 | Refer to the Troubleshooting guide. |
外部学习资源
以下内容由我们的合作伙伴和 Microsoft MVP 创建，提供了有关如何针对各种集成方案部署和配置 API 驱动型预配的额外指导。
Video tutorials
- John Savill 讲述 API 驱动型预配的工作原理
- Microsoft MVP Nick Ross 讲述如何配置 API 驱动型预配
- Microsoft MVP Nick Ross 讲述如何使用 Power Automate 和 API 驱动型预配从 SharePoint 中的 Excel 文件获取 HR 数据
- Microsoft 合作伙伴的关于 API 驱动型预配的 IdentityXP 系列（共 4 部分）
博客文章、演示文稿和其他有用的链接
- Microsoft MVP Pim Jacob 的文章说明了如何执行到本地 Active Directory 的 Bamboo HR API 驱动型预配
- Microsoft MVP Pim Jacob 讲述如何使用 API 驱动型预配和生命周期工作流配置入职者和离职者流程
- Microsoft MVP Marius Solbakken 的文章说明了如何使用 PowerShell 脚本和 API 驱动型预配获取 Excel 数据
- Suryendu Bhattacharyya 的文章说明了如何使用自定义 GitHub Actions 调用 API 驱动型预配
- Microsoft MVP Jan Vidar Elven 讲述用于 API 驱动型预配的 Bicep 模板