Assign permission at the tenant root management group level

Use this script to assign the Reader role to your service principal at the tenant root management group level. This grants read access to all subscriptions and resources in the tenant, and is required after you have created your app registration in Microsoft Entra ID.

Before running the script

1. Have the client ID of the service principal (app registration) you created in the previous step.

2. Confirm you have Global Admin and Tenant Owner permissions in your Azure tenant.

3. Sign in to the Azure CLI and obtain an Azure Resource Manager-scoped token using the following command.

az login --use-device-code --tenant [Tenant ID]

3. Sign in again to obtain a Microsoft Graph API-scoped token using the following command.

az login --use-device-code  --scope https://graph.microsoft.com//.default --tenant [Tenant ID]

5. Save the full script from the Script section below to a location you can run it from.

6. Run the script using the following command.

.\Setup-TenantRootManagementGroup-Permission.ps1 -ClientId <app-registration-client-id>

Script

The script looks up the service principal by client ID, builds the root management group scope from your tenant ID, assigns the Reader role, then verifies the assignment.

# Assigns the Reader role to a Service Principal at the Tenant Root Management Group scope.
# This grants read access to all subscriptions and resources in the tenant.
#
# Prerequisites:
#   - PIM into Global Admin or Tenant Owner (required to assign roles at root scope)
#   az login --use-device-code --tenant [Tenant ID]
#   az login --use-device-code --scope https://graph.microsoft.com//.default --tenant [Tenant ID]
#
# Usage:
#   .\Setup-TenantRootManagementGroup-Permission.ps1 -ClientId <app-registration-client-id>

param(
    [Parameter(Mandatory = $true)]
    [string]$ClientId
)

# Look up the Service Principal Object ID
Write-Host "Looking up Service Principal for Client ID: $ClientId ..."
$SpObjectId = az ad sp show --id $ClientId --query id -o tsv

if (-not $SpObjectId) {
    Write-Error "Could not find a Service Principal for Client ID '$ClientId'. Ensure the App Registration exists and you are logged in to the correct tenant."
    exit 1
}

Write-Host "Found Service Principal Object ID: $SpObjectId"

# Get the Tenant ID to build the root management group scope
$TenantId = az account show --query tenantId -o tsv
$Scope = "/providers/Microsoft.Management/managementGroups/$TenantId"

Write-Host "Assigning 'Reader' role at Tenant Root Management Group scope: $Scope ..."

az role assignment create `
    --assignee-object-id "$SpObjectId" `
    --assignee-principal-type ServicePrincipal `
    --role "Reader" `
    --scope "$Scope"

if ($LASTEXITCODE -ne 0) {
    Write-Warning "Failed to assign Reader role. Ensure you have elevated permissions (Global Admin / root management group Owner)."
    exit 1
}

Write-Host ""
Write-Host "Successfully assigned 'Reader' role at Tenant Root Management Group."

Write-Host ""
Write-Host "Verifying assignment ..."
az role assignment list --assignee "$SpObjectId" --scope "$Scope" --output table