使用访问评审 API 配置访问评审的范围

项目
07/04/2024

Microsoft Entra访问评审 API 允许以编程方式查看用户、服务主体或组必须在租户中Microsoft Entra资源的访问权限。

将Microsoft Entra资源配置为在 accessReviewScheduleDefinition 资源的作用域属性中查看。以下资源公开用于配置访问评审范围的设置：

资源	说明	访问评审方案示例
accessReviewQueryScope	在查看有权访问一个或一组相关资源的主体的完整集或子集时，最适用。	分配给组的用户的成员身份，包括直接成员或直接和可传递成员。来宾用户对一个组的访问权限。来宾用户对所有Microsoft 365 个组的访问权限。分配给特权角色的服务主体。用户和服务主体对权利管理访问包的访问。
accessReviewInactiveUsersQueryScope	继承自 accessReviewQueryScope。仅评审非活动用户时使用。其非活动状态由 inactiveDuration 属性指定。	仅限非活动用户的组成员身份
principalResourceMembershipsScope	继承自 accessReviewScope。最适合用于查看主体对配置主体和资源唯一池的资源的访问权限。	三个特定主体对一个Microsoft 365 组和一个特权Microsoft Entra角色的访问权限。

本文介绍如何通过配置三种派生资源类型来限定访问评审的范围。

使用 accessReviewQueryScope 和 accessReviewInactiveUsersQueryScope 配置范围

若要使用 accessReviewQueryScope 资源类型配置范围，请设置其 query、 queryRoot 和 queryType 属性的值。

accessReviewInactiveUsersQueryScope 需要 accessReviewQueryScope 的所有属性，并包含 inactiveDuration 属性。

示例

注意

本部分中的示例显示了Microsoft 图形 API支持的唯一有效 principalScopes 和 resourceScopes 组合。

示例 1：查看具有对组的直接和可传递分配的所有用户

示例方案： 假设组 A 有三个直接成员 - 用户 AU1 和 AU2 以及组 G1。另一方面，组 G1 有两个成员 - 用户 GU1 和 GU2。因此，用户 GU1 和 GU2 是嵌套组 G1 的可传递成员。评审中包含四个对象：用户 AU1、AU2、GU1 和 GU2。

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/{groupId}/transitiveMembers",
    "queryType": "MicrosoftGraph"
}

示例 2：查看具有对组的直接和可传递分配的所有非活动用户

由于此评审应用于非活动用户，因此请使用 accessReviewInactiveUsersQueryScope 资源，并使用值 #microsoft.graph.accessReviewInactiveUsersQueryScope指定 @odata.type 类型属性。

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
    "inactiveDuration": "P30D",
    "query": "/groups/{groupId}/transitiveMembers",
    "queryType": "MicrosoftGraph"
}

示例 3：查看具有对组的直接和可传递分配的所有来宾用户

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/{groupId}/transitiveMembers/?$filter=(userType eq 'Guest')",    
    "queryType": "MicrosoftGraph"
}

示例 4：查看直接分配到组的所有用户和组

以下示例将评审范围限定为仅定向属于用户或其他组的组成员。在此范围内：

直接用户包含在评审中。
直接组包含在评审中。
评审中不包括组的可传递成员（即嵌套组的成员）。

示例方案： 假设组 A 有三个直接成员 - 用户 AU1 和 AU2 以及组 G1。另一方面，组 G1 有两个成员 - 用户 GU1 和 GU2。因此，用户 GU1 和 GU2 是嵌套组 G1 的可传递成员。此评论中仅面向三个对象：用户 AU1 和 AU2，以及组 G1。

"scope": {
    "query": "/groups/{groupId}/members",
    "queryType": "MicrosoftGraph"
}

示例 5：查看直接分配到任何Microsoft 365 组的所有用户

由于此评审应用于所有Microsoft 365 组，因此请配置 instanceEnumerationScope 以指定要评审的Microsoft 365 个组。此评审中不包括具有动态成员身份或可分配角色的组。

"instanceEnumerationScope": {
    "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified'))",
    "queryType": "MicrosoftGraph"
},
"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "./members/microsoft.graph.user",
    "queryType": "MicrosoftGraph"
}

示例 6：查看直接分配到任何Microsoft 365 组的所有来宾用户

