Managed identities¶

Registry of all Azure managed identities used across HCS projects. Managed identities are preferred over service principals for any workload running on Azure infrastructure.

User-assigned vs. system-assigned¶

User-assigned managed identities are created as standalone Azure resources and can be assigned to one or more Azure resources. Prefer these — they survive resource recreation and can be shared across resources.

System-assigned managed identities are tied to a specific Azure resource and deleted when that resource is deleted. Use these only when a workload is strictly one resource with no sharing requirement.

How to register a new managed identity¶

Create the user-assigned managed identity:

az identity create `
    --name mi-hcs-<purpose>-<env> `
    --resource-group <rg-name> `
    --location eastus

Assign it to the Azure resource that will use it:

# Example: assign to an App Service
az webapp identity assign `
    --resource-group <rg-name> `
    --name <app-name> `
    --identities /subscriptions/be069ae1-fc96-4a07-9f8e-5994d83a817d/resourcegroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/mi-hcs-<purpose>-<env>

Grant the identity the minimum required role on the target resource(s).
If the identity needs Key Vault access, grant it Key Vault Secrets User on kv-hcs-vault-01.
Add it to the registry table below.
Commit: docs(identity): register managed identity mi-hcs-<purpose>-<env>

Naming convention: mi-hcs-<purpose>-<env> — e.g., mi-hcs-ado-agent-prd, mi-hcs-func-kv-dev

Registry¶

User-assigned¶

Name	Resource group	Purpose	Assigned to	Role assignments	Notes
(no user-assigned identities registered yet)

System-assigned¶

Resource name	Resource type	Purpose	Role assignments	Notes
(no system-assigned identities registered yet)

Managed identity access to Key Vault¶

When a managed identity needs to read secrets from kv-hcs-vault-01:

# Get the principal ID of the managed identity
$principalId = az identity show `
    --name mi-hcs-<purpose>-<env> `
    --resource-group <rg-name> `
    --query principalId `
    --output tsv

# Grant Key Vault Secrets User
az role assignment create `
    --assignee $principalId `
    --role "Key Vault Secrets User" `
    --scope "/subscriptions/be069ae1-fc96-4a07-9f8e-5994d83a817d/resourceGroups/<kv-rg>/providers/Microsoft.KeyVault/vaults/kv-hcs-vault-01"