Task 02: Assign RBAC Roles
DOCUMENT CATEGORY: Runbook
SCOPE: RBAC role assignment for Azure Local deployment identities
PURPOSE: Assign required roles to the deployment SPN and deployment user at subscription and resource group scope
MASTER REFERENCE: Microsoft Learn - Assign Azure Roles
Status: Active Applies To: Phase 03 — RBAC Permissions Last Updated: 2026-03-02
Overview
Assign the required RBAC roles to the Azure Local deployment service principal and deployment user. This is the Permission Transition Point — after completion, the deployment SPN has sufficient permissions for all subsequent phases.
After assigning these roles, the deployment SPN will have sufficient permissions for all subsequent deployment phases. No further elevated admin access is required.
Prerequisites
- Active Azure session with Owner or User Access Administrator role at subscription level
- Task 01: Create Deployment SPN completed —
sp-azurelocal-deployexists in Entra ID - Subscription ID confirmed in
infrastructure.yml→azure.subscription_id - Cluster resource group confirmed in
infrastructure.yml→azure.resource_group
Values from infrastructure.yml
The script reads these keys from infrastructure.yml (schema 5). Each key, with its type, default and example, is in the variables reference.
New-EntraSecurityGroups.ps1:
azure.tenant_id the tenant the sign-in must belong to
identity.entra.groups[].name the display name of the group (1 to 256 characters)
identity.entra.groups[].purpose the description of the group (optional, up to 1024 characters)
If a group of that name exists but is not a security group (a Microsoft 365 group or a distribution list), the script reports a conflict, does not create the group and exits 1. An entry of identity.entra.groups that is not a map stops the script with exit 2.
Set-EntraGroupRoleAssignments.ps1:
azure.tenant_id the tenant the sign-in must belong to
azure.subscription_id, azure.resource_group the default scope of an entry that has none
identity.entra.groups[].name the display name of the group
identity.entra.groups[].roles the Azure role names to assign
identity.entra.groups[].scope where to assign them (optional)
Section 1: Assign RBAC Roles to Service Principal
Assign the required RBAC roles to the deployment service principal created in Task 01. This enables automated deployments using the SPN credentials.
- Azure Portal
- Orchestrated Script
- Azure CLI
1. Navigate to Subscription IAM
- Go to Subscriptions → Select your Azure Local subscription
- Click Access control (IAM)
2. Add Role Assignments
For each role, repeat the following:
- Click + Add → Add role assignment
- In the Role tab — search for and select the role, then click Next
- In the Members tab:
- Select User, group, or service principal
- Click + Select members
- Search for
sp-azurelocal-deploy - Select the service principal → Click Select
- Click Review + assign
3. Required Role Assignments
Assign all of the following roles to sp-azurelocal-deploy:
Subscription-level roles:
| Role | Purpose |
|---|---|
Contributor | Create and manage resources |
User Access Administrator | Assign RBAC to other identities |
Azure Stack HCI Administrator | Azure Local cluster management |
Reader | View resources |
Resource group-level roles (at the Azure Local cluster resource group, e.g., rg-c01-azl-eus-01):
| Role | Purpose |
|---|---|
Key Vault Data Access Administrator | Manage data plane permissions to deployment Key Vault |
Key Vault Secrets Officer | Read and write secrets in deployment Key Vault |
Key Vault Contributor | Create and manage Key Vault resources for deployment |
Storage Account Contributor | Create storage accounts for deployment |
Azure Connected Machine Onboarding | Register machines with Azure Arc |
Azure Connected Machine Resource Administrator | Manage Arc-enabled machine resources |
All resource group-level roles MUST be assigned at the cluster resource group:
/subscriptions/<subscription-id>/resourceGroups/<cluster-resource-group>
Example: /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-c01-azl-eus-01
Do NOT assign these to the platform Key Vault resource group.
Validation
- Go to Access control (IAM) → Role assignments
- Filter by the service principal name
- Verify all 10 roles are listed
PowerShell
When to use: Run the task from a management workstation or a pipeline. The script reads
infrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/02-azure-foundation/phase-03-rbac-permissions/task-02-assign-rbac-roles/powershell/New-EntraSecurityGroups.ps1 | Creates the Microsoft Entra security groups that identity.entra.groups of infrastructure.yml lists. Supports -WhatIf. |
scripts/deploy/02-azure-foundation/phase-03-rbac-permissions/task-02-assign-rbac-roles/powershell/Set-EntraGroupRoleAssignments.ps1 | Assigns the Azure roles that identity.entra.groups of infrastructure.yml gives each Microsoft Entra group, at the scope it names. Supports -WhatIf. |
Requires: PowerShell 7; modules Az.Accounts, Az.KeyVault, powershell-yaml.
Run
./New-EntraSecurityGroups.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Set-EntraGroupRoleAssignments.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
Azure CLI
When to use: Run the task from a host that has the Azure CLI and not the Az PowerShell modules. The script is PowerShell 7 that calls
az; it readsinfrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/02-azure-foundation/phase-03-rbac-permissions/task-02-assign-rbac-roles/azurecli/New-EntraSecurityGroups.azcli.ps1 | Creates the Microsoft Entra security groups that identity.entra.groups of infrastructure.yml lists, with the Azure CLI. Supports -WhatIf. |
scripts/deploy/02-azure-foundation/phase-03-rbac-permissions/task-02-assign-rbac-roles/azurecli/Set-EntraGroupRoleAssignments.azcli.ps1 | Assigns the Azure roles that identity.entra.groups of infrastructure.yml gives each Microsoft Entra group, at the scope it names, with the Azure CLI. Supports -WhatIf. |
Requires: PowerShell 7 and the Azure CLI, signed in with az login --tenant <azure.tenant_id>.
Azure side only. The first script adds no members. The second never removes a role assignment, and a role held at a higher scope does not count: it assigns the role at the scope the file names. Owner and User Access Administrator let the group grant access to others, so review the file before you run it. You need a role that can write role assignments at each scope, and permission to read groups.
Run
./New-EntraSecurityGroups.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./New-EntraSecurityGroups.azcli.ps1 -InfrastructureFile ./infrastructure.yml
./Set-EntraGroupRoleAssignments.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Set-EntraGroupRoleAssignments.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Section 2: Assign RBAC Roles to Deployment User
If a human user will perform portal-based deployments (in addition to or instead of the SPN), assign the same roles to their user account.
- Azure Portal
- Orchestrated Script
- Azure CLI
1. Navigate to Subscription IAM
- Go to Subscriptions → Select your Azure Local subscription
- Click Access control (IAM)
2. Add Role Assignments
For each role, repeat the same process as Section 1, but search for the deployment user's name or email instead of the service principal.
3. Required Role Assignments
Assign the same 10 roles listed in Section 1 (4 subscription-level + 6 resource group-level) to the deployment user.
Validation
- Go to Access control (IAM) → Role assignments
- Filter by the user's name
- Verify all 10 roles are listed
PowerShell
When to use: Run the task from a management workstation or a pipeline. The script reads
infrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/02-azure-foundation/phase-03-rbac-permissions/task-02-assign-rbac-roles/powershell/New-EntraSecurityGroups.ps1 | Creates the Microsoft Entra security groups that identity.entra.groups of infrastructure.yml lists. Supports -WhatIf. |
scripts/deploy/02-azure-foundation/phase-03-rbac-permissions/task-02-assign-rbac-roles/powershell/Set-EntraGroupRoleAssignments.ps1 | Assigns the Azure roles that identity.entra.groups of infrastructure.yml gives each Microsoft Entra group, at the scope it names. Supports -WhatIf. |
Requires: PowerShell 7; modules Az.Accounts, Az.KeyVault, powershell-yaml.
Run
./New-EntraSecurityGroups.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Set-EntraGroupRoleAssignments.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
Azure CLI
When to use: Run the task from a host that has the Azure CLI and not the Az PowerShell modules. The script is PowerShell 7 that calls
az; it readsinfrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/02-azure-foundation/phase-03-rbac-permissions/task-02-assign-rbac-roles/azurecli/New-EntraSecurityGroups.azcli.ps1 | Creates the Microsoft Entra security groups that identity.entra.groups of infrastructure.yml lists, with the Azure CLI. Supports -WhatIf. |
scripts/deploy/02-azure-foundation/phase-03-rbac-permissions/task-02-assign-rbac-roles/azurecli/Set-EntraGroupRoleAssignments.azcli.ps1 | Assigns the Azure roles that identity.entra.groups of infrastructure.yml gives each Microsoft Entra group, at the scope it names, with the Azure CLI. Supports -WhatIf. |
Requires: PowerShell 7 and the Azure CLI, signed in with az login --tenant <azure.tenant_id>.
Azure side only. The first script adds no members. The second never removes a role assignment, and a role held at a higher scope does not count: it assigns the role at the scope the file names. Owner and User Access Administrator let the group grant access to others, so review the file before you run it. You need a role that can write role assignments at each scope, and permission to read groups.
Run
./New-EntraSecurityGroups.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./New-EntraSecurityGroups.azcli.ps1 -InfrastructureFile ./infrastructure.yml
./Set-EntraGroupRoleAssignments.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Set-EntraGroupRoleAssignments.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
Authorization failed | Insufficient permissions to assign roles | Requires Owner or User Access Administrator |
Role definition not found | Role name typo | Verify role name with Get-AzRoleDefinition |
Principal does not exist | SPN or user not found | Verify SPN was created in Task 01 |
Role assignment already exists | Role previously assigned | Safe to ignore — script handles idempotently |
Alternatives
The procedures in this task use the methods shown in the tabs above. The toolkit is PowerShell 7 only and has no Bash scripts. A few tasks that act on Azure also have an Azure CLI script written in PowerShell. The script status page of the toolkit lists which task has which script.
Navigation
| Previous | Up | Next |
|---|---|---|
| Task 01 — Create Deployment SPN | Phase 03 — RBAC Permissions | Phase 04 — Azure Management Infrastructure |
Version Control
- Created: 2026-01-15 by Azure Local Cloud
- Last Updated: 2026-03-02 by Azure Local Cloud
- Version: 2.0.0
- Tags: azure-local, phase-03, rbac, role-assignment
- Keywords: RBAC, role assignment, sp-azurelocal-deploy, Contributor, Azure Stack HCI Administrator
- Author: Azure Local Cloud
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |