Using KeyVault References to Read Key Vault Secrets

Microsoft Azure cloud hero

Azure KeyVault is the place to store secrets and cryptographic keys for our applications and services. I’m sure you already know that Key Vault can safeguard keys in hardware security modules and audit access to all the secrets inside, but if not, you can read about the basic features in the Key Vault documentation.

In this post, I want to look at a relatively new feature in Azure App Services that will allow you to consume Key Vault secrets from any application, service, or function running in App Services. This feature is currently in preview but is expected to be generally available in only a few weeks. I believe this new feature, called Key Vault references, is the best approach for using Key Vault. To understand why, let’s take a quick look at how we traditionally use Key Vault from an App Service.

Key Vault’s REST API

Key Vault, like every service inside of Azure, exposes an API. You can use the API to retrieve a secret from Key Vault. All you need to do is send an HTTPS request with the appropriate authorization token generated from an account with read access to the vault. The API allows us to use KeyVault from any platform and any language with quite a bit of flexibility. Applications can dynamically load secrets and connection strings from Key Vault and keep the settings cached.

Microsoft provides wrappers around the low-level HTTP API for many platforms and languages. When building apps or services with ASP.NET Core for example, you can reference a NuGet package for a Key Vault configuration provider. The provider will load a complete set of secrets into the app’s native configuration settings.  The code is simple and looks like the following.


The downside is that ops teams and admins have a tough time seeing what keys an application is using with the API approach. The API calls hide the configuration keys inside of application code. To change a key a service is using, for example, someone needs to make changes in the code base and then re-build and re-deploy the service.

Using ARM Templates

Another approach to using Key Vault secrets is to deploy an App Service or Function App using ARM templates with Key Vault parameters inside. This approach does not require any API calls to Key Vault at runtime because the ARM deployment will read Key Vault secrets during a deployment operation and create genuine App Settings in the service with the values of those secrets. The ARM template will look something like the following excerpt, which wants to create an App Setting named TheClientSecret with a secret value from Key Vault.

The template needs to specify the Key Vault secret to use by first adding to the parameters of the template.

And finally, by specifying the vault ID and secret name to substitute into the App Setting at deployment.

The ARM template approach makes it easy for ops teams to change settings because the settings are available in the service’s App Settings. However, it might not be obvious to the person making the changes that the next deployment will overwrite the change. When using an ARM template, the proper way to change a secret is to make the change in Key Vault and then redeploy the template.

Key Vault References

The Key Vault references feature of Azure App Services gives us the security benefits of using Azure Key Vault while keeping configuration settings outside of application code and deployment templates, which gives the ops team more flexibility and control. Let’s take the example where we have an application that wants to display a secret message. We’ll store the message in a new Azure Key Vault secret with the name SecretMessage.
A Key Vault Secret
  In the Application Settings for the app, we can specify a Key Vault reference using the syntax @Microsoft.KeyVault(SecretUri= You can find the full URI for a secret including the version number by drilling into the properties for the secret in the Azure portal.
Application Setting using Key Vault Reference
  All the application needs to do is ask for the configuration value "SecretMessage" with the same code it uses for any other App Setting. There are no code changes required. App services will place the value into the configuration system when the App Service starts. Note this means you’ll need to restart the app if you change the setting in Key Vault. However, for the ops team it is clear what configuration settings the application requires and where the settings come from. There is no more configuration hidden in application code or ARM templates.You will need to give the App Service a managed identity and grant the identity read access to the secrets it needs.


Although Key Vault references have been in preview for many months, my sources tell me the feature is stable and will be available by the end of September. Key Vault references are flexible while being transparent and secure, and I believe they should be everyone’s first choice for configuring secrets into an App Service.