通过

使用访问评审 API 查看对管理角色的访问权限

Microsoft Graph 中的访问评审 API 使组织能够审核和证明标识 (也称为 主体) 分配给组织中的资源的访问权限。 组织中最敏感的资源之一是管理角色。 使用访问评审 API，组织可以定期证明根据组织策略有权访问管理角色的主体。

Contoso 需要确保仅为正确的受托人分配管理角色。 系统审核员还应审核访问评审历史记录，以报告 Contoso 内部控制的有效性。

在本教程中，你将了解如何：

  • 创建具有活动角色或符合条件的Microsoft Entra角色的主体的定期访问评审。
  • 调查应用于访问评审的决策。
  • 生成访问评审历史记录报告

先决条件

若要完成本教程，需要以下资源和特权：

  • 启用了 Microsoft Entra ID P2 或 Microsoft Entra ID 治理 许可证的工作Microsoft Entra租户。
  • 登录到图形 资源管理器 等 API 客户端，使用至少具有 标识治理管理员 角色的帐户调用 Microsoft Graph。
  • 主体（如安全组和单个用户）具有对Microsoft Entra角色（如用户管理员角色）的活动或合格分配。 他们的分配是访问评审的范围。 若要分配管理角色，请参阅教程：使用 Privileged Identity Management (PIM) API 分配Microsoft Entra角色。
  • 授予自己以下委托的权限： AccessReview.ReadWrite.All。

步骤 1：创建角色分配的访问评审

以下访问评审计划定义具有以下设置：

  • 评审范围是 (principalScopes 属性) 具有用户管理员角色访问权限的组和用户。
    • 访问评审的范围可以限定为多个主体类型 (用户和组，或者服务主体) ， 并且只能包含一个 资源。 若要评审对多个Microsoft Entra角色的访问权限，请创建单独的访问评审。
    • roleDefinitionId fe930be7-5e62-47db-91af-98c3a49a38b1 是Microsoft Entra用户管理员角色的全局模板标识符。
  • 用户管理员角色的活动分配和合格分配都在审核中。
  • 审阅者是单个用户。 你可以将自己指定为审阅者。
  • 审批者必须在批准访问Microsoft Entra角色之前提供理由。
  • 默认决策是 None 审阅者在实例过期之前不响应访问评审请求。
  • autoApplyDecisionsEnabled 未设置，默认为 false。 在这种情况下，评审完成后，不会自动应用决策，因此必须手动应用这些决策。
  • 评审在三天内每三个月重复一次，不会结束。

请求

POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions
Content-type: application/json

{
    "displayName": "Review access of users and groups to privileged roles",
    "descriptionForAdmins": "Review access of users and groups to privileged roles",
    "scope": {
        "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
        "principalScopes": [
            {
                "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                "query": "/users",
                "queryType": "MicrosoftGraph"
            },
            {
                "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                "query": "/groups",
                "queryType": "MicrosoftGraph"
            }
        ],
        "resourceScopes": [
            {
                "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                "query": "/roleManagement/directory/roleDefinitions/fe930be7-5e62-47db-91af-98c3a49a38b1",
                "queryType": "MicrosoftGraph"
            }
        ]
    },
    "reviewers": [
        {
            "query": "/users/2560f739-2e0e-4550-9fa0-1a1e67ae0ab8",
            "queryType": "MicrosoftGraph"
        }
    ],
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": false,
        "defaultDecision": "None",
        "instanceDurationInDays": 1,
        "recommendationsEnabled": false,
        "recurrence": {
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 3
            },
            "range": {
                "type": "noEnd",
                "startDate": "2024-03-25"
            }
        }
    }
}

响应

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions/$entity",
    "id": "02800b79-1a6f-40b7-8381-c0bebc3763bd",
    "displayName": "Review access of users and groups to privileged roles",
    "status": "NotStarted",
    "descriptionForAdmins": "Review access of users and groups to privileged roles",
    "scope": {
        "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
        "principalScopes": [
            {
                "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                "query": "/users",
                "queryType": "MicrosoftGraph"
            },
            {
                "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                "query": "/groups",
                "queryType": "MicrosoftGraph"
            }
        ],
        "resourceScopes": [
            {
                "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                "query": "/roleManagement/directory/roleDefinitions/fe930be7-5e62-47db-91af-98c3a49a38b1",
                "queryType": "MicrosoftGraph"
            }
        ]
    },
    "reviewers": [
        {
            "query": "/users/2560f739-2e0e-4550-9fa0-1a1e67ae0ab8",
            "queryType": "MicrosoftGraph"
        }
    ],
    "fallbackReviewers": [],
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": false,
        "defaultDecision": "None",
        "instanceDurationInDays": 1,
        "autoApplyDecisionsEnabled": false,
        "recommendationsEnabled": false,
        "recommendationLookBackDuration": null,
        "decisionHistoriesForReviewersEnabled": false,
        "recurrence": {
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 3,
                "month": 0,
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "firstDayOfWeek": "sunday",
                "index": "first"
            },
            "range": {
                "type": "noEnd",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2024-03-25",
                "endDate": null
            }
        },
        "applyActions": [],
        "recommendationInsightSettings": []
    },
    "stageSettings": [],
    "additionalNotificationRecipients": []
}

