Configure the scope of access reviews using access reviews APIs

  • Article

The Microsoft Entra access reviews APIs allow you to programmatically review access that users, service principals, or groups have to Microsoft Entra resources in your tenant.

You configure the Microsoft Entra resources to review in the scope property of the accessReviewScheduleDefinition resource. The following resources expose the settings to configure the scope of the access review:

Resource Description Example access review scenarios
accessReviewQueryScope 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.
  • 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 for inactive users only
    principalResourceMembershipsScope Inherits from accessReviewScope. Best applicable to review principals' access to resources where you configure unique pools of principals and resources.
    • Access for three specific principals to one Microsoft 365 group and one privileged Microsoft Entra role.

      In this article, you learn how to scope your access review by configuring the three derived resource types.

      Configure scope by using accessReviewQueryScope and accessReviewInactiveUsersQueryScope

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

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

      Example 1: Review all users with direct and transitive assignment to a group

      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 are included in the review: users AU1, AU2, GU1, and GU2.

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

      Example 2: Review all inactive users with direct and transitive assignment to a group

      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.

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

      Example 3: Review all guest users with direct and transitive assignment to a group

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

      Example 4: Review all users and groups with direct assignment 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.

      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 this review, users AU1 and AU2, and group G1.

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

      Example 5: Review all users with direct assignment to any Microsoft 365 group

      Because this review is applied on all Microsoft 365 groups, configure the instanceEnumerationScope to specify the Microsoft 365 groups to review. Groups that are of dynamic membership or role-assignable aren't included in this review.

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

      Example 6: Review all guest users with direct assignment to any Microsoft 365 group

      Because this review is applied on all Microsoft 365 groups, configure the instanceEnumerationScope to specify the Microsoft 365 groups to review. Groups that are of dynamic membership or role-assignable aren't included in this review.

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

      Example 7: Review all inactive guest users with direct assignment to any Microsoft 365 group

      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. Also, because this review is applied on all Microsoft 365 groups, configure the instanceEnumerationScope to specify the Microsoft 365 groups to review. Groups that are of dynamic membership or role-assignable aren't included in this review.

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

      Example 8: Review all guest users with direct assignment to teams, except teams with shared channels

      Because this review is applied on all Teams-associated Microsoft 365 groups, configure the instanceEnumerationScope to specify the Teams-associated Microsoft 365 groups to review. Groups that are of dynamic membership or role-assignable aren't included in this review.

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

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

      Example 9: Review all inactive guest users with direct assignment to teams

      Because this review is applied on all Teams-associated Microsoft 365 groups, configure the instanceEnumerationScope to specify the Teams-associated Microsoft 365 groups to review. Groups that are of dynamic membership or role-assignable aren't included in this review.

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

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

      Example 10: 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 11: 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 12: Review users assigned to a Microsoft Entra admin role

      Example 12.1: Review all users with active or eligible assignments to a directory role

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

      Example 12.2: Review all users with eligible assignments to a directory 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"
}

      Example 12.2: Review all users with active assignments to a directory 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 13: Review all inactive guest users with direct assignment to groups

      "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 14: 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 examples 8 and 9, doesn't include B2B direct connect users and teams within shared channels.

      Note

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

      Example 15: 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 16: Review all users with direct or transitive assignment to an application

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

      Related content