Azure managed identities explained: connect services without secrets

A managed identity is an identity Azure creates for one of your resources and looks after for you: no password, no key, nothing to put in configuration or rotate. Your code asks the platform for a token, Entra ID issues it, and the service you call checks the identity's Azure roles like anyone else's. It's the right way for a Function, web app, container, VM, Logic App or pipeline to reach a storage account, a vault, a database or a model. This guide covers the decision everyone has to make first, the code, the laptop problem, a deployment pattern that doesn't break on day one, and the errors.

System-assigned or user-assigned

Why user-assigned wins by default: several resources that do the same job share one identity and one set of role assignments; the identity and its roles can exist before the resource that uses it, so a Bicep deployment doesn't fail because the creator can't assign roles; deleting and recreating a resource doesn't orphan the roles; and creating many resources at once doesn't hit the directory's object-creation rate limit (each system-assigned identity is a new service principal, and deleted ones count against your quota for 30 days). A resource can have one system-assigned and several user-assigned identities at once, and choose which to use per call.

One security point: whoever can run code on a resource can use every identity assigned to it, and whoever can assign a user-assigned identity can give its permissions to any resource they control. Treat "can deploy to this app" and "Managed Identity Operator" as privileged roles.

The three steps

1. Create the identity (user-assigned shown):

   az identity create --name id-orders-api --resource-group rg-orders
   az identity show --name id-orders-api --resource-group rg-orders --query "{clientId:clientId, principalId:principalId}"
   az webapp identity assign --name app-orders-api --resource-group rg-orders \
     --identities /subscriptions/<sub>/resourceGroups/rg-orders/providers/Microsoft.ManagedIdentity/userAssignedIdentities/id-orders-api
   

   Two IDs matter: the principal (object) ID is what role assignments point at; the client ID is what your code passes to pick a user-assigned identity.

2. Give it a data-plane role on the target, at the narrowest scope that works. A control-plane role such as Contributor doesn't read data; see our 403 after assigning a role guide for the role per service.

   az role assignment create --role "Storage Blob Data Reader" \
     --assignee-object-id <principalId> --assignee-principal-type ServicePrincipal \
     --scope /subscriptions/<sub>/resourceGroups/rg-orders/providers/Microsoft.Storage/storageAccounts/storders
   

3. Use it in code. The Azure Identity library (Azure.Identity, azure-identity, @azure/identity) handles the token:

   var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions
   {
       ManagedIdentityClientId = "<client id of id-orders-api>" // omit for a system-assigned identity
   });
   var blobs = new BlobServiceClient(new Uri("https://storders.blob.core.windows.net"), credential);
   

   The Azure CLI can use the identity too, on a VM or a hosted pipeline agent: az login --identity (add --client-id for user-assigned). Some services call the identity for you: a Logic App connection, a Data Factory linked service, an App Service Key Vault reference.

A useful second use: a managed identity can be a federated credential on an app registration, so an app that must be an Entra application (for Graph permissions, say) still has no secret. There's a limit of 20 federated credentials per app.

On your laptop there is no managed identity

DefaultAzureCredential tries a chain of credentials in order: environment variables (a service principal), workload identity, managed identity, Visual Studio, VS Code, Azure CLI, Azure PowerShell, Azure Developer CLI, then an interactive browser if you allow it. In Azure the managed identity answers; on your machine it fails and the chain falls through to your az login. The same code runs in both places, provided your own account has the same data-plane role on the same resource. Test with that account, not with a subscription Owner, which hides planes problems.

Microsoft's advice for production is to replace DefaultAzureCredential with the specific credential once you know what the app uses (ManagedIdentityCredential), or set AZURE_TOKEN_CREDENTIALS=prod to restrict the chain: it's faster (no failed attempts), easier to debug, and immune to a stray AZURE_CLIENT_SECRET environment variable on the host changing who the app is. The chain also honours AZURE_USERNAME and AZURE_PASSWORD, a username-and-password flow that mandatory MFA has made unusable; remove them if they're set anywhere.

Deploy it with Bicep

The pattern that survives redeploys: a user-assigned identity, the role assignment named deterministically and with principalType set, and the app referencing the identity.

resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
  name: 'id-orders-api'
  location: location
}

// Storage Blob Data Reader, by ID so a rename of the role never breaks it
var blobReader = subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '2a2b9908-6ea1-4ae2-8e65-a410df84e7d1')

resource read 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, identity.properties.principalId, blobReader)
  scope: storage
  properties: {
    roleDefinitionId: blobReader
    principalId: identity.properties.principalId
    principalType: 'ServicePrincipal' // avoids the PrincipalNotFound replication race
  }
}

The guid(scope, principalId, roleDefinitionId) name changes if the principal changes, which is what you want: a role assignment's principal can't be updated, so a reused name with a new identity fails with RoleAssignmentUpdateNotPermitted. A system-assigned identity's principal ID changes every time the resource is recreated, which is the other reason user-assigned deploys more smoothly.

Tidy up the other way too: deleting an identity doesn't delete its role assignments, which linger as Identity not found and count against the subscription's assignment limit. Get-AzRoleAssignment | Where-Object ObjectType -eq "Unknown" | Remove-AzRoleAssignment clears them.

The errors

Sources

• What is managed identities for Azure resources?, Microsoft Learn
• Managed identity best practice recommendations, Microsoft Learn
• Credential chains in the Azure Identity library for .NET, Microsoft Learn (DefaultAzureCredential order and production guidance)
• Troubleshoot Azure-hosted application authentication, Microsoft Learn (the ManagedIdentityCredential errors)
• Troubleshoot Azure RBAC, Microsoft Learn (PrincipalNotFound, RoleAssignmentUpdateNotPermitted, identity not found)
• Sign in to Azure with a managed identity using Azure CLI, Microsoft Learn
• Known issues with managed identities, Microsoft Learn