使用 PIM 为Microsoft Entra角色 API 分配管理角色

Privileged Identity Management (PIM) 使组织能够管理对Microsoft Entra ID中资源的管理访问权限。 管理访问权限可以通过可分配角色的组或Microsoft Entra角色进行。 PIM 通过限制访问处于活动状态的时间、管理访问范围以及提供特权访问的可审核日志来帮助管理特权访问的风险。

Contoso 希望使用安全组将管理角色分配给主体。 公司分配资格,而不是永久处于活动状态的管理角色。 此方法在以下方面有效:

  • 删除现有组成员或添加更多组成员也会删除管理员。
  • 组成员继承符合条件的角色分配。 可以向组分配更多角色,而不是直接向单个用户分配角色。
  • 通过分配资格而不是永久处于活动状态的用户管理员权限,公司可以强制实施 实时访问,从而授予执行特权任务的临时权限。 当组成员需要使用特权时,他们激活其分配的临时时间段。 公司可审核角色激活的所有记录。

在本教程中,你将了解如何:

  • 创建可分配角色的安全组。
  • 使可分配角色的安全组符合管理角色的条件。
  • 通过激活用户的合格分配,向用户授予实时访问权限。

先决条件

若要完成本教程,需要以下资源和特权:

  • 启用了 Microsoft Entra ID P2 或 Microsoft Entra ID 治理 许可证的工作Microsoft Entra租户。
  • 登录到 API 客户端(如 Graph 资源管理器), 使用至少具有 特权角色管理员 角色的帐户调用 Microsoft Graph。
    • [可选]在另一个浏览器中启动新的匿名会话。 稍后将在本教程中登录。 启用了 MFA 的测试用户,你有权访问其 Microsoft Authenticator 应用帐户。
  • 授予自己以下委托的权限: Group.ReadWrite.AllDirectory.Read.All、、 RoleEligibilitySchedule.ReadWrite.DirectoryRoleAssignmentSchedule.ReadWrite.DirectoryRoleManagement.ReadWrite.Directory

步骤 1:创建可分配角色的安全组

将自己分配为组所有者,并将你和测试用户都分配为成员。

请求:创建可分配角色的组

POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json

{
    "description": "IT Helpdesk to support Contoso employees",
    "displayName": "IT Helpdesk (User)",
    "mailEnabled": false,
    "mailNickname": "userHelpdesk",
    "securityEnabled": true,
    "isAssignableToRole": true,
    "owners@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/1ed8ac56-4827-4733-8f80-86adc2e67db5"
    ],
    "members@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/1ed8ac56-4827-4733-8f80-86adc2e67db5",
        "https://graph.microsoft.com/v1.0/users/7146daa8-1b4b-4a66-b2f7-cf593d03c8d2"
    ]
}

响应

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "@odata.id": "https://graph.microsoft.com/v2/29a4f813-9274-4e1b-858d-0afa98ae66d4/directoryObjects/e77cbb23-0ff2-4e18-819c-690f58269752/Microsoft.DirectoryServices.Group",
    "id": "e77cbb23-0ff2-4e18-819c-690f58269752",
    "description": "IT Helpdesk to support Contoso employees",
    "displayName": "IT Helpdesk (User)",
    "groupTypes": [],
    "isAssignableToRole": true,
    "mailEnabled": false,
    "mailNickname": "userHelpdesk",
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-3883711267-1310199794-258579585-1385637464",
    "visibility": "Private",
    "onPremisesProvisioningErrors": []
}

步骤 2:创建 unifiedRoleEligibilityScheduleRequest

现在你已拥有可分配角色的安全组,请将其分配为有资格获得一年的用户管理员角色。 将符合条件的分配范围限定为整个租户。 此租户级范围允许用户管理员对租户中的所有用户使用其特权,但特权较高的用户(例如全局管理员)除外。

请求

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleEligibilityScheduleRequests
Content-type: application/json

{
    "action": "AdminAssign",
    "justification": "Assign User Admin eligibility to IT Helpdesk (User) group",
    "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
    "directoryScopeId": "/",
    "principalId": "e77cbb23-0ff2-4e18-819c-690f58269752",
    "scheduleInfo": {
        "startDateTime": "2021-07-01T00:00:00Z",
        "expiration": {
            "endDateTime": "2022-06-30T00:00:00Z",
            "type": "AfterDateTime"
        }
    }
}

响应

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#roleManagement/directory/roleEligibilityScheduleRequests/$entity",
    "id": "64a8bd54-4591-4f6a-9c77-3e9cb1fdd29b",
    "status": "Provisioned",
    "createdDateTime": "2021-09-03T20:45:28.3848182Z",
    "completedDateTime": "2021-09-03T20:45:39.1194292Z",
    "action": "AdminAssign",
    "principalId": "e77cbb23-0ff2-4e18-819c-690f58269752",
    "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
    "directoryScopeId": "/",
    "isValidationOnly": false,
    "targetScheduleId": "64a8bd54-4591-4f6a-9c77-3e9cb1fdd29b",
    "justification": "Assign User Admin eligibility to IT Helpdesk (User) group",
    "createdBy": {
        "user": {
            "id": "1ed8ac56-4827-4733-8f80-86adc2e67db5"
        }
    },
    "scheduleInfo": {
        "startDateTime": "2021-09-03T20:45:39.1194292Z",
        "expiration": {
            "type": "afterDateTime",
            "endDateTime": "2022-06-30T00:00:00Z"
        }
    },
    "ticketInfo": {}
}

