Skip to content

Latest commit

 

History

History
536 lines (395 loc) · 23.3 KB

setup.md

File metadata and controls

536 lines (395 loc) · 23.3 KB
Raw

AzGovViz - Azure Governance Visualizer - Setup

This guide will help you to setup and run AzGovViz

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

Table of contents

  • AzGovViz from Console

    • Grant permissions in Azure
    • Execution options
      • Option 1 - Execute as a Tenant Member User
      • Option 2 - Execute as a Tenant Guest User
      • Option 3 - Execute as Service Principal
    • Clone the AzGovViz repository
    • Run AzGovViz

  • AzGovViz in Azure DevOps (AzDO)

    • Create AzDO Project
    • Import AzGovViz GitHub repository
    • Create AzDO Service Connection
      • Option 1 - Create Service Connection in AzDO
      • Option 2 - Create Service Connection´s Service Principal in the Azure Portal
    • Grant permissions in Azure
    • Grant permissions in AAD
    • Grant permissions on AzGovViz AzDO repository
    • Edit AzDO YAML file
    • Create AzDO Pipeline
    • Run the AzDO Pipeline
    • Create AzDO Wiki - WikiAsCode

  • AzGovViz in GitHub Actions

    • Create GitHub repository
    • Import Code
    • AzGovViz YAML
      • Store the credentials in GitHub
      • Edit the workflow YAML file
      • Run AzGovViz in GitHub Actions
    • AzGovViz OIDC YAML
      • Store the credentials in GitHub
      • Edit the workflow YAML file
      • Run AzGovViz in GitHub Actions

  • AzGovViz in GitHub Codespaces

AzGovViz 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 AzGovViz

  • PowerShell
$objectId = "<objectId of the identity that shall run AzGovViz>"
$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 AzGovViz 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 AzGovViz (work with the Guest User´s display name)

Proceed with step Clone the AzGovViz 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
    • Click on 'Add a permissions'
    • Back in the main 'API permissions' menu you will find 3 permissions with status 'Not granted for...'. Click on 'Grant admin consent for TenantName' and confirm by click on 'Yes'
    • Now you will find the 3 permissions with status 'Granted for TenantName'

Permissions in Azure Active Directory for App registration: alt text

Proceed with step Clone the AzGovViz repository

Clone the AzGovViz repository

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

Proceed with step Run AzGovViz from Console

Run AzGovViz 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 AzGovViz

Familiarize yourself with the available parameters for AzGovViz

  • 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"

AzGovViz in Azure DevOps

Create AzDO Project

Create a project

Import AzGovViz GitHub repository

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

Import into a new repo

Note: the AzGovViz 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. 'AzGovViz_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 AzGovViz 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. 'AzGovViz_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
    • Click on 'Add a permissions'
    • Back in the main 'API permissions' menu you will find the 3 permissions with status 'Not granted for...'. Click on 'Grant admin consent for TenantName' and confirm by click on 'Yes'
    • Now you will find the 3 permissions with status 'Granted for TenantName'

Permissions in Azure Active Directory for App registration: alt text

Grant permissions on AzGovViz AzDO repository

When the AzDO pipeline executes the AzGovViz script the outputs should be pushed back to the AzGovViz 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 AzGovViz AzDO repository
    • In AzDO click on 'Project settings' (located on the bottom left), under 'Repos' open the 'Repositories' page
    • Click on the AzGovViz 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 AzGovViz 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 AzGovViz 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 AzGovViz 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 AzGovViz 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 AzGovViz 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 AzGovViz repository
  • Select the folder 'wiki' and click 'OK'
  • Enter a name for the Wiki
  • Click 'Publish'

AzGovViz 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

AzGovViz 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. 'AzGovViz_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 (AzGovViz 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 (AzGovViz 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 AzGovViz then enable the schedule in the on section

Run AzGovViz in GitHub Actions (AzGovViz YAML)

In GitHub navigate to 'Actions'

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

AzGovViz 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. 'AzGovViz_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 AzGovViz repository)
  • Fill the field 'Name' with a name (e.g. AzGovViz_GitHub_Actions)
  • Click 'Add'

Store the credentials in GitHub (AzGovViz 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 (AzGovViz 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 AzGovViz then enable the schedule in the on section

Run AzGovViz in GitHub Actions (AzGovViz OIDC YAML)

In GitHub navigate to 'Actions'

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

AzGovViz 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