使用 PIM API 管理Microsoft Entra角色分配
Privileged Identity Management (PIM) 是Microsoft Entra ID 治理的一项功能，可用于管理、控制和监视对组织中重要资源的访问。 用户、组和服务主体等主体 (应用程序) 获得对重要资源的访问权限的一种方法是通过分配Microsoft Entra角色。
Microsoft Entra角色 API 的 PIM 允许你管理特权访问，并限制对Microsoft Entra角色的过度访问。 本文介绍适用于 Microsoft Graph 中Microsoft Entra角色 API 的 PIM 的治理功能。
注意
若要管理 Azure 资源角色，请使用适用于 PIM 的 Azure 资源管理器 API。
用于管理Microsoft Entra角色的安全警报的 PIM API 仅在终结点上/beta可用。 有关详细信息，请参阅Microsoft Entra角色的安全警报。
分配角色的方法
用于Microsoft Entra角色的 PIM 提供了两种将角色分配给主体的方法：
- 活动角色分配：主体可以具有永久或临时的永久活动角色分配。
- 符合条件的角色分配：主体可以永久或暂时获得角色。 使用符合条件的身份，主体在需要执行特权任务时激活其角色，从而创建临时活动的角色分配。 激活始终有时间限制，最长为 8 小时，但在角色设置中可以降低最大持续时间。 激活也可以续订或延长。
用于管理活动角色分配的 PIM API
PIM 允许通过创建永久分配或临时分配来管理活动角色分配。 使用 unifiedRoleAssignmentScheduleRequest 资源类型及其相关方法来管理角色分配。
注意
建议使用 PIM 来管理活动角色分配，而不是使用 unifiedRoleAssignment 或 directoryRole 资源类型直接管理它们。
下表列出了使用 PIM 管理角色分配和要调用的 API 的方案。
| 应用场景 | API |
|---|---|
| 管理员创建永久角色分配并分配给主体 管理员向主体分配临时角色 |
创建 roleAssignmentScheduleRequests |
| 管理员续订、更新、扩展或删除角色分配 | 创建 roleAssignmentScheduleRequests |
| 管理员查询所有角色分配及其详细信息 | 列出 roleAssignmentScheduleRequests |
| 管理员查询角色分配及其详细信息 | 获取 unifiedRoleAssignmentScheduleRequest |
| 主体查询其角色分配和详细信息 | unifiedRoleAssignmentScheduleRequest： filterByCurrentUser |
| 主体对其 符合条件的 角色分配执行实时和有时间限制的激活 | 创建 roleAssignmentScheduleRequests |
| 主体取消他们创建的角色分配请求 | unifiedRoleAssignmentScheduleRequest：cancel |
| 已激活其合格角色分配的主体在不再需要访问权限时将其停用 | 创建 roleAssignmentScheduleRequests |
| 主体停用、扩展或续订自己的角色分配。 | 创建 roleAssignmentScheduleRequests |
用于管理角色资格的 PIM API
主体可能不需要永久角色分配，因为它们不需要通过特权角色一直授予的权限。 在这种情况下，PIM 还允许创建角色资格并将其分配给主体。 使用角色资格，主体在需要执行特权任务时激活角色。 激活始终有时间限制，最长为 8 小时。 主体也可以是永久或暂时符合条件的角色。
使用 unifiedRoleEligibilityScheduleRequest 资源类型及其相关方法来管理角色资格。
下表列出了使用 PIM 管理角色资格的方案以及要调用的 API。
| 应用场景 | API |
|---|---|
| 管理员创建并分配给主体的合格角色 管理员向主体分配临时角色资格 |
创建 roleEligibilityScheduleRequests |
| 管理员续订、更新、扩展或删除角色资格 | 创建 roleEligibilityScheduleRequests |
| 管理员查询所有角色资格及其详细信息 | 列出 roleEligibilityScheduleRequests |
| 管理员查询角色资格及其详细信息 | 获取 unifiedRoleEligibilityScheduleRequest |
| 管理员取消他们创建的角色资格请求 | unifiedRoleEligibilityScheduleRequest：cancel |
| 主体查询其角色资格和详细信息 | unifiedRoleEligibilityScheduleRequest：filterByCurrentUser |
| 主体停用、延长或续订自己的角色资格。 | 创建 roleEligibilityScheduleRequests |
角色设置和 PIM
每个Microsoft Entra角色定义设置或规则。 此类规则包括多重身份验证 (MFA) 、理由或批准是否需要激活符合条件的角色，或者是否可以为角色的主体创建永久分配或资格。 这些特定于角色的规则确定在通过 PIM 创建或管理角色分配和资格时可以应用的设置。
在 Microsoft Graph 中，这些规则通过 unifiedRoleManagementPolicy 和 unifiedRoleManagementPolicyAssignment 资源类型及其相关方法进行管理。
例如，假设默认情况下，角色不允许永久活动分配，并且为活动分配定义了最长 15 天。 尝试创建不带到期日期的 unifiedRoleAssignmentScheduleRequest 对象会 400 Bad Request 返回违反过期规则的响应代码。
PIM 允许配置各种规则，包括：
- 是否可以为主体分配永久合格分配
- 角色激活所允许的最长持续时间，以及激活符合条件的角色是否需要理由或批准
- 允许批准Microsoft Entra角色的激活请求的用户
- 激活和强制实施角色分配是否需要 MFA
- 收到角色激活通知的主体
下表列出了使用 PIM 管理Microsoft Entra角色的规则和要调用的 API 的方案。
| 应用场景 | API |
|---|---|
| 检索角色管理策略和关联的规则或设置 | 列出 unifiedRoleManagementPolicies |
| 检索角色管理策略及其关联的规则或设置 | 获取 unifiedRoleManagementPolicy |
| 更新角色管理策略的关联规则或设置 | 更新 unifiedRoleManagementPolicy |
| 检索为角色管理策略定义的规则 | List rules |
| 检索为角色管理策略定义的规则 | 获取 unifiedRoleManagementPolicyRule |
| 更新为角色管理策略定义的规则 | 更新 unifiedRoleManagementPolicyRule |
| 获取所有角色管理策略分配的详细信息，包括与Microsoft Entra角色关联的策略和规则或设置 | 列出 unifiedRoleManagementPolicyAssignments |
| 获取角色管理策略分配的详细信息，包括与Microsoft Entra角色关联的策略和规则或设置 | 获取 unifiedRoleManagementPolicyAssignment |
有关使用 Microsoft Graph 配置规则的详细信息，请参阅 PIM API 中Microsoft Entra角色的规则概述。 有关更新规则的示例，请参阅使用 PIM API 更新Microsoft Entra ID角色的规则。
审核日志
通过 PIM 为Microsoft Entra角色执行的所有活动都记录在审核日志Microsoft Entra，你可以通读列表目录审核 API。
零信任
此功能可帮助组织使其租户与零信任体系结构的三个指导原则保持一致：
- 显式验证
- 使用最低特权
- 假定漏洞
若要详细了解零信任和其他使组织符合指导原则的方法，请参阅零信任指导中心。
授权
使用Privileged Identity Management的租户必须具有足够的购买许可证或试用许可证。 有关详细信息，请参阅Microsoft Entra ID 治理许可基础知识。
相关内容
- 若要了解有关安全操作的详细信息，请参阅Microsoft Entra体系结构中心Microsoft Entra Privileged Identity Management的安全操作。