本文档提供Microsoft Entra API 驱动的入站用户预配的概念性概述。
介绍
如今，企业有各种权威记录制度。 若要建立端到端标识生命周期，加强安全态势，并遵守法规，Microsoft Entra ID 中的标识数据必须与这些记录系统中管理的员工数据保持同步。 记录系统可以是托管在本地或云中的数据库中的 HR 应用、工资单应用、电子表格或 SQL 表。
使用 API 驱动的入站预配，Microsoft Entra 预配服务现在支持与 任何 记录系统集成。 客户和合作伙伴可以使用他们选择 的任何 自动化工具从记录系统中检索员工数据，并将其引入到 Microsoft Entra ID 中。 IT 管理员完全控制如何使用属性映射处理和转换数据。 在 Microsoft Entra ID 中提供员工数据后，IT 管理员可以使用 生命周期工作流配置适当的 joiner-mover-leaver 业务流程。
支持的场景
使用 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 管理中心管理的基于规则的属性流和转换。
端到端流程
工作流的步骤
- IT 管理员从 Microsoft Entra Enterprise 应用库配置 API 驱动的入站用户预配应用 。
- IT 管理员 授予访问权限， 并向 API 开发人员/合作伙伴/系统集成商提供终结点访问权限详细信息。
- API 开发人员/合作伙伴/系统集成商生成 API 客户端，以将权威标识数据发送到 Microsoft Entra ID。
- API 客户端从权威源读取标识数据。
- API 客户端将 POST 请求发送到与预配应用关联的预配 /bulkUpload API 终结点。
注释
API 客户端不需要在源属性和目标属性值之间执行任何比较，以确定要调用的操作（创建/更新/启用/禁用）。 此设置由预配服务自动处理。 API 客户端只需使用 SCIM 架构构造将其打包为批量请求来上传从源系统读取的标识数据。
- 如果成功，则返回一个
Accepted 202 Status。 - Microsoft Entra 预配服务处理收到的数据、应用属性映射规则并完成用户预配。
- 根据配置的预配应用，将用户预配到本地 Active Directory（适用于混合用户）或Microsoft Entra ID（仅适用于仅限云的用户）。
- 然后，API 客户端查询预配日志 API 终结点，以获取发送的每个记录的状态。
- 如果处理任何记录失败，API 客户端可以检查错误详细信息，并在下一个批量请求（步骤 5）中包含与失败操作对应的记录。
- 随时，IT 管理员可以检查预配作业的状态，并在预配日志中查看事件。
API 驱动的入站用户预配的主要功能
- 作为公开使用有效 OAuth 令牌访问的 异步 Microsoft图形预配 /bulkUpload API 终结点的预配应用提供。
- 租户管理员必须向与此预配应用交互的 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 中的特定预配应用相关联。 可以通过为每个数据源创建预配应用来集成多个数据源。
- 传入批量请求有效负载几乎实时处理。
- 管理员可以通过查看预配 日志来检查预配进度。
- API 客户端可以通过查询 预配日志 API 来跟踪进度。
许可要求
此功能适用于 Microsoft Entra ID P1、P2 和 Microsoft Entra ID Governance 许可证。 若要查找符合要求的正确许可证，请参阅 Microsoft Entra ID Governance 许可基础知识。
API 使用指南
/bulkUpload API 终结点扩展了可在 Microsoft Entra ID 中管理用户的方式。 为了帮助你确定 API 终结点是否 /bulkUpload 适合你的集成方案，请参阅此表，将其与其他基于 API 的集成选项进行比较。
| 用例方案到 API 的映射 | 用户创建 API | HR 入站批量 API | 用户邀请 API | 直接分配 API |
|---|---|---|---|---|
| 当标识创建方案为... | 在Microsoft未与 HR 源中的任何辅助角色关联的用户的 Entra ID 中创建即席用户 | 从权威 HR 源中采购员工记录，并希望这些员工在 Microsoft Entra ID 或本地 Active Directory 中有“成员”帐户 | 在 Microsoft Entra ID 中创建临时来宾用户，用于共享目的，其中来宾具有唯一的访问权限 | 为现有用户分配（预览版）来宾创建Microsoft Entra ID，为新的来宾提供标准化访问权限 |
| ...使用 API... | 创建用户 | 执行 bulkUpload。 | 创建邀请 | 创建 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 管理中心 |
| 用户就业开始时的生命周期由... | 手动进程 | 基于属性触发的 employeeHireDate 条目载入生命周期工作流 |
权利管理 | 使用权利管理访问包进行自动分配 |
| 终止其雇佣时用户生命周期由... | 手动进程 | 基于属性触发的 employeeLeaveDateTime 载入生命周期工作流 |
访问权限审查 | 当用户失去上次访问包分配时的权利管理，将被删除 |
推荐的学习路径
| # | 学习目标 | Guidance |
|---|---|---|
| 1。 | 想要了解有关入站预配 API 规范的详细信息。 | 请参阅 /bulkUpload API 规范文档。 |
| 2. | 你希望更熟悉 API 驱动的预配概念、方案和限制。 | 请参阅 有关 API 驱动的入站预配的常见问题解答。 |
| 3. | 作为 管理员用户，需要快速测试入站预配 API。 | * 创建 API 驱动的入站预配应用 |
| 4. | 使用服务帐户或托管标识，需要快速测试入站预配 API。 | * 创建 API 驱动的入站预配应用 * 授予 API 权限 * 使用 cURL 测试 API |
| 5. | 你想要扩展 API 驱动的预配应用以处理更多自定义属性。 | 请参阅教程 ：扩展 API 驱动的预配以同步自定义属性 |
| 6. | 你想要将数据从记录系统自动上传到入站预配 API 终结点。 | 请参阅教程 * PowerShell 快速入门 * Azure 逻辑应用快速入门 |
| 7. | 你想要排查入站预配 API 问题 | 请参阅 故障排除指南。 |
外部学习资源
合作伙伴和Microsoft MVP 创建的以下内容提供了有关如何为各种集成方案部署和配置 API 驱动的预配的额外指导。
- 博客文章、演示文稿和其他有用链接
- Microsoft MVP Pim Jacob 的文章，介绍如何 对本地 Active Directory 执行 Bamboo HR API 驱动的预配
- Microsoft MVP Pim Jacob 的演示 ，介绍如何使用 API 驱动的预配和生命周期工作流配置联接器和离开器流程
- Microsoft MVP Marius Solbakken 的文章，介绍如何 使用 PowerShell 脚本和 API 驱动的预配来源 Excel 数据
- Suryendu Bhattacharyya 的文章 介绍如何使用自定义 GitHub 操作调用 API 驱动预配
- Microsoft MVP Jan Vidar Elven 的 Bicep 模板进行 API 驱动的预配