Section 7 - User Assigned Managed Identities

SPARK utilizes a User Assigned Managed Identity (UAMI)1. This reduces the overall attack surface of SPARK as it eliminates the requirements to store secrets/keys within the SPARK application. User Assigned Managed Identities are the recommended managed identity type for Microsoft services.

Requirements

The Azure Administrator will be required for this step. The user must have:

  • Global Administrator role2 or Application Administrator Role
  • Owner role for the resource group
  • Access to the Azure Portal
  • PnP.PowerShell installed
  • PnP App Certificate generated during Step 5 of the Pre-Deployment Guide

The required permissions3 for the PnP.PowerShell script will require at a minimum:

  1. AppRoleAssignment.ReadWrite.All
  2. Application.Read.All

If running Azure Cloud Shell4, or any shell that doesn’t have a GUI, then reference the link below if you are unable to connect to PnP.

PowerShell Script

  1. Review the script and install the required modules if needed
  2. Update the pnp-connection information
    • clientId - The PnP app registration client id
    • environment - The PnP environment value
    • spoAdminUrl - The SPO admin url
    • tenantId - The tenant id
    • thumbprint - The PnP app registration certificate thumbprint
  3. Review the permissions and azure roles to apply to the uami
  4. Run the script and validate that the uami was created and configured
  5. Update the SPARK deployment workbook variables from the script output
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

########################################## Required Modules ##########################################
#Install-Module Az.ManagedServiceIdentity

########################################## UAMI Information ##########################################
# Set the information
$info = @{
    clientId = "XXXXXXXX-9b85-4b4a-8df2-b799d47e8471"
    environment = "Microsoft365"
    spoAdminUrl = "https://tenant-admin.sharepoint.com"
    tenantId = "XXXXXXXX-eeae-4761-b1cb-1a83e86ef445"
    thumbprint = "1A2B3C4D5E6F708192A3B4C5D6E7F8091A2B3C4D"
    roles = @(
        "Automation Operator"
        "Storage Blob Data Contributor"
    )
    permissions = @{
        graph = @(
            "Sites.FullControl.All",
            "Directory.Read.All",
            "Group.Read.All",
            "User.Read.All"
        )
        spo = @(
            "Sites.FullControl.All"
        )
    }
}

########################################## Connect to Azure ##########################################
# Connect to Azure
Import-Module Az.ManagedServiceIdentity
Connect-AzAccount | Out-Null;

########################################## Create Resource Group ##########################################
# Get the resource group
$rg = Get-AzResourceGroup -Name sub-spark-rg

# Get the uami
$uami = Get-AzUserAssignedIdentity -ResourceGroupName sub-spark-rg -Name uami-spark-spoactions -ErrorAction SilentlyContinue
if($uami -eq $null) {
    # Create the uami
    $uami = New-AzUserAssignedIdentity -Name "uami-spark-spoactions" `
        -ResourceGroupName $rg.ResourceGroupName `
        -Location $rg.Location
}

########################################## Connect to PnP ##########################################
if($info.environment -ne "Microsoft365") {
    # Connection for GCC-High and DoD
    Connect-PnPOnline -Url $info.spoAdminUrl -ClientId $info.clientId -Thumbprint $info.thumbprint -Tenant $info.tenantId -AzureEnvironment $info.environment
} else {
    # Connection for Commercial and GCC
    Connect-PnPOnline -Url $info.spoAdminUrl -ClientId $info.clientId -Thumbprint $info.thumbprint -Tenant $info.tenantId
}

########################################## Grant Permissions ##########################################
# Parse the graph permissions
$info.permissions.graph | ForEach-Object {
    # Grant the graph permission
    Add-PnPAzureADServicePrincipalAppRole -Principal $uami.PrincipalId  -AppRole $_ -BuiltInType MicrosoftGraph

    # Log
    Write-Host "Permission Added: $_"
}

# Parse the spo permissions
$info.permissions.spo | ForEach-Object {
    # Grant the spo permission
    Add-PnPAzureADServicePrincipalAppRole -Principal $uami.PrincipalId  -AppRole $_ -BuiltInType SharePointOnline

    # Log
    Write-Host "Permission Added: $_"
}

########################################## Grant Roles ##########################################
# Parse the roles
$info.roles | ForEach-Object {
    # Grant the role
    New-AzRoleAssignment -ObjectId $uami.PrincipalId `
        -RoleDefinitionName $_ `
        -Scope $rg.ResourceId

    # Log
    Write-Host "Role Added: $_"
}
########################################## Variables ##########################################
# Output the variables for the spreadsheet
Write-Host "Spreadsheet value v_uamiName: $($uami.Name)"
Write-Host "Spreadsheet value UAMI objId: $($uami.PrincipalId)"