步骤 3:确认用户的当前角色分配

虽然组成员现在 有资格获得 用户管理员角色,但他们仍无法使用该角色,除非他们显式激活角色。 可以通过检查用户的当前角色分配进行确认。

请求

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=principalId eq '7146daa8-1b4b-4a66-b2f7-cf593d03c8d2'

响应

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#roleManagement/directory/roleAssignments",
    "value": []
}

空响应对象显示用户在 Contoso 中没有现有的Microsoft Entra角色。 用户现在将在有限的时间内激活其符合条件的用户管理员角色。

步骤 4:用户自行激活其符合条件的分配

事件票证 CONTOSO:在 Contoso 的事件管理系统中提出了 Security-012345,公司要求所有员工的刷新令牌都失效。 作为 IT 支持人员的成员,Aline 负责完成此任务。

首先,在手机上启动 Authenticator 应用,然后打开 Aline Dupuy 的帐户。

以 Aline 身份登录到 Graph 资源管理器。 可以使用其他浏览器执行此步骤。 这样做不会中断当前会话。 或者,可以通过注销 Graph 资源管理器并以 Aline 身份重新登录来中断当前会话。

登录后,激活用户管理员角色五小时。

请求

若要激活角色,请 roleAssignmentScheduleRequests 调用终结点。 在此请求中,操作 UserActivate 允许激活符合条件的分配。

  • 对于 principalId,请提供 (Aline) ID 的值。
  • roleDefinitionId 是你有资格获得的角色的 ID,在本例中为“用户管理员”角色。
  • 输入票证系统的详细信息,该票证系统提供了激活请求的可审核理由。
POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignmentScheduleRequests
Content-type: application/json

{
    "action": "SelfActivate",
    "principalId": "7146daa8-1b4b-4a66-b2f7-cf593d03c8d2",
    "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
    "directoryScopeId": "/",
    "justification": "Need to invalidate all app refresh tokens for Contoso users.",
    "scheduleInfo": {
        "startDateTime": "2024-03-25T15:13:00.000Z",
        "expiration": {
            "type": "AfterDuration",
            "duration": "PT5H"
        }
    },
    "ticketInfo": {
        "ticketNumber": "CONTOSO:Security-012345",
        "ticketSystem": "Contoso ICM"
    }
}

响应

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#roleManagement/directory/roleAssignmentScheduleRequests/$entity",
    "id": "295edd40-4646-40ca-89b8-ab0b46b6f60e",
    "status": "Granted",
    "createdDateTime": "2021-09-03T21:10:49.6670479Z",
    "completedDateTime": "2021-09-04T15:13:00Z",
    "action": "SelfActivate",
    "principalId": "7146daa8-1b4b-4a66-b2f7-cf593d03c8d2",
    "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
    "directoryScopeId": "/",
    "isValidationOnly": false,
    "targetScheduleId": "295edd40-4646-40ca-89b8-ab0b46b6f60e",
    "justification": "Need to invalidate all app refresh tokens for Contoso users.",
    "createdBy": {
        "user": {
            "id": "7146daa8-1b4b-4a66-b2f7-cf593d03c8d2"
        }
    },
    "scheduleInfo": {
        "startDateTime": "2021-09-04T15:13:00Z",
        "expiration": {
            "type": "afterDuration",
            "endDateTime": null,
            "duration": "PT5H"
        }
    },
    "ticketInfo": {
        "ticketNumber": "CONTOSO:Security-012345",
        "ticketSystem": "Contoso ICM"
    }
}

可以通过运行 GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignmentScheduleRequests/filterByCurrentUser(on='principal')来确认分配。 响应对象返回新激活的角色分配,其状态设置为 Granted。 使用新权限,在分配处于活动状态的五小时内执行任何允许的操作。 五小时后,活动分配将过期,但通过 IT 支持 (用户) 组中的成员身份,你有资格获得用户管理员角色。

步骤 6:清理资源

以全局管理员身份登录并删除为本教程创建的以下资源:角色资格请求和 IT 支持 (用户) 组。

撤销角色资格请求

请求

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleEligibilityScheduleRequests
Content-type: application/json

{
    "action": "AdminRemove",
    "principalId": "e77cbb23-0ff2-4e18-819c-690f58269752",
    "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
    "directoryScopeId": "/"
}

响应

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#roleManagement/directory/roleEligibilityScheduleRequests/$entity",
    "id": "dcd11a1c-300f-4d17-8c7a-523830400ec8",
    "status": "Revoked",
    "action": "AdminRemove",
    "principalId": "e77cbb23-0ff2-4e18-819c-690f58269752",
    "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
    "directoryScopeId": "/"
}

删除 IT 支持 (用户) 组

请求会返回 204 No Content 响应代码。

DELETE https://graph.microsoft.com/v1.0/groups/e77cbb23-0ff2-4e18-819c-690f58269752

总结

本教程介绍了如何使用 PIM API 在 Microsoft Entra ID 中管理管理角色分配。

  • 使组有资格担任管理角色时,也可以向组分配活动角色,并使成员有资格加入该组。 在此方案中,对组 API 使用 PIM。
  • 测试用户需要 MFA 才能激活其角色。 此要求是Microsoft Entra角色设置的一部分,你可以将规则更改为不需要 MFA。
  • 作为可配置规则的一部分,还可以配置以下设置:
    • 限制角色激活的最长允许持续时间。
    • 需要或不需要理由和票证信息来激活角色。