步骤 2：检索访问评审的实例

每个访问评审实例表示 每个重复周期，每个 唯一的资源正在审查。 由于你定义了定期访问评审，因此实例的 ID 与步骤 1 中的计划定义的 ID 不同。

请求

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/02800b79-1a6f-40b7-8381-c0bebc3763bd/instances

响应

此访问评审实例的状态为 InProgress，这意味着评审实例可供审阅者提交决策，并且此访问评审实例的期限尚未过期。 还收到来自 Azure Microsoft 的电子邮件通知，要求执行访问评审。

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('02800b79-1a6f-40b7-8381-c0bebc3763bd')/instances",
    "@odata.count": 1,
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET identityGovernance/accessReviews/definitions('<guid>')/instances?$select=endDateTime,fallbackReviewers",
    "value": [
        {
            "id": "30f0cb53-da42-402e-8be5-9005f9c374f7",
            "startDateTime": "2024-03-25T09:38:15.177Z",
            "endDateTime": "2024-03-26T09:38:15.177Z",
            "status": "InProgress",
            "scope": {
                "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
                "principalScopes": [
                    {
                        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                        "query": "/v1.0/users",
                        "queryType": "MicrosoftGraph"
                    },
                    {
                        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                        "query": "/v1.0/groups",
                        "queryType": "MicrosoftGraph"
                    }
                ],
                "resourceScopes": [
                    {
                        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                        "query": "/beta/roleManagement/directory/roleDefinitions/fe930be7-5e62-47db-91af-98c3a49a38b1",
                        "queryType": "MicrosoftGraph"
                    }
                ]
            },
            "reviewers": [
                {
                    "query": "/v1.0/users/2560f739-2e0e-4550-9fa0-1a1e67ae0ab8",
                    "queryType": "MicrosoftGraph"
                }
            ],
            "fallbackReviewers": []
        }
    ]
}

步骤 3：在记录任何决策之前检索访问评审决策

在发布决策之前，让我们先检查等待决策的项目。

请求

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/02800b79-1a6f-40b7-8381-c0bebc3763bd/instances/30f0cb53-da42-402e-8be5-9005f9c374f7/decisions

响应

以下响应显示了两个决策项，每个项对应于每个主体访问资源所需的决策。 由于步骤 1 中未启用建议，因此没有可用的建议。 作为审阅者，你现在可以提交访问评审实例的决策。

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('02800b79-1a6f-40b7-8381-c0bebc3763bd')/instances('30f0cb53-da42-402e-8be5-9005f9c374f7')/decisions",
    "@odata.count": 2,
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET identityGovernance/accessReviews/definitions('<guid>')/instances('<guid>')/decisions?$select=accessReviewId,appliedBy",
    "value": [
        {
            "id": "25bf64c2-2396-4efc-9bb8-e9dc39ee0441",
            "accessReviewId": "30f0cb53-da42-402e-8be5-9005f9c374f7",
            "decision": "NotReviewed",
            "applyResult": "New",
            "recommendation": "NoInfoAvailable",
            "principalLink": "https://graph.microsoft.com/v1.0/users/ad20a697-7be8-410a-bb08-207a21e6400d",
            "resourceLink": "https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/fe930be7-5e62-47db-91af-98c3a49a38b1",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "resource": {
                "id": "fe930be7-5e62-47db-91af-98c3a49a38b1",
                "displayName": "User Administrator",
                "type": "directoryRole"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "ad20a697-7be8-410a-bb08-207a21e6400d",
                "displayName": "Adele Vance",
                "type": "user",
                "userPrincipalName": "AdeleV@contoso.com",
                "lastUserSignInDateTime": ""
            }
        },
        {
            "id": "888007fa-1d32-4000-a359-fd1d5876a3ed",
            "accessReviewId": "30f0cb53-da42-402e-8be5-9005f9c374f7",
            "decision": "NotReviewed",
            "applyResult": "New",
            "recommendation": "NoInfoAvailable",
            "principalLink": "https://graph.microsoft.com/v1.0/groups/df434df5-5b8e-4044-9fa3-ac9d6ea45156",
            "resourceLink": "https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/fe930be7-5e62-47db-91af-98c3a49a38b1",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "resource": {
                "id": "fe930be7-5e62-47db-91af-98c3a49a38b1",
                "displayName": "User Administrator",
                "type": "directoryRole"
            },
            "principal": {
                "id": "df434df5-5b8e-4044-9fa3-ac9d6ea45156",
                "displayName": "User Administrators",
                "type": "group"
            }
        }
    ]
}

