Task 01: Create Azure Local Deployment SPN
DOCUMENT CATEGORY: Runbook
SCOPE: Service principal creation for Azure Local deployment automation
PURPOSE: Create a dedicated service principal for Azure Local cluster deployment
MASTER REFERENCE: Microsoft Learn - Service Principals
Status: Active Applies To: Phase 03 — RBAC Permissions Last Updated: 2026-03-02
Overview
Create a dedicated service principal (SPN) for Azure Local deployment automation. This SPN is used specifically for Azure Local cluster deployment operations and is separate from any CI/CD service principals.
This task requires Owner or User Access Administrator permissions at the subscription or tenant level. The deployment SPN cannot be used until RBAC is assigned in Task 02.
Service Principal Details
| Attribute | Value |
|---|---|
| Display Name | sp-azurelocal-deploy |
| Account Type | Single tenant |
| Purpose | Azure Local deployment automation |
| Secret Expiry | 12 months (recommended) |
Prerequisites
- Active Azure session with Owner or User Access Administrator role
- Phase 02: Verify Provider Registration completed
If the deployment SPN already exists in the target environment, the script detects existing SPNs and prompts before creating a new secret. Enter n if the existing secret in the platform Key Vault is still valid.
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.
azure.tenant_id the tenant the sign-in must belong to
azure.location the region of the identity
azure.subscription_id, azure.resource_group the place when the entry has none
tags tags for the identity (optional)
azure.automation_identity.type must be managed_identity
azure.automation_identity.name the name of the identity
azure.automation_identity.subscription_id the subscription that holds it (optional)
azure.automation_identity.resource_group the resource group that holds it (optional)
The Terraform route (src/terraform/modules/identity) also reads azure.automation_identity.resource_group_roles[] (registry 5.0.62, schema 5.6.28, optional): the roles of the automation identity at resource group scope, each with resource_group (a resource group of the Azure Local subscription) and roles (role names, for example Contributor). The subscription roles come from devops.authentication.roles.
Create Deployment Service Principal
- Azure Portal
- Orchestrated Script
- Azure CLI
1. Create App Registration
- Navigate to Microsoft Entra ID → App registrations
- Click + New registration
- Configure:
- Name:
sp-azurelocal-deploy - Supported account types: Accounts in this organizational directory only (Single tenant)
- Redirect URI: Leave blank
- Click Register
2. Record Application Details
After registration, note the following values from the Overview page:
| Value | Store In Key Vault As |
|---|---|
| Application (client) ID | sp-azurelocal-deploy-appid |
| Directory (tenant) ID | sp-azurelocal-deploy-tenantid |
3. Create Client Secret
- In the app registration, go to Certificates & secrets
- Click + New client secret
- Configure:
- Description:
Azure Local Deployment Automation - Expires: 12 months (recommended)
- Click Add
- Copy the secret value immediately — it is only shown once
The client secret value is only displayed once. Copy it immediately and store it securely. If you lose it, you must create a new secret.
4. Store Credentials in Key Vault
- Navigate to your platform Key Vault
- Go to Secrets → + Generate/Import
- Create the following secrets:
| Secret Name | Value |
|---|---|
sp-azurelocal-deploy-appid | Application (client) ID |
sp-azurelocal-deploy-secret | Client secret value |
sp-azurelocal-deploy-tenantid | Directory (tenant) ID |
Validation
- App registration created with name
sp-azurelocal-deploy - Application ID and Tenant ID recorded
- Client secret created and copied
- All credentials stored in Key Vault
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-01-create-azure-local-deployment-spn/powershell/New-AutomationManagedIdentity.ps1 | Creates the user-assigned managed identity that azure.automation_identity of infrastructure.yml names. Supports -WhatIf. |
Requires: PowerShell 7; modules Az.Resources.
Run
./New-AutomationManagedIdentity.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-01-create-azure-local-deployment-spn/azurecli/New-AutomationManagedIdentity.azcli.ps1 | Creates the user-assigned managed identity that azure.automation_identity of infrastructure.yml names, with the Azure CLI. Supports -WhatIf. |
Requires: PowerShell 7 and the Azure CLI, signed in with az login --tenant <azure.tenant_id>.
Works when azure.automation_identity.type is managed_identity; for service_principal it stops with exit code 2 (the CI/CD bootstrap creates that app registration). It creates only the identity and assigns no role. It reports the client id and the principal id (not secrets): record the client id in azure.automation_identity.client_id. You need Managed Identity Contributor (or Contributor) on the resource group.
Run
./New-AutomationManagedIdentity.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./New-AutomationManagedIdentity.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
Insufficient privileges | Missing Application Administrator role | Request Entra ID Application Administrator role |
Key Vault access denied | Missing Key Vault permissions | Assign Key Vault Secrets Officer role |
| SPN already exists prompt | SPN was previously created | Enter n to skip — use existing SPN |
| Secret not in Key Vault | Storage step was skipped | Re-run script or manually store secrets |
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 |
|---|---|---|
| Phase 02 — Verify Provider Registration | Phase 03 — RBAC Permissions | Task 02 — Assign RBAC Roles |
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, service-principal, entra-id
- Keywords: service principal, sp-azurelocal-deploy, app registration, deployment SPN
- Author: Azure Local Cloud
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |