Trace a failed Key Vault reference through identity, secret permissions, network access, and refresh behavior without printing the secret.
0 reputation · 1d ago
A Key Vault reference can look correct in App Service while the application still receives an unresolved reference or cannot start. The fastest way to investigate is to separate four checks: the identity making the request, its permission to read the secret, the network path to the vault, and the version App Service has cached.
This guide covers App Service application settings that use Key Vault references. An application calling the Key Vault SDK directly has its own credential selection and retry behavior. The steps below are a documentation-based diagnostic workflow, not a claim that a particular production environment has been tested.
App Service uses the app’s system-assigned managed identity by default. If keyVaultReferenceIdentity is configured, it uses the specified user-assigned identity for reference operations instead. Your own Azure CLI login is a separate identity: successfully reading a secret from your laptop does not prove the app can read it.
az webapp identity show --resource-group YOUR_RESOURCE_GROUP --name YOUR_APP
az webapp show --resource-group YOUR_RESOURCE_GROUP --name YOUR_APP --query '{referenceIdentity:keyVaultReferenceIdentity,identity:identity.type}'These commands inspect configuration; they do not print secret values. Record the principal ID of the identity actually used, and repeat the check for a deployment slot if the failure occurs only in that slot. Do not assume the production app and slot share the same identity or settings.
A role that can view or configure a vault is not automatically a role that can read secret values. First identify the vault’s authorization model. For Azure RBAC, Microsoft documents Key Vault Secrets User as the role for resolving references. For the vault access-policy model, the managed identity needs the Get secret permission.
Review the assignment scope and the principal it targets. A similarly named identity is not sufficient. Check that the reference points to the intended vault, secret name, and optional version. Also check that the selected secret version is enabled. Avoid broad Owner or Administrator assignments as a shortcut: they make the investigation harder and expand access unnecessarily.
Correct IAM permissions do not bypass a vault firewall. A network-restricted vault must accept traffic from the virtual network used by the application. For private endpoints, verify VNet integration, private DNS resolution, and routing together. Microsoft’s reference guidance says Linux apps connecting to private endpoints need explicit routing of all traffic through the virtual network, with the documented exception for Functions on the Flex Consumption plan.
A useful nuance: the vault audit log can show a failed SecretGet with status 403 from a public outbound address, followed by a successful request from a private address. Microsoft documents this sequence as expected in the relevant network configuration. Diagnose the final result and correlated events rather than treating one failed event as conclusive.
| Observation | Next check |
|---|---|
| The identity has no secret-read role | Review the authorization model, principal ID, and assignment scope. |
| Permissions look correct; requests still fail | Check VNet integration, DNS, vault network rules, and effective routes. |
| Public 403 followed by private success | Correlate the complete request sequence and application behavior. |
| The app still uses the old value after rotation | Check version pinning and the reference refresh interval. |
A versionless reference follows the latest secret version, but App Service caches resolved references and refetches them every 24 hours. A configuration change triggers an app restart and refetch. Microsoft also documents a management API endpoint for an authenticated reference refresh. Treat both approaches as operational changes: understand the restart or refresh impact before using them on a busy application.
If the reference names an explicit secret version, creating a newer version does not change the reference. Decide whether deliberate version pinning or automatic rotation suits your release process, and document the rollback step. Keep environment-specific references as slot settings where appropriate so a slot swap does not mix environments.
Share the hosting plan and operating system, whether this is a slot, system-assigned or user-assigned identity, the vault authorization model, whether a private endpoint is involved, and the error category with timestamps. Redact subscription identifiers if necessary. Never post a secret value, token, connection string, or unredacted application-settings export.
Use the Azure forum for a follow-up, or read the existing Logic Apps managed identity guide for another service-specific identity scenario.
Reviewed against Microsoft documentation on 11 September 2026. Platform behavior can change; check the current documentation before applying configuration changes.
A thoughtful contribution can make all the difference. Be the first to share one.