步骤 4：记录决策

假设公司策略要求通过安全组而不是直接授予单个主体对管理角色的访问权限。 根据公司策略，在批准组访问权限时发布拒绝 Adele Vance 访问的决定。

批准安全组的角色分配

在以下请求中，你批准 IT 支持组的访问权限。 请求返回 204 No Content 响应。

POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/02800b79-1a6f-40b7-8381-c0bebc3763bd/instances/30f0cb53-da42-402e-8be5-9005f9c374f7/decisions/888007fa-1d32-4000-a359-fd1d5876a3ed
Content-type: application/json

{
    "decision": "Approve",
    "justification": "The IT Helpdesk requires continued access to the User Administrator role to manage user account support requests, lifecycle, and access to resources"
}

拒绝单个用户的角色分配

在以下请求中，拒绝对 Adele Vance 的访问。 请求返回 204 No Content 响应。

POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/02800b79-1a6f-40b7-8381-c0bebc3763bd/instances/30f0cb53-da42-402e-8be5-9005f9c374f7/decisions/25bf64c2-2396-4efc-9bb8-e9dc39ee0441
Content-type: application/json

{
    "decision": "Deny",
    "justification": "Adele should join an allowed group to maintain access to the User Administrator role. For more details, refer to the company policy '#132487: Administrative roles'"
}

检索访问评审决策 (重复步骤 3) 时，它们具有以下设置：

  • 对于 Adele，IT 支持组的访问评审决策是 ApproveDeny。
  • reviewedBy 对象包含你作为审阅者的详细信息。
  • applyResult 表示 New 尚未应用决策。

虽然你记录了此实例的所有挂起的决策，但尚未将决策应用于资源和主体对象。 例如，Adele 仍具有用户管理员权限。 可以通过运行以下查询 https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=roleDefinitionId eq 'fe930be7-5e62-47db-91af-98c3a49a38b1'来验证此分配。 此行为是因为 autoApplyDecisionsEnabled 设置为 false，你尚未停止评审，或者实例周期尚未结束。

在本教程中，你不会手动停止实例，而是让它自动结束，然后应用决策。

提示

  1. 在访问评审实例 的状态 标记为 Completed之前，仍可以更改决策。 重新运行步骤 4，为主体应用不同的决策。
  2. 还可以手动停止访问评审实例，以便加快步骤 5 的进度。

步骤 5：应用访问评审决策

作为管理员，在访问评审实例 的状态 设置为 Completed后，可以应用决策。 请求会返回 204 No Content 响应代码。

POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/02800b79-1a6f-40b7-8381-c0bebc3763bd/instances/30f0cb53-da42-402e-8be5-9005f9c374f7/applyDecisions

Adele 失去了对用户管理员角色的访问权限，而 IT 支持组保持其访问权限。 可以通过运行以下查询 GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=roleDefinitionId eq 'fe930be7-5e62-47db-91af-98c3a49a38b1'来验证角色分配的此状态。

访问评审实例 的状态 现在 Applied为 。 此外，由于访问评审是重复的，因此会立即创建新实例。 其开始日期是从当前审阅实例的 endDateTime 开始的三个月。

步骤 6：检索访问评审历史记录定义

Contoso 的审核员还希望查看上一季度的访问评审历史记录。 在此示例中，为作用域为目录角色分配的所有 accessReviewScheduleDefinition 对象生成访问评审历史记录报告， (roleAssignmentScheduleInstances) 。 此查询包括访问评审以及历史记录报表中的所有决策。

首先，定义历史记录报表的范围。 然后，生成审核员用于下载报告的下载 URI。 下载 URI 仅在 24 小时内处于活动状态。 因此，到期后，可以从以前定义的历史记录报表重新生成另一个下载 URI。

定义访问评审历史记录数据的范围

请求

POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/historyDefinitions

