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 — they have no credentials to manage or rotate.

---

User-assigned vs system-assigned

User-assigned — created as a standalone Azure resource, assignable to multiple resources. Preferred. Survives resource recreation and can be shared.

System-assigned — tied to a specific resource, deleted when that resource is deleted. Use only when a workload is strictly one resource with no sharing requirement.

Entra-ID-only tenants (no Azure subscription): neither form is possible — a managed identity is always an ARM resource and requires a subscription + resource group to be created in. Tenants with zero subscriptions get an SPN only; see the Entra-only note in service-principals.md. Backfill the MI once a subscription exists for that tenant.

---

Naming

Azure resource name: follows the variables and naming standard — mi-<org>-<env>-<purpose>

Examples: mi-hcs-prd-platform-automation, mi-tp-poc-arc-management

KV client ID entry — store the client ID in the appropriate vault using the KV standard pattern: <org>-<env-name>-<purpose>-mi-client-id

Examples: hcs-platform-platform-automation-mi-client-id, tp-tplabs-arc-management-mi-client-id

---

How to register a new managed identity

1. Create the user-assigned managed identity:

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

2. Store the client ID in the correct vault:

   $clientId = az identity show --name mi-<org>-<env>-<purpose> --resource-group <rg> --query clientId --output tsv
   az keyvault secret set --vault-name <vault> --name <org>-<env-name>-<purpose>-mi-client-id --value $clientId

3. Grant the identity the minimum required roles on its target resources
4. If it needs KV access, follow the KV access section below
5. Register it in the registry table below
6. Register the client ID secret in secret-inventory.md
7. Commit: docs(identity): register managed identity mi-<org>-<env>-<purpose>

---

Registry

User-assigned

All platform MIs have Owner at root management group and Global Admin (Entra direct assignment) in their respective tenant. Client IDs are stored in kv-hcs-vault-01 (non-sensitive resource IDs). Created 2026-05-12 via Invoke-TenantIdentitySetup.ps1 (AB#21).

Naming note: These follow the shorter mi-<short>-platform form from AB#21's acceptance criteria, not the full mi-<org>-<env>-<region>-<inst> standard in docs/standards/variables.md. Standards-alignment is a follow-on item.

Resource name	Tenant	Resource group	Client ID	Client ID KV secret (→ kv-hcs-vault-01)	Platform vault	Role assignments	Notes
mi-hcs-platform	hybridsolutions.cloud (d6fc73cf)	rg-hcs-kv-mgmt-eus-01	d7bbb90b-d197-44d5-b1a0-4847cb713cdc	hcs-platform-mi-hcs-platform-client-id	kv-hcs-vault-01	Owner @ root MG, Global Admin	—
mi-turnerlegacy-platform	turnerlegacy.org (57be591b)	rg-turnerlegacy-prod	53487ef5-3616-4449-9980-cacaa41e9b6e	hcs-platform-mi-turnerlegacy-platform-client-id	kv-turnerlegacy-prod	Owner @ root MG, Global Admin	—
mi-azlmgmt-platform	azurelocal.cloud (604d3138)	rg-platform-identity-eus-01	327b87d3-05e7-4ea6-8363-a3ca04196a7a	hcs-platform-mi-azlmgmt-platform-client-id	kv-azlmgmt-platform	Owner @ root MG, Global Admin	Vault created as part of AB#21
mi-tpdemos-platform	tierpointdemos.cloud (28217fed)	rg-azrlmgmt-azl-eus-01	4773d848-66b9-4940-9ca5-c724f224403b	hcs-platform-mi-tpdemos-platform-client-id	kv-demos-platform	Owner @ root MG, Global Admin	Vault in sub 5e04c7f2
mi-tppoc-platform	tierpointpoc.cloud (2e21f99f)	rg-platform-identity-eus-01	185f555d-a70b-4d62-8353-fccfe86a0274	hcs-platform-mi-tppoc-platform-client-id	kv-tppoc-platform	Owner @ root MG, Global Admin	Vault created as part of AB#21
mi-tplabs-platform	tierpointproductlabs.cloud (a9b67171)	rg-azrlmgmt-dev-eus-01	d247b73c-9863-4411-8dcd-d62f9667393b	hcs-platform-mi-tplabs-platform-client-id	kv-tplabs-platform	Owner @ root MG, Global Admin	Vault in sub 2caa0b8a
mi-phx-platform	projectphx.cloud (c9257f80)	rg-phx-security-eastus2-001	e20a3403-2ef5-4c6b-9c5a-66e28a323d56	hcs-platform-mi-phx-platform-client-id	kv-phx-platform	Owner @ root MG, Global Admin	Vault in sub 2f075d7e
mi-ptlmgmt-platform	prodtechlabmgmt.com (3321553e)	rg-ptlm-prodtech-eus-identity-mgmt	ac0d8316-dc16-4079-8f9f-bcdf5ea2de2e	hcs-platform-mi-ptlmgmt-platform-client-id	kv-ptlmgmt-platform	Owner @ root MG, Global Admin	Vault created as part of AB#21

System-assigned

Resource name	Resource type	Purpose	Role assignments	Notes
(none registered yet)

---

Key Vault access

Granting access to a single vault

$principalId = az identity show `
    --name mi-<org>-<env>-<purpose> `
    --resource-group <rg> `
    --query principalId --output tsv

az role assignment create `
    --assignee $principalId `
    --role "Key Vault Secrets User" `
    --scope "/subscriptions/$env:AZURE_SUBSCRIPTION_ID/resourceGroups/<kv-rg>/providers/Microsoft.KeyVault/vaults/<vault-name>"

Cross-vault access — platform managed identity

The platform managed identity (mi-hcs-prd-platform-automation) is granted access to external vaults so platform tooling can resolve secrets from any registered vault without per-SPN credentials.

Rules:

• Grant Key Vault Secrets User for read-only access to an external vault
• Grant Key Vault Secrets Officer only when platform tooling needs to write to that vault
• Every access grant must be listed in the registry table above under Vault access
• No pipeline or script should bypass the platform MI by using a SPN secret to access an external vault

To grant the platform MI access to an external vault:

$platformMIPrincipalId = az identity show `
    --name mi-hcs-prd-platform-automation `
    --resource-group <hcs-rg> `
    --query principalId --output tsv

az role assignment create `
    --assignee $platformMIPrincipalId `
    --role "Key Vault Secrets User" `
    --scope "/subscriptions/<target-sub-id>/resourceGroups/<target-rg>/providers/Microsoft.KeyVault/vaults/<target-vault>"

Document the grant in this registry before it is applied.