Skip to content

Latest commit

 

History

History
587 lines (439 loc) · 29.6 KB

setup.md

File metadata and controls

587 lines (439 loc) · 29.6 KB

Azure Governance Visualizer aka AzGovViz - Setup

This guide will help you to setup and run AzGovViz

  • Abbreviations:
    • Azure Active Directory - AAD
    • Azure DevOps - AzDO

Table of content

Azure Governance Visualizer from Console

Grant permissions in Azure

  • Requirements
    • To assign roles, you must have 'Microsoft.Authorization/roleAssignments/write' permissions on the target Management Group scope (such as the built-in RBAC Role 'User Access Administrator' or 'Owner')

Create a 'Reader' RBAC Role assignment on the target Management Group scope for the identity that shall run Azure Governance Visualizer

  • PowerShell
$objectId = "<objectId of the identity that shall run Azure Governance Visualizer>"
$role = "Reader"
$managementGroupId = "<managementGroupId>"

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

Execution options

Option 1 - Execute as a Tenant Member User

Proceed with step Clone the Azure Governance Visualizer repository

Option 2 - Execute as a Tenant Guest User

If the tenant is hardened (AAD External Identities / Guest user access = most restrictive) then Guest User must be assigned the AAD Role 'Directory readers'

💡 Compare member and guest default permissions

💡 Restrict Guest permissions

Assign AAD Role - Directory readers

Assign the AAD Role 'Directory Reader' for the Guest User that shall run Azure Governance Visualizer (work with the Guest User´s display name)

Proceed with step Clone the Azure Governance Visualizer repository

Option 3 - Execute as Service Principal

A Service Principal by default has no read permissions on Users, Groups and Service Principals, therefore we need to grant additional permissions in AAD

Grant API permissions

  • Requirements
    • To grant API permissions and grant admin consent for the directory, you must have 'Privileged Role Administrator' or 'Global Administrator' role assigned Assign Azure AD roles to users

Grant API permissions for the Service Principal´s Application

  • Navigate to 'Azure Active Directory'
  • Click on 'App registrations'
  • Search for the Application that we created earlier and click on it
  • Under 'Manage' click on 'API permissions'
    • Click on 'Add a permissions'
    • Click on 'Microsoft Graph'
    • Click on 'Application permissions'
    • 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
    • Click on 'Add a permissions'
    • 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 in Azure Active Directory for App registration: alt text

Proceed with step Clone the Azure Governance Visualizer repository

Clone the Azure Governance Visualizer repository

  • Requirements

  • PowerShell

Set-Location "c:\Git"
git clone "https://github.com/JulianHayward/Azure-MG-Sub-Governance-Reporting.git"

Proceed with step Run Azure Governance Visualizer from Console

Run Azure Governance Visualizer from Console

PowerShell & Azure PowerShell modules

Connecting to Azure as User (Member or Guest)

  • PowerShell
Connect-AzAccount -TenantId <TenantId> -UseDeviceAuthentication

Connecting to Azure using 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

  • PowerShell
$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

Run Azure Governance Visualizer

Familiarize yourself with the available parameters for Azure Governance Visualizer

  • PowerShell
c:\Git\Azure-MG-Sub-Governance-Reporting\pwsh\AzGovVizParallel.ps1 -ManagementGroupId <target Management Group Id>

Note if not using the -OutputPath parameter, all outputs will be created in the current directory. The following example will create the outputs in directory c:\AzGovViz-Output (directory must exist)

  • PowerShell
c:\Git\Azure-MG-Sub-Governance-Reporting\pwsh\AzGovVizParallel.ps1 -ManagementGroupId <target Management Group Id> -OutputPath "c:\AzGovViz-Output"

Azure Governance Visualizer in Azure DevOps

Create AzDO Project

Create a project

Import Azure Governance Visualizer GitHub repository

Azure Governance Visualizer Clone URL: https://github.com/JulianHayward/Azure-MG-Sub-Governance-Reporting.git

Import into a new repo

Note: the Azure Governance Visualizer GitHub repository is public - no authorization required

Create AzDO Service Connection

For the pipeline to authenticate and connect to Azure we need to create an AzDO Service Connection which basically is a Service Principal (Application) There are two options to create the Service Connection:

  • Options
    • Option 1 Create Service Connection´s Service Principal in the Azure Portal
    • Option 2 Create Service Connection in AzDO

Create AzDO Service Connection - Option 1 - Create Service Connection´s Service Principal in the Azure Portal

