Edit

Assign reviewers to access reviews using access reviews APIs

  • Article

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 primary reviewers are configured in the reviewers property of the access reviews accessReviewScheduleDefinition resource. In addition, you can specify fallback reviewers by using the fallbackReviewers property. These properties aren't required when you create a self-review (where users review their own access).

To configure the reviewers and fallback reviewers, set the values of query, queryRoot, and queryType properties of accessReviewReviewerScope resource type.

Note

Review of groups whose membership is governed through PIM for groups only assigns active owners as the reviewers. Eligible owners are not included. At least one fallback reviewer is required to review these groups. If there are no active owners when the review begins, the fallback reviewers are assigned to the review.

Example 1: A self-review

To configure a self-review, don't specify the reviewers property, or supply an empty object to the property.

If the corresponding access review scope targets B2B direct connect users and teams with shared channels, the team owner is assigned to review access for the B2B direct connect users.

"reviewers": []

Example 2: A specific user as the reviewer

"reviewers": [
    {
        "query": "/users/{userId}",
        "queryType": "MicrosoftGraph"
    }
]

Example 3: Members of a group as reviewers

"reviewers": [
    {
        "query": "/groups/{groupId}/transitiveMembers",
        "queryType": "MicrosoftGraph"
    }
]

Example 4: Group owners as reviewers

When the access review is scoped to a group, for example, examples 1-4 for configuring an access review scope.

"reviewers": [
    {
        "query": "/groups/{groupId}/owners",
        "queryType": "MicrosoftGraph"
    }
]

When the access review is scoped to a group and to assign only the group owners from a specific country as reviewers:

"reviewers": [
    {
        "query": "/groups/{groupId}/owners?$filter=microsoft.graph.user/userType eq 'Member' and microsoft.graph.user/country eq 'USA'",
        "type": "MicrosoftGraph"
    }
]

When the access review is scoped to all groups, for example, examples 5-9 for configuring an access review scope.

"reviewers": [
    {
        "query": "./owners",
        "queryType": "MicrosoftGraph"
    }
]

Example 5: People managers as reviewers

Because ./manager is a relative query, specify the queryRoot property with the value decisions.

If the corresponding access review scope targets B2B direct connect users and teams with shared channels, the team owner is assigned to review access for the B2B direct connect users.

"reviewers": [
    {
        "query": "./manager",
        "queryType": "MicrosoftGraph",
        "queryRoot": "decisions"
    }
]

Example 6: Application owners as reviewers

"reviewers": [
    {
        "query": "/servicePrincipals/{servicePrincipalId}/owners",
        "queryType": "MicrosoftGraph"
    }
]

Related content