Reporting Office 365 Admin Role Group Members

Office 365 allows organizations to delegate administrative privileges in a granular fashion. There is an over-arching “Global Administrator” role, as well as a series of lower privilege roles for specific administrative tasks. A partial list of the admin roles is visible in the user management area of the Office 365 admin portal.

That's not the complete list though. There's several other administrative and non-administrative roles in Office 365. While looking for a complete list, I happen to stumble across some differences between how the old MSOnline PowerShell module reports the list of roles, compared to the new AzureAD PowerShell module. Get-MsolRole returns 30 groups, while Get-AzureADDirectoryRoleTemplate returns 34 groups. I've highlighted the differences in the table below.

It's good practice to review the membership of admin groups on a regular basis, to make sure that only those users who require admin privileges in your tenant actually have them, and nobody else has sneaked in there and been forgotten. It's even better practice to manage privileged access using Azure Privileged Identity Management.

If you're familiar with the Exchange RBAC permissions model you will notice that none of the Exchange RBAC roles are included in that list above. If you want to report on those you can use my RBAC role group membership report script.

You should also be aware that if you're using Get-AzureADDirectoryRole as the equivalent cmdlet to Get-MsolRole, the Get-AzureADDirectoryRole cmdlet only returns roles that have been enabled. It seems that a role becomes enabled when you first add a user to the role, or when an admin enables the role using the Enable-AzureADDirectoryRoleTemplate cmdlet. Since the point of this exercise is to report on membership of Office 365 roles, I'm going to use Get-AzureADDirectoryRole as the basis of a PowerShell script, which will effectively ignore roles that have not been enabled yet.

If you just want to download the reporting script, go to the end of this blog post.

To begin with, let's look at the output of Get-AzureADDirectoryRole for one of my tenants.

To see the membership of a role, such as Company Administrator (which is the same as Global Administrator when you're editing a user's roles in the Office 365 admin portal), we need to run Get-AzureADDirectoryRoleMember and supply the ObjectId.

The standard output looks different depending on the role that you're querying. For example, Directory Readers looks like this.

The properties that are returned are also different, depending on the type of object that is a member of the group. Users have properties such as JobTitle, Mail, and PasswordPolicies. Service principals (such as the Office 365 Secure Score service) have properties such as AppId, Homepage, and Oauth2Permissions. Both types of objects have common properties such as ObjectType and DisplayName though, so reporting on both types of objects together is not too difficult.

For this script I'm going to report on:

• DisplayName
• ObjectType
• AccountEnabled
• UserPrincipalName (for users)
• Homepage (for service principals)
• PasswordPolicies (for users)

Retrieving that information for the members of an admin group/role is not difficult, as you can see above. To generate a full report it's really just a matter of looping through the roles, collect the desired info, and present it in a readable format for the report. I've chosen to used CSV as the file format. You can then load the CSV into Excel to filter and sort the data as required.

This script, Get-O365AdminGroupsReport.ps1, relies on the AzureAD PowerShell module. If you do not have the module installed the script will throw an error. You can install the AzureAD module from the PowerShell Gallery.

To use the script, simply run the following command and you'll be prompted to authenticate to Azure AD.

To see script progress, use the -Verbose switch.

The script will output a CSV file named Office365AdminGroupMembers-ddMMyyyy.csv, where “ddMMyyyy” is the current date (e.g. 17042017). If the file already exists, a unique string of characters is added to the filename.

There are two optional parameters that you can use to change the output behavior:

• ReportFile – You can provide a custom output file name. The file name you specify will be modified with the current date, for example MyReportFileName.csv will become MyReportFileName-ddMMyyyy.csv. If a file of the same name exists, a unique character string will also be appended to the file name.
• Overwrite – Overwrites an existing report file of the same name, instead of appending a unique character string.

You can download Get-O365AdminGroupsReport.ps1 from the TechNet Script Gallery.

Paul Cunningham

Paul is a Microsoft MVP for Office Servers and Services. He works as a consultant, writer, and trainer specializing in Office 365 and Exchange Server. Paul is a co-author of Office 365 for IT Pros and several other books, and is also a Pluralsight author.