Azure Portal

  • Navigate to 'Azure Active Directory'
  • Click on 'App registrations'
  • Click on 'New registration'
  • Name your application (e.g. 'AzureGovernanceVisualizer_SC')
  • Click 'Register'
  • Your App registration has been created, in the 'Overview' copy the 'Application (client) ID' as we will need it later to setup the Service Connection in AzDO
  • Under 'Manage' click on 'Certificates & Secrets'
  • Click on 'New client secret'
  • Provide a good description and choose the expiry time based on your need and click 'Add'
  • A new client secret has been created, copy the secret´s value as we will need it later to setup the Service Connection in AzDO

Note: if you do not assign the RBAC 'Reader' role to the Management group at this stage then the 'Verify' step in Azure DevOps will fail.

  • In the portal proceed to 'Management Groups', select the scope at which Azure Governance Visualizer will run, usually Tenant Root Group
  • Go to 'Access Control (IAM)', 'Grant Access' and 'Add Role Assignment', select 'Reader', click 'Next'
  • Now 'Select Member', this will be the name of the Application you created above (e.g. 'AzureGovernanceVisualizer_SC').
  • Select 'Next', 'Review + Assign'

Azure DevOps

  • Click on 'Project settings' (located on the bottom left)
  • Under 'Pipelines' click on 'Service Connections'
  • Click on 'New service connection' and select the connection/service type 'Azure Resource Manager' and click 'Next'
  • For the authentication method select 'Service principal (manual)' and click 'Next'
  • For the 'Scope level' select 'Management Group'
    • In the field 'Management Group Id' enter the target Management Group Id
    • In the field 'Management Group Name' enter the target Management Group Name
  • Under 'Authentication' in the field 'Service Principal Id' enter the 'Application (client) ID' that you copied away earlier
  • For the 'Credential' select 'Service principal key', in the field 'Service principal key' enter the secret that you copied away earlier
  • For 'Tenant ID' enter your Tenant Id
  • Click on 'Verify'
  • Under 'Details' provide your Service Connection with a name and copy away the name as we will need that later when editing the Pipeline YAML file
  • For 'Security' leave the 'Grant access permissions to all pipelines' option checked (optional)
  • Click on 'Verify and save'

Create AzDO Service Connection - Option 2 - Create Service Connection in AzDO

  • Click on 'Project settings' (located on the bottom left)
  • Under 'Pipelines' click on 'Service connections'
  • Click on 'New service connection' and select the connection/service type 'Azure Resource Manager' and click 'Next'
  • For the authentication method select 'Service principal (automatic)' and click 'Next'
  • For the 'Scope level' select 'Management Group', in the Management Group dropdown select the target Management Group (here the Management Group´s display names will be shown), in the 'Details' section apply a Service Connection name and optional give it a description and click 'Save'
  • A new window will open, authenticate with your administrative account
  • Now the Service Connection has been created

Important! In Azure on the target Management Group scope an 'Owner' RBAC Role assignment for the Service Connection´s Service Principal has been created automatically (we do however only require a 'Reader' RBAC Role assignment! we will take corrective action in the next steps)

Grant permissions in Azure

  • Requirements
    • To assign roles, you must have 'Microsoft.Authorization/roleAssignments/write' permissions on the target Management Group scope (such as the built-in RBAC Role 'User Access Administrator' or 'Owner')

Create a 'Reader' RBAC Role assignment on the target Management Group scope for the AzDO Service Connection´s Service Principal

  • PowerShell
$objectId = "<objectId of the AzDO Service Connection´s Service Principal>"
$role = "Reader"
$managementGroupId = "<managementGroupId>"

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

Important! If you have created the AzDO Service Connection in AzDO (Option 2) then you SHOULD remove the automatically created 'Owner' RBAC Role assignment for the AzDO Service Connection´s Service Principal from the target Management Group

Grant permissions in AAD

API permissions

  • Requirements
    • To grant API permissions and grant admin consent for the directory, you must have 'Privileged Role Administrator' or 'Global Administrator' role assigned (Assign Azure AD roles to users)

Grant API permissions for the Service Principal´s Application that we created earlier

  • Navigate to 'Azure Active Directory'
  • Click on 'App registrations'
  • Search for the Application that we created earlier and click on it
  • Under 'Manage' click on 'API permissions'
    • Click on 'Add a permissions'
    • Click on 'Microsoft Graph'
    • Click on 'Application permissions'
    • 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
    • Click on 'Add a permissions'
    • Back in the main 'API permissions' menu you will find the 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 in Azure Active Directory for App registration: alt text

Grant permissions on Azure Governance Visualizer AzDO repository

When the AzDO pipeline executes the Azure Governance Visualizer script the outputs should be pushed back to the Azure Governance Visualizer AzDO repository, in order to do this we need to grant the AzDO Project´s Build Service account with 'Contribute' permissions on the repository

  • Grant permissions on the Azure Governance Visualizer AzDO repository
    • In AzDO click on 'Project settings' (located on the bottom left), under 'Repos' open the 'Repositories' page
    • Click on the Azure Governance Visualizer AzDO Repository and select the tab 'Security'
    • On the right side search for the Build Service account %Project name% Build Service (%Organization name%) and grant it with 'Contribute' permissions by selecting 'Allow' (no save button available)

