使用 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 资源角色,请使用适用于 Azure 资源管理器 (ARM) 的 PIM API

用于管理活动角色分配的 PIM API

PIM 允许通过创建永久分配或临时分配来管理活动角色分配。 使用 unifiedRoleAssignmentScheduleRequest 资源类型及其相关方法来管理角色分配。

下表列出了使用 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 中,这些规则通过 unifiedRoleManagementPolicyunifiedRoleManagementPolicyAssignment 资源类型及其相关方法进行管理。

例如,假设默认情况下,角色不允许永久活动分配,并且为活动分配定义了最长 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 配置规则的详细信息,请参阅 Microsoft Graph 中 PIM API 中Microsoft Entra角色的规则概述。 有关更新规则的示例,请参阅在 Microsoft Graph 中使用 PIM API 更新Microsoft Entra ID规则

Microsoft Entra角色的安全警报

Microsoft Entra角色的 PIM 在检测到租户中Microsoft Entra角色的可疑或不安全设置时,会生成警报。 以下七种警报类型可用:

通知 Microsoft Graph 资源 (警报配置/事件)
租户中的全局管理员过多 tooManyGlobalAdminsAssignedToTenantAlertConfiguration / tooManyGlobalAdminsAssignedToTenantAlertIncident
限制 PIM 使用的无效许可证警报 invalidLicenseAlertConfiguration / invalidLicenseAlertIncident
为激活配置的角色,无需多重身份验证 noMfaOnRoleActivationAlertConfiguration / noMfaOnRoleActivationAlertIncident
具有未使用的合格或活动Microsoft Entra角色分配的用户 redundantAssignmentAlertConfiguration / redundantAssignmentAlertIncident
Microsoft Entra Privileged Identity Management外部分配的角色 rolesAssignedOutsidePrivilegedIdentityManagementAlertConfiguration / rolesAssignedOutsidePrivilegedIdentityManagementAlertIncident
Microsoft Entra角色激活过于频繁 sequentialActivationRenewalsAlertConfiguration / sequentialActivationRenewalsAlertIncident
特权角色中可能过时的帐户 staleSignInAlertConfiguration / staleSignInAlertIncident

有关这些警报(包括严重性评级和触发器)的详细信息,请参阅在 PIM 中为Microsoft Entra角色配置安全警报

PIM 警报 API 的构建基块

使用以下 Microsoft Graph 资源来管理 PIM 警报。

资源 说明 API 操作
unifiedRoleManagementAlert 提供 PIM 中针对Microsoft Entra角色的警报摘要,无论这些警报是启用或禁用的,是 PIM 服务上次扫描租户中是否存在事件或此警报,还是在租户中映射到此警报类型的事件数。 PIM 服务每天扫描租户中与警报相关的事件,但你也可以运行手动扫描。 List

获取

更新

刷新 (手动扫描)
unifiedRoleManagementAlertDefinition 提供每种警报类型的详细说明、严重性级别、缓解与租户中警报相关的事件的建议步骤,以及防止将来发生的建议操作。 List

获取
unifiedRoleManagementAlertConfiguration 警报的租户特定配置,包括 PIM 服务是否应扫描租户中与警报相关的事件、触发警报的阈值和相关警报定义。 这是一种抽象类型,从中派生表示单个警报类型的资源。 List

获取

更新
unifiedRoleManagementAlertIncident 租户中与警报类型匹配的事件。 List

获取

修正

有关为Microsoft Entra角色使用安全警报的详细信息,请参阅在 Privileged Identity Management 中为Microsoft Entra角色配置安全警报

有关使用 PIM API 处理Microsoft Entra角色的安全警报的详细信息,请参阅在 Microsoft Graph 中使用 PIM API 管理Microsoft Entra角色的安全警报

审核日志

通过 PIM 为Microsoft Entra角色执行的所有活动都记录在审核日志Microsoft Entra,你可以通读列表目录审核 API。

零信任

此功能可帮助组织将其标识与零信任体系结构的三个指导原则保持一致:

  • 显式验证
  • 使用最低特权
  • 假定漏洞

若要详细了解零信任和其他使组织符合指导原则的方法,请参阅零信任指导中心

授权

使用Privileged Identity Management的租户必须具有足够的购买许可证或试用许可证。 有关详细信息,请参阅使用Privileged Identity Management的许可证要求