To ensure the security of your Microsoft 365 client, we recommend implementing an appropriate governance and security strategy. An effective measure is to determine the current administrators and their permissions. In this article, we want to identify administrators with permanent roles and administrators who can use roles with Privileged Identity Management (PIM). PIM provides just-in-time privileged access to Azure AD and Azure resources. See how to find all Administrators, including PIM, here.
We have many methods to accomplish that task. Here, we use the Microsoft Graph API, the Graph Explorer, Postman, Fiddler and PowerShell. First, we want to get the permanent Administrators of a tenant with Graph Explorer. We open aka.ms/ge, authenticate and we are in business.
Standard directory roles and users holding a role
To get a list of all directory roles, we can use GET /directoryRoles as described at List directoryRoles. This is the query we can use in Graph Explorer (as a user holding the permissions to access that data):
https://graph.microsoft.com/v1.0/directoryRoles
Now we can add one Role Id to that query to get the members. See List members and the following sample to get the relevant fields only. Here, we use the id of the role "Company Administrator" with Id "afe...". The Role Id´s are different in every tenant, so you have to query your desired role and use the corresponding role id.
https://graph.microsoft.com/v1.0/directoryRoles/<role id>/members?$select=id,userPrincipalName
The response shows the users of that role.
Mission accomplished. We can get the admins holding a specific role in a Microsoft 365 tenant as described here. We could also add or modify the admins with Graph. Let´s continue with PIM.
Privileged Identity Management with Graph (Beta)
The PIM operations are currently all in the Beta version of Microsoft Graph (and of today not in v1.0). APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported.
Note: There´s an old Beta method. When we use a GET https://graph.microsoft.com/beta/privilegedRoles (only available for the Beta endpoint, not for v1.0) as described at List assignments (Beta), we get an error, as here:
{ "error":
{ "code": "TenantEnabledInAadRoleMigration",
"message": "The current endpoints of AAD roles have been disabled for the tenant for migration purpose.
Please use the new Azure AD RBAC roles. Please refer to https://aka.ms/PIMFeatureUpdateDoc for new PIM features;
https://aka.ms/PIMAPIUpdateDoc for API and PowerShell changes because of migration." ,
"innerError": { ... } } }This method seems to be outdated. Again, it´s a Beta version.
So, https://aka.ms/PIMFeatureUpdateDoc leads to a document Azure AD PIM Code Base Refresh.pdf that describes that Microsoft merged the Azure AD roles and Azure Resource roles into a new method recently. https://aka.ms/PIMAPIUpdateDoc informs about the new roles and about the API: "When customers have the updated version rolled out to their Azure AD organization, the existing graph API will stop working. You must transition to use the Graph API for Azure resource roles. To manage Azure AD roles using that API, swap /azureResources with /aadroles in the signature and use the Directory ID for the resourceId."
Privileged Identity Management with the new Graph API (Beta)
The updated Beta API documentation is at Privileged Identity Management - Azure resources. We want to get the users as described at List governanceRoleAssignments. The method returns a collection of governanceRoleAssignments on a resource.
In real world, we want to use the Graph API in a custom app. To test that without Graph Explorer, we create a test app "tpApp1" in Azure AD with the Application permission PrivilegedAccess.Read.AzureAD (and some other permissions, for other tests, but they shouldn't be relevant here) and grant the access as here.
Postman helps for testing such calls against any HTTP endpoint. In Postman, we use that application to get a token with https://login.microsoftonline.com/{{TenantID}}/oauth2/v2.0/token and the usual parameters ClientID, ClientSecret and TenantID (the Postman environments help). Once we have a valid token for that app, we can run the query to get the role assignments:
https://graph.microsoft.com/beta/privilegedAccess/aadRoles/resources/{{TenantID}}/roleAssignments
The request works well with the app permissions and we get roles and the assigned users and Service Principals (with their IDs).
So, we can get the PIM role assignments with the Graph API as application. This means, we can integrate that into our custom applications. Sure, IDs need to be replaced with names to generate useful output, but that's another task for later.
Another method is to use PowerShell.
Privileged Identity Management with PowerShell
Kindly, the article PowerShell for Azure AD roles in Privileged Identity Management informs how to access PIM with PowerShell. To use that, we need to install the PowerShell AzureADPreview module. We can add the -Force parameter to update to the latest version if we have that module installed previously.
Install-module AzureADPreview -Force
Now let´s use the module in a script and connect to Azure AD.
Import-Module AzureADPreview
Connect-AzureAD
Once we are connected, we get the roles for a user and lookup the role. Basically, we can start step by step as here: Get the Tenant Id, get all administrative roles with users, lookup the user and the role definition and output the data as needed. The following script shows the basic idea how to get the data from the Azure AD tenant.
# Get the tenant id
$tenantid = Get-AzureADTenantDetail | select-object -expandproperty ObjectId
# Get all roles
$roles = Get-AzureADMSPrivilegedRoleAssignment -ProviderId "aadRoles" -ResourceId $tenantid
# To do a lookup for the friendly role name, let´s get all roles in a collection
$roledefinition = Get-AzureADMSPrivilegedRoleDefinition -ProviderId "aadRoles" -ResourceId $tenantid
# Loop through the roles..
foreach ($onerole in $roles) {
# Lookup the user
$user = Get-AzureADUser -ObjectId $onerole.SubjectId
# Lookup the roledefinition and output the role depending on your needs...
Write-Host "$onerole.roledefinitionid, $onerole.AssignmentState, $user"
}
# Export the data to a CSV file or similar.
Note: When we use the Fiddler tracing tool, we see that the command Get-AzureADMSPrivilegedRoleAssignment is using the same Graph Beta endpoint to get the roles using a refresh token for the request. The data is returned and deserialized from a JSON response to a .NET object that can be used in PowerShell easily. Here´s the Fiddler trace showing (parts of) the request with the Beta endpoint method.
GET /beta/privilegedAccess/aadRoles/resources/<TenantId>/roleAssignments HTTP/1.1
Create a report out of the data
If the data is written to a list, the result output could look similar as here. Adapt the script as needed.
We see there are a couple of users in that tenant holding various Admin roles. There´s a permanent Global Administrator service.app@contoso.onmicrosoft.com. Also, there´s a user christiec@contoso.org, who is eligible to activate the Global Administrator role (see the yellow selection). This role assignment starts on February, 25th with no end date. That user currently has activated the role with PIM today with a timeframe of 2 hours (the green selection). And we see more roles are assigned to users or Service Principals.
Summary
Governance and security is important. Starting to secure your Microsoft 365 (Azure AD) tenant by using Secure Score and custom tools or scripts. Our company atwork is specialized in supporting customers to accomplish that goal. Getting a list of all (possible) Administrators is one step to secure your organization´s environment. We call this task "GetAdminRoles". As shown here as a concept, unwanted administrators can be identified by creating a report including Privileged Identity Management roles. It´s a Must-have for every organization.
Thanks to my colleagues Christoph Wilfing and Martina Grom for developing this solution. Happy developing and scripting!