I rotated the custom domain on our identity provider in production last month. The new domain went into Azure Key Vault as a new version of the secret. My App Service kept its existing Key Vault reference, configured without a version so it would always pick up the latest. After the rotation, every authenticated request started failing. The token validation middleware was rejecting tokens because the issuer URL no longer matched.
The identity provider's dashboard showed the new domain. The Key Vault showed the new secret as the current version. App Service was still serving the previous value.
The Diagnosis
App Service caches Key Vault references. The cache refreshes every 24 hours, or whenever the app restarts. I had restarted the app. I forced a configuration refresh through the management API. I waited longer than 24 hours. The reference still resolved to a previous secret value, which contained the default issuer domain instead of the custom one I had rotated in.
The reference looked like this:
@Microsoft.KeyVault(SecretUri=https://my-vault.vault.azure.net/secrets/idp-domain)
That format is what Microsoft's official documentation currently shows for the no-version case. According to that documentation, omitting the version means App Service should resolve to the latest version of the secret. It wasn't.
I tried adding a trailing slash:
@Microsoft.KeyVault(SecretUri=https://my-vault.vault.azure.net/secrets/idp-domain/)
After the next refresh, the reference resolved to the current value. Authentication started working. The only difference was the slash.
The Documentation Contradiction
Microsoft's current App Service Key Vault references guide shows the no-version reference format without a trailing slash. The page was last updated in April. It explicitly says omitting the secret version means the app uses the latest version that exists in the key vault.
Community guidance from Microsoft MVP blogs going back several years has consistently included the slash. One author capitalizes the rule: the URI MUST end with the trailing slash when omitting the version. The same kind of older-version resolution surfaces in a Logic Apps GitHub issue where the resolver returned a prior version after a new one was created, with app restart and disabling the older version listed as workarounds.
The empirical guidance and the current official documentation disagree. My production observation lined up with the empirical guidance.
What to Actually Do
Always include the trailing slash on the no-version form. It costs nothing and removes a class of failure that is hard to diagnose because the symptom appears unrelated to secret resolution. Authentication fails, or a connection string points at a stale endpoint, or a feature flag references the wrong environment, and the Key Vault dashboard shows everything looking correct.
If a deployment is coupled to a specific secret value, pin the version in the reference URL. The versioned form is unambiguous and isn't subject to this resolver behavior:
@Microsoft.KeyVault(SecretUri=https://my-vault.vault.azure.net/secrets/idp-domain/abc123def456)
After rotating a secret that an unversioned reference depends on, force a refresh through the management API rather than waiting for the 24-hour cache interval, then verify the resolved value before walking away from the deployment.
Why This Matters
A Key Vault reference looks like a URL, but it isn't getting parsed by the same code path as a direct REST call to Key Vault. The App Service reference resolver is its own surface, with its own behavior, and the current public documentation does not capture all of it. When a configuration setting that is meant to mirror a secret diverges from the source of truth, the failure mode is silent and the diagnosis is slow.
In a system where a single secret value gates authentication for every authenticated request, an off-by-one-character resolver bug becomes a production outage. The fix was small. The lesson was that infrastructure references are code, and they have edge cases.
Identity and authentication are where production systems quietly fail when secret rotation goes wrong. Production cloud configuration is the kind of cloud platforms and modernization work I take on through Pelican Digital Pathways.