Configure the scope of your access review using the Microsoft Graph API

Article
11/29/2023

The Microsoft Entra access reviews API allows you to programmatically review the access that users, service principals, or groups have to your Microsoft Entra resources. The API can help you to automate proactive review and keep control over access to resources in your organization.

The resources to review are configured in the scope property of the accessReviewScheduleDefinition resource. This property is of the type accessReviewScope, an abstract type that the following API resources that can be used to configure the access review scope inherit from.

Resource	Description	Example scenarios
accessReviewQueryScope	Inherits from accessReviewScope. Best applicable when reviewing the full set or subset of principals who have access to a resource or group of related resources.	Membership of users assigned to a group, either direct members or direct and transitive members. Guest user access to one group. Guest user access to all Microsoft 365 groups in a tenant. Service principals assigned to privileged roles. User and service principal access to Entitlement Management access packages.
accessReviewInactiveUsersQueryScope	Inherits from accessReviewQueryScope. Used when only inactive users are reviewed. Their inactive status is specified by the inactiveDuration property.	Group membership of only inactive users.
principalResourceMembershipsScope	Inherits from accessReviewScope. Best applicable to review principals' access to resources where you configure unique pools of principals and resources.	Reviewing access of three specific principals across one Microsoft 365 group and one privileged Microsoft Entra role.

In this article, you'll learn how to scope your access review using these three derived resource types.

Use accessReviewQueryScope and accessReviewInactiveUsersQueryScope to configure scope

To configure the scope by using the accessReviewQueryScope type, set the values of its query, queryRoot, and queryType properties. For descriptions of these properties, see accessReviewQueryScope resource type.

accessReviewInactiveUsersQueryScope requires all the properties of accessReviewQueryScope and includes an inactiveDuration property.

Example 1: Review all users assigned to a group

The following example scopes the review to both direct and transitive members of the group who are users. The transitive members are members of the nested groups.

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

Example scenario: Suppose group A has three direct members - users AU1 and AU2 and group G1. Group G1 on the other hand has two members - users GU1 and GU2. Users GU1 and GU2 are therefore transitive members of the nested group G1. Four objects will be included in the review: users AU1, AU2, GU1, and GU2.

To review only inactive users assigned to the group:

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

This example also scopes the review to both direct and transitive members of the group who are inactive users.

Example 2: Review all guest users assigned to a group

The following example scopes the review to both direct and transitive members of the group who are guest users. The transitive members are members of the nested groups.

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

Example 3: Review all users and groups assigned to a group

The following example scopes the review to only direct members of the group who are either users or other groups. In this scope:

The direct users are included in the review.
The direct groups are included in the review.
The transitive members of the groups, that is, members of nested groups, aren't included in the review.

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

Example scenario: Suppose group A has three direct members - users AU1 and AU2 and group G1. Group G1 on the other hand has two members - users GU1 and GU2. Users GU1 and GU2 are therefore transitive members of the nested group G1. Only three objects are targeted in the above review, users AU1 and AU2, and group G1.

Example 4: Review all users assigned to all Microsoft 365 groups

The following example creates a review of all Microsoft 365 groups in the tenant. The review is scoped to only direct members of the group.

"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"
}

Additionally, because this review is applied on all Microsoft 365 groups, configure the instanceEnumerationScope to specify the Microsoft 365 groups to review. Dynamic groups and role-assignable groups aren't included in this review.

Example 5: Review all guest users assigned to all Microsoft 365 groups

The following example scopes the review to direct members of all Microsoft 365 groups who are guest users.

"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"
}

Review all inactive guest users assigned to all Microsoft 365 groups

The following example scopes the review to direct members of all Microsoft 365 who are inactive guest users.

"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"
}

Additionally, because this review is applied on inactive users, use the accessReviewInactiveUsersQueryScope resource and specify the @odata.type type property with the value #microsoft.graph.accessReviewInactiveUsersQueryScope. Dynamic groups and role-assignable groups aren't included in this review.

Example 6: Review all guest users assigned to all teams

The following example scopes the review to direct members of all teams who are guest users.

"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"
}

Additionally, because this review is applied on all Teams-enabled Microsoft 365 groups, configure the instanceEnumerationScope to specify the Teams-enabled Microsoft 365 groups to review. Dynamic groups and role-assignable groups aren't included in this review.

This review won't include B2B direct connect users in teams with shared channels. To include B2B direct connect users in teams with shared channels, see Example 11: Review all users assigned to a team, including B2B direct connect users in a team with shared channels.

Review all inactive guest users assigned to all Teams

The following example scopes the review to direct members of all teams who are inactive guest users.

"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"
}

Additionally, because this review is applied on all teams, configure the instanceEnumerationScope property to specify all teams. Dynamic groups and role-assignable groups aren't included in this review.

Example 7: Review all assignment to Entitlement Management access packages

"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"
}

Example 8: Review all service principals assigned to a privileged role

"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"
}

Example 9: Review all users assigned to a privileged role

Review all users assigned to a privileged role (all active and eligible assignments included)

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

Review all users with eligible assignment to a privileged role

"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"
}

Review all users with active assignment to a privileged role

"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"
}

Use principalResourceMembershipsScope to configure scope

The principalResourceMembershipsScope exposes the principalScopes and resourceScopes properties to support more tailored configuration options for the scope of the accessReviewScheduleDefinition object. The capabilities include reviewing access for multiple principals or groups of principals to multiple resources.

Example 10: Review all inactive guest users assigned to all groups

The following example scopes the review to direct members of all groups who are inactive guest users. The guest users are considered inactive users when the period of their inactivity is 30 days from the start date of the access review instance.

"scope": {
    "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
    "principalScopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
            "query": "/users?$filter=(userType eq 'Guest')",
            "queryType": "MicrosoftGraph",
            "inactiveDuration": "P30D"
        }
    ],
    "resourceScopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/groups",
            "queryType": "MicrosoftGraph"
        }
    ]
}

Example 11: Review all users assigned to a team, including B2B direct connect users in a team with shared channels

In this example, the access review scope is all users who are members of a team, or assigned to a shared channel within the team. These members include internal users, direct and transitive users, B2B collaboration users, and B2B direct connect users.

"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
        }
    ]
}

To review B2B direct connect users and teams within shared channels, you must specify the /teams/{groupId}/channels?$filter=(membershipType eq 'shared') query pattern in the resourceScopes object. An all teams review, such as Example 6, won't include B2B direct connect users and teams within shared channels.

Note

Access review of B2B direct connect users and teams is only supported in single-stage access reviews and not in multi-stage access reviews.

Example 12: Review all guest users assigned to a directory role

"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"
        }
    ]
}

Example 13: Review all users assigned to an application

In this example, the access review scope is all users who are assigned to any of the roles of the application. The principals whose access is to be reviewed are specified by elements of principalScope in the principalResourceMembershipsScope. This example has two elements, for the users directly assigned to the application roles, and the users who are members of groups assigned to the application roles. The application is specified by the ID of the application's service principal.

"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
        }
    ]
}

Next steps

Assign reviewers to your access review definition
Try out tutorials to learn how to use the access reviews API to review access to Microsoft Entra resources
Create an access review