Use the Graph API to Work with Azure AD Access Reviews

Check that Guests are Really Wanted

Microsoft is previewing the ability to create an Azure AD Access Review to cover guest access to every group (and team) in a tenant. The idea is that group owners are asked to approve or deny the access granted to guest users to their groups. With the caveat that all previews come with rough edges, the review works well enough for organizations to assess if the feature is valuable for them.

A challenge facing every GUI is how to achieve the balance of usability for both large and small organizations. Getting an oversight of an access review for guests in 27 teams in a small tenant makes certain demands on the GUI to make the data comprehensible and enable administrators to figure out where the overall review is at. Doing the same for a large tenant where reviews might be ongoing for thousands of teams poses a different test. However, the Identity Governance section in the Azure AD admin center has just one interface to manage access reviews (Figure 1).

Details of an Azure AD Access Review for all groups in a tenant
Figure 1: Details of an Azure AD Access Review for all groups in a tenant

When an access review is viewed through the Azure AD admin center, you see10 groups at a time (it’s a preview), but even if the admin center showed a hundred groups, paging through large numbers of groups to find what’s happening in an individual review can be painful.

Using the Graph API for Access Reviews

Which brings us to the Graph API for Azure AD Access Reviews, the basis for DIY management of access reviews. To test how the API worked, I wrote a PowerShell script to find the review for all groups and create a report of the review decisions made to date.

The steps taken in the script are:

  • As usual when using PowerShell to interact with the Graph, create a registered app in Azure AD. Note the app identifier, tenant identifier, and app secret. The app must be assigned the AccessReview.ReadWrite.All permission. I also assigned the Group.ReadApp permission to allow the app to retrieve details of Azure AD groups.
  • Use the app identifier, tenant identifier, and app secret to get an access token.
  • Read the set of access reviews known in the tenant and find the one used for guest access to all groups. This will result in a review instance.
  • Find the groups within the scope of the review. These are called instances. In other words, an instance of the overall review applied to a specific group.
  • For each instance, retrieve the decisions made for the guests in the group. It’s here that I retrieved the group display name to make it easier to understand the output.
  • Store details of each decision (verdict). The verdict will be Deny, Approve, or NotReviewed. A verdict comes with the name of the person who decided and when they decided. If the policy dictates, a justification is also present.
  • Capture the details of the verdict out in a PowerShell list.
  • After processing all instances, write the verdict data out from the list to a CSV file and give an overall report on screen.

Figure 2 shows the output at the end of the script.

Figure 2: Overall statistics for an Azure AD Access Review for guest users

The script generates a CSV file to allow the decision data to be analyzed in whatever way you wish. Piping the data to the Out-GridView cmdlet is a good way to get a quick overview of the current state of reviews across all groups (Figure 3).

Figure 3: Reviewing the decision status for access reviews

Download the Script

The sample script can be downloaded from GitHub. It doesn’t exercise all the functionality available in the API. For example, to accelerate the process of completing the review, you could look for outstanding reviews of guests in groups and call the acceptRecommendations API to accept the automatic recommendations as made by Azure AD. However, as I explain here, accepting automatic recommendations is not always the wisest thing to do, especially when Azure AD makes decisions based on limited data.


You’ll find full details about Azure B2B collaboration (the basis of guest access to Teams and Groups) plus a ton of insight about how guest access works in the Office 365 for IT Pros eBook. And because we keep the book updated, new developments like the Azure AD Access Review for all guests in a tenant are mentioned there too.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.