OPTION 1 (legacy) - Edit AzDO YAML file (.pipelines folder)

  • Click on 'Repos'
  • Navigate to the Azure Governance Visualizer Repository
  • In the folder 'pipeline' click on 'AzGovViz.yml' and click 'Edit'
  • Under the variables section
    • Enter the Service Connection name that you copied earlier (ServiceConnection)
    • Enter the Management Group Id (ManagementGroupId)
  • Click 'Commit'

OPTION 1 (legacy) - Create AzDO Pipeline (.pipelines folder)

  • Click on 'Pipelines'
  • Click on 'New pipeline'
  • Select 'Azure Repos Git'
  • Select the Azure Governance Visualizer repository
  • Click on 'Existing Azure Pipelines YAML file'
  • Under 'Path' select '/.pipelines/AzGovViz.yml' (the YAML file we edited earlier)
  • Click ' Save'

OPTION 2 (new) - Edit AzDO Variables YAML file (.azuredevops folder)

For the 'parameters' and 'variables' sections, details about each parameter or variable is documented inline.

  • Click on 'Repos'
  • Navigate to the Azure Governance Visualizer repository
  • In the folder '/.azuredevops/pipelines' click on 'AzGovViz.variables.yml' and click 'Edit'
  • If needed, modify the 'parameters' section:
    • For more information about parameters
    • [Optional] Update the 'ExcludedResourceTypesDiagnosticsCapableParameters'
    • [Optional] Update the 'SubscriptionQuotaIdWhitelistParameters'
  • Update the 'Required Variables' section:
    • Replace <YourServiceConnection> with the Service connection name you copied earlier (ServiceConnection)
    • Replace <YourManagementGroupId> with the Management Group Id (ManagementGroupId)
  • If needed, update the 'Default Variables' section
  • If needed, update the 'Optional Variables' section

OPTION 2 (new) Create AzDO Pipeline (.azuredevops folder)

  • Click on 'Pipelines'
  • Click on 'New pipeline'
  • Select 'Azure Repos Git'
  • Select the Azure Governance Visualizer repository
  • Click on 'Existing Azure Pipelines YAML file'
  • Under 'Path' select '/.azuredevops/pipelines/AzGovViz.pipeline.yml'
  • Click ' Save'

Run the AzDO Pipeline

  • Click on 'Pipelines'
  • Select the Azure Governance Visualizer pipeline
  • Click 'Run pipeline'

Create AzDO Wiki (WikiAsCode)

Once the pipeline has executed successfully we can setup our Wiki (WikiAsCode)

  • Click on 'Overview'
  • Click on 'Wiki'
  • Click on 'Publish code as wiki'
  • Select the Azure Governance Visualizer repository
  • Select the folder 'wiki' and click 'OK'
  • Enter a name for the Wiki
  • Click 'Publish'

Azure Governance Visualizer in GitHub Actions

Create GitHub repository

Create a 'private' repository

Import Code

Click on 'Import code'

Use 'https://github.com/JulianHayward/Azure-MG-Sub-Governance-Reporting.git' as clone URL

Click on 'Begin import'

Navigate to your newly created repository In the folder ./github/workflows two worklows are available:

  1. AzGovViz.yml Use this workflow if you want to store your Application (App registration) secret in GitHub

  2. AzGovViz_OIDC.yml Use this workflow if you want leverage the OIDC (Open ID Connect) feature - no secret stored in GitHub

Azure Governance Visualizer YAML

For the GitHub Actiom to authenticate and connect to Azure we need to create Service Principal (Application)

In the Azure Portal navigate to 'Azure Active Directory'

  • Click on 'App registrations'
  • Click on 'New registration'
  • Name your application (e.g. 'AzureGovernanceVisualizer_SC')
  • Click 'Register'
  • Your App registration has been created, in the 'Overview' copy the 'Application (client) ID' as we will need it later to setup the secrets in GitHub
  • Under 'Manage' click on 'Certificates & Secrets'
  • Click on 'New client secret'
  • Provide a good description and choose the expiry time based on your need and click 'Add'
  • A new client secret has been created, copy the secret´s value as we will need it later to setup the secrets in GitHub

Store the credentials in GitHub (Azure Governance Visualizer YAML)

In GitHub navigate to 'Settings'

  • Click on 'Secrets'
  • Click on 'Actions'
  • Click 'New repository secret'
    • Name: CREDS
    • Value:
{
   "tenantId": "<GUID>",
   "subscriptionId": "<GUID>",
   "clientId": "<GUID>",
   "clientSecret": "<GUID>"
}

