Skip to main content

Task 01: Create Azure Local Deployment SPN

Runbook Azure

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.

Elevated Admin Required

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​

AttributeValue
Display Namesp-azurelocal-deploy
Account TypeSingle tenant
PurposeAzure Local deployment automation
Secret Expiry12 months (recommended)

Prerequisites​

SPN May Already Exist

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​

1. Create App Registration​

  1. Navigate to Microsoft Entra ID → App registrations
  2. Click + New registration
  3. Configure:
  • Name: sp-azurelocal-deploy
  • Supported account types: Accounts in this organizational directory only (Single tenant)
  • Redirect URI: Leave blank
  1. Click Register

2. Record Application Details​

After registration, note the following values from the Overview page:

ValueStore In Key Vault As
Application (client) IDsp-azurelocal-deploy-appid
Directory (tenant) IDsp-azurelocal-deploy-tenantid

3. Create Client Secret​

  1. In the app registration, go to Certificates & secrets
  2. Click + New client secret
  3. Configure:
  • Description: Azure Local Deployment Automation
  • Expires: 12 months (recommended)
  1. Click Add
  2. Copy the secret value immediately — it is only shown once
Copy Secret Now

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​

  1. Navigate to your platform Key Vault
  2. Go to Secrets → + Generate/Import
  3. Create the following secrets:
Secret NameValue
sp-azurelocal-deploy-appidApplication (client) ID
sp-azurelocal-deploy-secretClient secret value
sp-azurelocal-deploy-tenantidDirectory (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

Troubleshooting​

IssueCauseSolution
Insufficient privilegesMissing Application Administrator roleRequest Entra ID Application Administrator role
Key Vault access deniedMissing Key Vault permissionsAssign Key Vault Secrets Officer role
SPN already exists promptSPN was previously createdEnter n to skip — use existing SPN
Secret not in Key VaultStorage step was skippedRe-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.

PreviousUpNext
Phase 02 — Verify Provider RegistrationPhase 03 — RBAC PermissionsTask 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​

VersionDateAuthorChanges
1.0.02025-03-25Azure Local CloudInitial release