"instanceEnumerationScope": {
    "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified'))",
    "queryType": "MicrosoftGraph"
},
"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
    "queryType": "MicrosoftGraph"
}

示例 7：查看直接分配到任何Microsoft 365 组的所有非活动来宾用户

由于此评审应用于非活动用户，因此请使用 accessReviewInactiveUsersQueryScope 资源，并使用值 #microsoft.graph.accessReviewInactiveUsersQueryScope指定 @odata.type 类型属性。此外，由于此评审应用于所有Microsoft 365 个组，因此请配置 instanceEnumerationScope 以指定要评审的Microsoft 365 个组。此评审中不包括具有动态成员身份或可分配角色的组。

"instanceEnumerationScope": {
    "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified'))",
    "queryType": "MicrosoftGraph"
},
"scope": {
    "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
    "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
    "queryType": "MicrosoftGraph",
    "inactiveDuration": "P30D"
}

示例 8：查看直接分配到团队的所有来宾用户，但具有共享频道的团队除外

由于此评审应用于所有与 Teams 关联的Microsoft 365 个组，因此请将 instanceEnumerationScope 配置为指定要评审的 Teams 关联的Microsoft 365 个组。此评审中不包括具有动态成员身份或可分配角色的组。

此评审不包括使用共享频道的团队中的 B2B 直连用户。若要在具有共享频道的团队中包含 B2B 直连用户，请参阅示例 14：查看分配给团队的所有用户，包括具有共享频道的团队中的 B2B 直连用户。

"instanceEnumerationScope": {
    "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified') and resourceProvisioningOptions/Any(x:x eq 'Team')')",
    "queryType": "MicrosoftGraph"
},
"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
    "queryType": "MicrosoftGraph"
}

示例 9：查看直接分配到团队的所有非活动来宾用户

"instanceEnumerationScope": {
    "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified') and resourceProvisioningOptions/Any(x:x eq 'Team')')",
    "queryType": "MicrosoftGraph"
},
"scope": {
    "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
    "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
    "queryType": "MicrosoftGraph",
    "inactiveDuration": "P30D"
}

示例 10：查看权利管理访问包的所有分配

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/identityGovernance/entitlementManagement/accessPackageAssignments?$filter=(accessPackageId eq '{package id}' and assignmentPolicyId eq '{id}' and catalogId eq 'id')",
    "queryType": "MicrosoftGraph"
}

示例 11：查看分配给特权角色的所有服务主体

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/roleManagement/directory/roleAssignmentScheduleInstances?$expand=principal&$filter=(isof(principal,'microsoft.graph.servicePrincipal') and roleDefinitionId eq '{role ID}')",
    "queryType": "MicrosoftGraph"
}

示例 12：查看分配给Microsoft Entra管理员角色的用户

示例 12.1：查看具有对目录角色的活动或符合条件的分配的所有用户

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/roleManagement/directory/roleDefinitions/{role ID}",
    "queryType": "MicrosoftGraph"
}

示例 12.2：查看具有目录角色合格分配的所有用户

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/roleManagement/directory/roleEligibilityScheduleInstances?$expand=principal&$filter=(isof(principal,'microsoft.graph.user') and roleDefinitionId eq '{role ID}')",
    "queryType": "MicrosoftGraph"
}

示例 12.2：查看具有目录角色的活动分配的所有用户

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/roleManagement/directory/roleAssignmentScheduleInstances?$expand=principal&$filter=(assignmentType eq 'Assigned' and isof(principal,'microsoft.graph.user') and roleDefinitionId eq '{role ID}')",
    "queryType": "MicrosoftGraph"
}

使用 principalResourceMembershipsScope 配置范围

principalResourceMembershipsScope 公开 principalScopes 和 resourceScopes 属性，以支持 accessReviewScheduleDefinition 对象范围的更定制配置选项。这些功能包括查看对多个资源的多个主体或主体组的访问权限。

示例 13：查看分配给团队的所有用户，包括具有共享频道的团队中的 B2B 直连用户

在此示例中，访问评审范围是团队成员或分配到团队中共享频道的所有用户。这些成员包括内部用户、直接用户和可传递用户、B2B 协作用户和 B2B 直连用户。

"scope": {
    "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
    "principalScopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/users",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "resourceScopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/groups/{groupId}/transitiveMembers",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        },
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/teams/{groupId}/channels?$filter=(membershipType eq 'shared')",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ]
}