Workflow permissions

In GitHub navigate to 'Settings'

  • Click on 'Actions'
  • Click on 'General'
  • Under 'Workflow permissions' select 'Read and write permissions'
  • Click 'Save'

Edit the workflow YAML file (Azure Governance Visualizer YAML)

  • In the folder ./github/workflows edit the YAML file AzGovViz.yml
  • In the env section enter you Management Group ID
  • If you want to continuously run Azure Governance Visualizer then enable the schedule in the on section

Run Azure Governance Visualizer in GitHub Actions (Azure Governance Visualizer YAML)

In GitHub navigate to 'Actions'

  • Click 'Enable GitHub Actions on this repository'
  • Select the Azure Governance Visualizer workflow
  • Click 'Run workflow'

Azure Governance Visualizer OIDC YAML

For the GitHub Actiom to authenticate and connect to Azure we need to create Service Principal (Application). Using OIDC we will however not have the requirement to create a secret, nore store it in GitHub - awesome :)

  • Navigate to 'Azure Active Directory'
  • Click on 'App registrations'
  • Click on 'New registration'
  • Name your application (e.g. 'AzureGovernanceVisualizer_SC')
  • Click 'Register'
  • Your App registration has been created, in the 'Overview' copy the 'Application (client) ID' as we will need it later to setup the secrets in GitHub
  • Under 'Manage' click on 'Certificates & Secrets'
  • Click on 'Federated credentials'
  • Click 'Add credential'
  • Select Federation credential scenario 'GitHub Actions deploying Azure Resources'
  • Fill the field 'Organization' with your GitHub Organization name
  • Fill the field 'Repository' with your GitHub repository name
  • For the entity type select 'Branch'
  • Fill the field 'GitHub branch name' with your branch name (default is 'master' if you imported the Azure Governance Visualizer repository)
  • Fill the field 'Name' with a name (e.g. AzureGovernanceVisualizer_GitHub_Actions)
  • Click 'Add'

Store the credentials in GitHub (Azure Governance Visualizer OIDC YAML)

In GitHub navigate to 'Settings'

  • Click on 'Secrets'
  • Click on 'Actions'
  • Click 'New repository secret'
  • Create the following three secrets:
    • Name: CLIENT_ID
      Value: Application (client) ID
    • Name: TENANT_ID
      Value: Tenant ID
    • Name: SUBSCRIPTION_ID
      Value: Subscription ID

Workflow permissions

In GitHub navigate to 'Settings'

  • Click on 'Actions'
  • Click on 'General'
  • Under 'Workflow permissions' select 'Read and write permissions'
  • Click 'Save'

Edit the workflow YAML file (Azure Governance Visualizer OIDC YAML)

  • In the folder ./github/workflows edit the YAML file AzGovViz_OIDC.yml
  • In the env section enter you Management Group ID
  • If you want to continuously run Azure Governance Visualizer then enable the schedule in the on section

Run Azure Governance Visualizer in GitHub Actions (Azure Governance Visualizer OIDC YAML)

In GitHub navigate to 'Actions'

  • Click 'Enable GitHub Actions on this repository'
  • Select the AzGovViz_OIDC workflow
  • Click 'Run workflow'

Azure Governance Visualizer GitHub Codespaces

Note: Codespaces is available for organizations using GitHub Team or GitHub Enterprise Cloud. Quickstart for Codespaces

alt text

alt text

alt text

alt text

alt text

Optional Publishing the Azure Governance Visualizer HTML to a Azure Web App

There are instances where you may want to publish the HTML output to a webapp so that anybody in the business can see up to date status of the Azure governance.

There are a few models to do this, the option below is one way to get you started.

Prerequisites

  • Deploy a simple webapp on Azure. This can be the smallest SKU or a FREE SKU. It doesn't matter whether you choose Windows or Linux as the platform
    alt text
  • Step through the configuration. I typically use the Code for the publish and then select the Runtime stack that you standardize on alt text
  • No need to configure anything, unless your organization policies require you to do so
    NOTE: it is a good practice to tag your resource for operational and finance reasons
  • In the webapp Configuration add the name of the HTML output file to the Default Documents
    alt text
  • Make sure to configure Authentication!
    alt text

Azure DevOps

  • Assign the Azure DevOps Service Connection´s Service Principal with RBAC Role Website Contributor on the Azure Web App
  • Edit the .azuredevops/AzGovViz.variables.yml file
    alt text

GitHub Actions

  • Assign the Service Principal used in GitHub with RBAC Role Website Contributor on the Azure Web App
  • Edit the .github/workflows/AzGovViz_OIDC.yml or .github/workflows/AzGovViz.yml file
    alt text