Report Global Admins

graph-globaladmins-get.ps1 Documentation

Purpose

graph-globaladmins-get.ps1 reports members of the Microsoft Entra ID Global Administrator role by querying Microsoft Graph.

The script:

• Authenticates to Microsoft Graph.
• Resolves the Global Administrator role by role template ID.
• Retrieves all members of that role (with paging support).
• Normalizes returned data into a consistent object shape.
• Displays results in a formatted table.
• Optionally exports results to CSV.

Script Location

• Script: graph-globaladmins-get.ps1

Parameters

-csv

Type: switch

Default: False

Behavior:

• When supplied, exports the final summary to a CSV file.
• When omitted, the script only displays results in the console.

Example:

. .\graph-globaladmins-get.ps1 -csv

-OutputFile

Type: string

Default: ..\graph-globaladmins.csv

Behavior:

• Specifies the CSV destination path when -csv is used.
• Accepts relative or absolute paths.

Example:

. .\graph-globaladmins-get.ps1 -csv -OutputFile .\reports\global-admins.csv

Required Permissions and Scope

The script connects with:

• RoleManagement.Read.Directory
• User.Read.All

You must sign in with an account that can grant or use these delegated permissions in your tenant.

Prerequisites

1. PowerShell 7+ (recommended) or Windows PowerShell 5.1.
2. Microsoft Graph PowerShell SDK installed (minimum requirement is support for Connect-MgGraph and Invoke-MgGraphRequest).
3. Network access to graph.microsoft.com.

Install Graph SDK (if needed):

Install-Module Microsoft.Graph -Scope CurrentUser

How to Execute

Run from PowerShell:

. 'C:\downloads\source\office365\graph-globaladmins-get.ps1'

With CSV export:

. 'C:\downloads\source\office365\graph-globaladmins-get.ps1' -csv

With custom CSV path:

. 'C:\downloads\source\office365\graph-globaladmins-get.ps1' -csv -OutputFile 'C:\temp\global-admins.csv'

Operational Flow (Step by Step)

1. Applies strict scripting behavior:

• Set-StrictMode -Version Latest
• $ErrorActionPreference = "Stop"

2. Connects to Graph:

• Calls Connect-MgGraph with required scopes.

3. Resolves role using Global Administrator role template ID:

• Role template ID: 62e90394-69f5-4237-9190-012177145e10
• Query:
  • GET /v1.0/directoryRoles?$filter=roleTemplateId eq '62e90394-69f5-4237-9190-012177145e10'

4. Retrieves role members:

• Query:
  • GET /v1.0/directoryRoles/{roleId}/members?$select=id,displayName,userPrincipalName
• Uses paging with @odata.nextLink until all pages are collected.

5. Normalizes member properties:

• Supports multiple response shapes:
  • Direct object properties.
  • Dictionary/hashtable payloads.
  • AdditionalProperties dictionaries.

6. Enriches user records when needed:

• If a member is type #microsoft.graph.user and key fields are missing, performs:
  • GET /v1.0/users/{id}?$select=id,displayName,userPrincipalName

7. Builds output objects:

• Id
• DisplayName
• UserPrincipalName
• PrincipalType

8. Sorts by DisplayName and writes table output.

9. Optionally exports UTF-8 CSV when -csv is used.

10. Always attempts to disconnect Graph in finally.

Output Schema

Each row includes:

• DisplayName: principal display name.
• UserPrincipalName: user sign-in name (usually null for non-user principals).
• PrincipalType: User, Graph type (for non-users), or Unknown.
• Id: object ID.

Error Handling Behavior

• Any terminating error is caught and written with Write-Error.
• Script exits with code 1 on failure.
• If the Global Administrator role is not found, the script throws:
  • Unable to locate the Global Administrator directory role in this tenant.
• Disconnect errors are intentionally ignored in cleanup to avoid masking the primary failure.

Troubleshooting

Blank or Unknown values in output

Cause:

• Graph responses can vary in shape.

Current handling:

• The script reads fields from direct properties, dictionaries, and AdditionalProperties.

If issue persists:

• Confirm permissions/scopes were consented.
• Retry in a fresh PowerShell session.

Graph module assembly conflicts

Typical symptom:

• Assembly load conflicts referencing Microsoft.Graph.Authentication in long-lived sessions.

Mitigation in this script:

• Uses Invoke-MgGraphRequest for data retrieval paths to reduce dependency on typed cmdlets.

No results returned

Potential causes:

• No active Global Administrator role instance returned by Graph in current context.
• Tenant or account context mismatch.
• Insufficient permissions.

Checks:

• Run Get-MgContext after sign-in and verify account/tenant.
• Verify consent for RoleManagement.Read.Directory and User.Read.All.

Notes

• CSV export path is resolved by PowerShell relative to the current working directory unless an absolute path is provided.
• Output can include users and non-user principals assigned to the role.
• This script is read-only and does not modify tenant configuration.