{
    "displayName": "Last quarter's access reviews for administrative roles - User Administrator",
    "decisions": [],
    "reviewHistoryPeriodStartDateTime": "2024-03-24T00:00:00Z",
    "reviewHistoryPeriodEndDateTime": "9999-12-31T00:00:00Z",
    "scopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "queryType": "MicrosoftGraph",
            "query": "/identityGovernance/accessReviews/definitions?$filter=contains(scope/query, 'roleAssignmentScheduleInstances')"
        }
    ]
}

响应

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/historyDefinitions/$entity",
    "id": "841fc5d5-b89e-42cd-9f76-3343689aaabf",
    "displayName": "Last quarter's access reviews for administrative roles - User Administrator",
    "reviewHistoryPeriodStartDateTime": "2024-03-24T00:00:00Z",
    "reviewHistoryPeriodEndDateTime": "9999-12-31T00:00:00Z",
    "decisions": [
        "approve",
        "deny",
        "dontKnow",
        "notReviewed",
        "notNotified"
    ],
    "status": "requested",
    "createdDateTime": "2024-03-25T17:15:45.1940174Z",
    "createdBy": {
        "id": "2560f739-2e0e-4550-9fa0-1a1e67ae0ab8",
        "displayName": "MOD Administrator",
        "type": null,
        "userPrincipalName": "admin@contoso.com"
    },
    "scopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/identityGovernance/accessReviews/definitions?$filter=contains(scope/query, 'roleAssignmentScheduleInstances')",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ]
}

检索访问评审历史记录的实例

请求

POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/historyDefinitions/841fc5d5-b89e-42cd-9f76-3343689aaabf/instances

响应

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/historyDefinitions('841fc5d5-b89e-42cd-9f76-3343689aaabf')/instances",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET identityGovernance/accessReviews/historyDefinitions('<guid>')/instances?$select=downloadUri,expirationDateTime",
    "value": [
        {
            "id": "841fc5d5-b89e-42cd-9f76-3343689aaabf",
            "reviewHistoryPeriodStartDateTime": "2024-03-24T00:00:00Z",
            "reviewHistoryPeriodEndDateTime": "9999-12-31T00:00:00Z",
            "status": "done",
            "runDateTime": "2024-03-25T17:15:45.1940174Z",
            "fulfilledDateTime": "2024-03-25T17:16:06.5812358Z",
            "downloadUri": null
        }
    ]
}

请求

POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/historyDefinitions/841fc5d5-b89e-42cd-9f76-3343689aaabf/instances/841fc5d5-b89e-42cd-9f76-3343689aaabf/microsoft.graph.generateDownloadUri

响应

downloadUri 属性包含一个链接，用于下载 Excel 文件格式的历史记录报表。 此链接仅活动 24 小时。

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.accessReviewHistoryInstance",
    "id": "841fc5d5-b89e-42cd-9f76-3343689aaabf",
    "reviewHistoryPeriodStartDateTime": "2024-03-24T00:00:00Z",
    "reviewHistoryPeriodEndDateTime": "9999-12-31T00:00:00Z",
    "status": "done",
    "runDateTime": "2024-03-25T17:15:45.1940174Z",
    "fulfilledDateTime": "2024-03-25T17:16:06.5812358Z",
    "downloadUri": "https://ermconsolreportusc.blob.core.windows.net/erm-reports/Last quarter's access reviews for administrative roles - User Administrator-841fc5d5-b89e-42cd-9f76-3343689aaabf.csv?skoid=4ad0868b-7b78-4869-abb7-8f29151d8428&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skt=2024-03-25T17:17:40Z&ske=2024-03-25T17:19:40Z&sks=b&skv=2021-08-06&sv=2021-08-06&st=2024-03-25T17:17:40Z&se=2024-03-26T17:17:40Z&sr=b&sp=r&sig=g%2BlQj2PxFG1lAYDuUt5VWO8tvLPQebA7GLnqz%2FQb%2BbQ%3D"
}

第 7 步：清理资源

在此步骤中，将删除访问评审定义。 由于访问评审计划定义是访问评审的蓝图，因此删除该定义会删除相关的设置、实例和决策。 请求返回 204 No Content 响应。

DELETE https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/02800b79-1a6f-40b7-8381-c0bebc3763bd

总结

你了解了如何评审对管理角色的访问权限，以及如何为合规性报告生成可审核的访问评审历史记录报告。 组织可以使用访问评审 API 持续控制对其资源的特权访问，包括Microsoft Entra角色和 Azure 资源角色。 除了用户和组，还可以查看应用程序和服务主体对管理角色的访问权限。

相关内容