若要查看共享频道中的 B2B 直接连接用户和团队，必须在 resourceScopes 对象中指定/teams/{groupId}/channels?$filter=(membershipType eq 'shared')查询模式。 所有团队评审（例如示例 8 和 9）不包括共享频道中的 B2B 直连用户和团队。

注意

B2B 直连用户和团队的访问评审仅支持单阶段访问评审，而不支持多阶段访问评审。

示例 14：查看分配给目录角色的所有来宾用户

"scope": {
    "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
    "principalScopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/users?$filter=(userType eq 'Guest')",
            "queryType": "MicrosoftGraph"
        }
    ],
    "resourceScopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/roleManagement/directory/roleDefinitions/{role id}",
            "queryType": "MicrosoftGraph"
        }
    ]
}

示例 15：查看对应用程序进行直接或可传递分配的所有用户

"scope": {
    "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
    "principalScopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/v1.0/users",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        },
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "./members/microsoft.graph.user",
            "queryType": "MicrosoftGraph",
            "queryRoot": "/v1.0/groups"
        }
    ],
    "resourceScopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/v1.0/servicePrincipals/{servicePrincipalId}",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ]
}

将审阅者分配到访问评审定义
试用教程，了解如何使用访问评审 API 来评审对Microsoft Entra资源的访问权限

通过

使用访问评审 API 配置访问评审的范围

使用 accessReviewQueryScope 和 accessReviewInactiveUsersQueryScope 配置范围

示例

示例 1：查看具有对组的直接和可传递分配的所有用户

示例 2：查看具有对组的直接和可传递分配的所有非活动用户

示例 3：查看具有对组的直接和可传递分配的所有来宾用户

示例 4：查看直接分配到组的所有用户和组

示例 5：查看直接分配到任何Microsoft 365 组的所有用户

示例 6：查看直接分配到任何Microsoft 365 组的所有来宾用户

示例 7：查看直接分配到任何Microsoft 365 组的所有非活动来宾用户

示例 8：查看直接分配到团队的所有来宾用户，但具有共享频道的团队除外

示例 9：查看直接分配到团队的所有非活动来宾用户

示例 10：查看权利管理访问包的所有分配

示例 11：查看分配给特权角色的所有服务主体

示例 12：查看分配给Microsoft Entra管理员角色的用户

示例 12.1：查看具有对目录角色的活动或符合条件的分配的所有用户

示例 12.2：查看具有目录角色合格分配的所有用户

示例 12.2：查看具有目录角色的活动分配的所有用户

使用 principalResourceMembershipsScope 配置范围

示例 13：查看分配给团队的所有用户，包括具有共享频道的团队中的 B2B 直连用户

示例 14：查看分配给目录角色的所有来宾用户

示例 15：查看对应用程序进行直接或可传递分配的所有用户

反馈

其他资源

通过

使用访问评审 API 配置访问评审的范围

使用 accessReviewQueryScope 和 accessReviewInactiveUsersQueryScope 配置范围

示例

示例 1：查看具有对组的直接和可传递分配的所有用户

示例 2：查看具有对组的直接和可传递分配的所有非活动用户

示例 3：查看具有对组的直接和可传递分配的所有来宾用户

示例 4：查看直接分配到组的所有用户和组

示例 5：查看直接分配到任何Microsoft 365 组的所有用户

示例 6：查看直接分配到任何Microsoft 365 组的所有来宾用户

示例 7：查看直接分配到任何Microsoft 365 组的所有非活动来宾用户

示例 8：查看直接分配到团队的所有来宾用户，但具有共享频道的团队除外

示例 9：查看直接分配到团队的所有非活动来宾用户

示例 10：查看权利管理访问包的所有分配

示例 11：查看分配给特权角色的所有服务主体

示例 12：查看分配给Microsoft Entra管理员角色的用户

示例 12.1：查看具有对目录角色的活动或符合条件的分配的所有用户

示例 12.2：查看具有目录角色合格分配的所有用户

示例 12.2：查看具有目录角色的活动分配的所有用户

使用 principalResourceMembershipsScope 配置范围

示例 13：查看分配给团队的所有用户，包括具有共享频道的团队中的 B2B 直连用户

示例 14：查看分配给目录角色的所有来宾用户

示例 15：查看对应用程序进行直接或可传递分配的所有用户

相关内容

反馈

其他资源