Troubleshooting Managed Identity and Federation
Identify the effective principal
Azure compute
az webapp identity show --name "<app>" --resource-group "<rg>"
az functionapp identity show --name "<app>" --resource-group "<rg>"
az containerapp show --name "<app>" --resource-group "<rg>" --query identity
az vm identity show --name "<vm>" --resource-group "<rg>"User-assigned identity
az identity show --name "<identity>" --resource-group "<rg>" \
--query "{clientId:clientId, principalId:principalId, id:id}" -o jsonVerify RBAC
az role assignment list \
--assignee "<principal-id-or-client-id>" \
--all \
--query "[].{role:roleDefinitionName, scope:scope}" \
-o tableVerify federated credentials
Managed identity
az identity federated-credential list \
--identity-name "<identity>" \
--resource-group "<rg>" \
--query "[].{name:name, issuer:issuer, subject:subject, audiences:audiences}" \
-o tableApp registration
az ad app federated-credential list \
--id "<application-client-id>" \
--query "[].{name:name, issuer:issuer, subject:subject, audiences:audiences}" \
-o tableError map
| Error or symptom | Meaning | Action |
|---|---|---|
AADSTS700016 |
Application/client ID not found or wrong identity configured | Check service connection/app registration/client ID |
AADSTS7000215 |
Invalid/expired client secret | Migrate to WIF; do not create a new long-lived secret for new projects |
AADSTS70021 |
No matching federated identity record for assertion | Compare issuer, subject, and audience |
AADSTS700211 |
No matching issuer | Correct issuer in federated credential |
AADSTS700213 |
No matching subject | Correct subject; check renames |
AADSTS700223/AADSTS700238 |
Tenant restricts workload identity federation | Tenant admin must allow the workload identity type/issuer |
Azure 403 Forbidden |
Token valid but authorization missing/not propagated | Fix role assignment scope or wait/retry |
| SQL token-identified principal login failure | Database user/role missing | Create contained user and grant DB permissions |
| Cosmos forbidden with identity | Missing Cosmos native RBAC | Add SQL role assignment at correct scope |
Propagation-safe retry
Use retry only for the first post-deployment access check or startup dependency validation. Do not hide permanent authorization failures indefinitely.
Recommended initial policy:
- Initial delay: 5 seconds.
- Maximum delay: 60 seconds.
- Attempts: 5 to 8.
- Jitter: yes.
- Log: principal ID, role/scope expected, target resource, but never token values.
Logs to capture
- Credential type selected.
- Managed identity client ID if configured, not secrets or tokens.
- Target resource URI.
- Principal ID and expected role/scope.
- Correlation/request IDs from Azure SDK exceptions.
Checks before declaring success
- Identity token acquisition succeeds in the target runtime, not only locally.
- Target operation succeeds using identity.
- Credential-bearing connection string/key path fails after local auth is disabled.
- Role assignments are captured in IaC.
- No secret values are added to app settings, pipeline variables, or IaC outputs.