console.md

Configure and run Azure Governance Visualizer from the console

When trying out Azure Governance Visualizer for the first time or simply as a one-time evaluation of an Azure tenant, the quickest way to get results is to run it directly from the console. These instructions will get you up and running from a terminal.

Prerequisites

The following must be installed on the workstation that will be used to run the scripts:

• Git
• PowerShell 7 (minimum supported version 7.0.3)
• Azure PowerShell, specifically Az.Accounts.
• AzAPICall

There is a dev container provided in this repo if you'd wish to use GitHub Codespaces.

1. Validate Microsoft Graph permissions for your user

▶️ If your user is a tenant member user and you plan on running the script as yourself, then no additional setup is necessary. This is the most common. You can 🔽 continue with 2. Validate Azure permissions for your user.

- or -

▶️ However, if your user is tenant guest user and you plan on running the script as yourself, continue to Set up to execute as a tenant guest user to ensure your user is configured properly. You will likely need support from the Microsoft Entra ID administrator of the tenant you are a guest in.

- or -

▶️ If instead you are planning on executing the script as a pre-existing service principal instead of as your user, see Set up to execute as a service principal to ensure it is configured properly.

Set up to execute as a tenant guest user

Your user is a guest user in the tenant or there are other hardened restrictions on the tenant, then your user must first be assigned the Microsoft Entra ID role 'Directory readers'. Work with the Microsoft Entra administrator for the tenant you are a guest in to have them assign the 'Directory readers' role to your guest account.

🔽 Once that is configured, continue with 2. Validate Azure permissions for your user.

Set up to execute as a service principal

You are planning on executing the script as a service principal instead of as your user. A service principal, by default, has no read permissions on users, groups, and other service principals, therefore you'll need to work with a Microsoft Entra ID administrator to grant additional permissions to the service principal. The following Microsoft Graph API permissions, with admin consent, need to be granted:

• 'Application / Application.Read.All'
• 'Group / Group.Read.All'
• 'User / User.Read.All'
• 'PrivilegedAccess / PrivilegedAccess.Read.AzureResources'

Assign Microsoft Graph permissions, if needed

🖱️ Use the Microsoft Entra admin center to assign permissions to the service principal:

To grant API permissions and admin consent for the directory, the user performing the following steps must have 'Privileged Role Administrator' or 'Global Administrator' role assigned in Microsoft Entra ID.

1. Navigate to the Microsoft Entra admin center.
2. Click on 'App registrations'
3. Search for the existing application (service principal)
4. Under 'Manage' click on 'API permissions'
5. Click on 'Add a permissions'
6. Click on 'Microsoft Graph'
7. Click on 'Application permissions'
8. Select the following set of permissions and click 'Add permissions'
   • Application / Application.Read.All
   • Group / Group.Read.All
   • User / User.Read.All
   • PrivilegedAccess / PrivilegedAccess.Read.AzureResources
9. Click on 'Add a permissions'
10. Back in the main 'API permissions' menu you will find permissions with status 'Not granted for...'. Click on 'Grant admin consent for TenantName' and confirm by click on 'Yes'
    • Now you will find the permissions with status 'Granted for TenantName'

Permissions and admin consent granted in Microsoft Entra ID for the service principal (App Registration):

2. Validate Azure permissions for your user

The identity executing the script (your user or the service principal) needs to have the 'Reader' Azure RBAC role assignment on the target management group.

Assign Azure permissions, if needed

If that permission is not yet assigned to your user or the service principal, a user with 'Microsoft.Authorization/roleAssignments/write' permissions on the target management group scope (such as the built-in Azure RBAC role 'User Access Administrator' or 'Owner') is required to make the required permission changes.

🖱️ Use the Azure portal to validate and assign the role:

Follow the instructions at Assign Azure roles using the Azure portal to grant Azure RBAC 'Reader' role to the management group.

⌨️ Or use PowerShell to assign the role:

$objectId = "<objectId of the identity that will execute Azure Governance Visualizer>"
$managementGroupId = "<managementGroupId>"

New-AzRoleAssignment `
-ObjectId $objectId `
-RoleDefinitionName "Reader" `
-Scope /providers/Microsoft.Management/managementGroups/$managementGroupId

3. Clone the Azure Governance Visualizer repository

You'll need a copy of this repository on your workstation.

git clone "https://github.com/Azure/Azure-Governance-Visualizer.git"
Set-Location "Azure-MG-Sub-Governance-Reporting"

4. Authenticate to Azure

As your user:

Connect-AzAccount -TenantId <TenantId> -UseDeviceAuthentication

- or -

As the service principal:

Have the 'Application (client) ID' of the app registration OR 'Application ID' of the service principal (Enterprise application) and the secret of the app registration at hand.

$pscredential = Get-Credential
Connect-AzAccount -ServicePrincipal -TenantId <TenantId> -Credential $pscredential

User: Enter 'Application (client) ID' of the App registration OR 'Application ID' of the service principal (Enterprise application)

Password for user <Id>: Enter App registration's secret

5. Run the Azure Governance Visualizer

Familiarize yourself with the available parameters for Azure Governance Visualizer. The following example will create the output in directory c:\AzGovViz-Output (directory must exist)

.\pwsh\AzGovVizParallel.ps1 -ManagementGroupId <target Management Group Id> -OutputPath "c:\AzGovViz-Output"

6. View the results

Open the generated HTML in your default browser.

Set-Location -Path "c:\AzGovViz-Output"
Get-ChildItem
Invoke-Item ".\AzGovViz*.html"

There is also a markdown version available as well in the output directory.

Using GitHub Codespaces as your console

This repo ships with a GitHub Codespace dev container configuration that has all of the Prerequisites installed.

Visual screenshot tour of that experience

Next steps

Consider a solution that automates the execution of this process to have regular snapshots of this data available for review. This repo has instructions available to automate using Azure DevOps or GitHub. For report hosting, consider using the Azure Governance Visualizer accelerator which will give you an example on how to host the output on Azure Web Apps in conjunction with the automation.