########################################## Disconnect ##########################################
Disconnect-AzAccount | Out-Null;
Disconnect-PnPOnline | Out-Null;

Manual Steps:

Video Walkthrough

Step 1: Create User Assigned Managed Identity

  1. Browse and log into the Azure Portal

Use the correct URL for your environment:

Worldwide (Commercial) & GCC https://portal.azure.com
GCC-High and DoD https://portal.azure.us
  1. From the top search bar, enter Managed Identities and select it from the search results
Manage Identities
  1. Click on Create and then set the properties shown in the table
Name Value
Subscription The subscription associated with the resource group
Resource Group The resource group created in Step 6 of pre-deployment
Name uami-spark-spoactions
Region The same as resource group
Create UAMI
  1. Click Review + create
  2. Click Create to create the user assigned managed identity
  3. Wait for the user assigned managed identity resource to be created, and then select Go to resource
Configure Graph Permissions

DOCUMENTATION STEP

Document the following values in the SPARK Deployment Workbook

Deployment Tab > Azure General

  • v_clientId The uami application id
  • v_uamiName: The uami name
  • UAMI objId: The uami object id

Step 2: Configure User Assigned Managed Identity Graph Permissions

  1. Modify the script below with the following parameters you gathered from the SPARK Deployment Workbook
  2. Open PowerShell v7.2+ and run the script shown below
Name Value
Certificate The certificate thumbprint associated with the app registration that is used for PnP.PowerShell
Client ID The app registration id that is used for PnP.PowerShell
SPO Admin Url The SharePoint Admin center url
Tenant Environment The environment containing the tenant:
USGovernment
USGovernmentHigh
USGovernmentDoD
Tenant ID The tenant id
UAMI Object ID The UAMI object id found in step 1

The required permissions5 for the PnP.PowerShell script will require at a minimum:

  1. AppRoleAssignment.ReadWrite.All
  2. Application.Read.All
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# Set the UAMI object id
$objectId = "<UAMI Object ID>"

# Connection for Commercial and GCC
#Connect-PnPOnline -Url <SPO Admin Url> -ClientId <Client ID> -Thumbprint <Certificate> -Tenant <Tenant ID>

# Connection for GCC-High and DoD
Connect-PnPOnline -Url <SPO Admin Url> -ClientId <Client ID> -Thumbprint <Certificate> -Tenant <Tenant ID> -AzureEnvironment <Tenant Environment>

# Principal is Object Id of the System Assigned MI
Add-PnPAzureADServicePrincipalAppRole -Principal $objectId -AppRole "Sites.FullControl.All" -BuiltInType SharePointOnline 

#Graph SharePoint Site.FullControl.All
Add-PnPAzureADServicePrincipalAppRole -Principal $objectId  -AppRole "Sites.FullControl.All" -BuiltInType MicrosoftGraph

# Grant Directory.Read.All
Add-PnPAzureADServicePrincipalAppRole -Principal $objectId  -AppRole "Directory.Read.All" -BuiltInType MicrosoftGraph

# Grant Group.Read.All
Add-PnPAzureADServicePrincipalAppRole -Principal $objectId  -AppRole "Group.Read.All" -BuiltInType MicrosoftGraph

# Grant User.Read.All
Add-PnPAzureADServicePrincipalAppRole -Principal $objectId -AppRole "User.Read.All" -BuiltInType MicrosoftGraph

# Disconnect from PnP
Disconnect-PnPOnline

The sample Connect-PnPOnline connection string within the script above is not the only method of completing this step. Alternative methods are available and may be used if already configured within the local organization.

Step 3: Configure User Assigned Managed Identity RBAC

  1. Open the uami-spark-spoactions UAMI
  2. Select Azure role assignments from the left navigation
  3. Click on + Add role assignment
  4. Add the role assignments shown below in the table
Name Value
Scope Resource Group
Subscription The subscription associated with the resource group
Resource Group The resource group created in Step 6 of pre-deployment
Roles Storage Blob Data Contributor
Automation Operator
RBAC
  1. Click Save to add the role assignment

This step will configure the permissions for the storage account used by SQL and the runbooks that will be provisioned later on. This may take several minutes to be added to the uami.

  1. Click on Refresh and validate the role assignements were added
Verify RBAC

Continue to creating the Automation Accounts

References

  1. What is managed identities for Azure resources? ↩

  2. Azure roles ↩

  3. Reference Link - Add-PnPAzureADServicePrincipalAppRole ↩

  4. Reference Link - [BUG] Unable to connect to PNP with CloudShell ↩

  5. Reference Link - Add-PnPAzureADServicePrincipalAppRole ↩