Key Vault References in Azure App Service

App settings are a vital part of every app you'll build as a developer. See my post here for why we use them if you're not familiar. But how can we use them when deploying to Azure App Service?

Azure App Service let's you add application settings which are then included as environment variables to the underlying host. Your app can then interact with these environment variables to control functionally without having to update and redeploy your code.

A perfect example of this is a connection string for a database. Each environment would have its own database and so would have a separate connection string that can be stored in an app setting.

App settings in Azure App Service are encrypted at rest, so provide a good level of security by default. When storing sensitive values though, there are extra layers of security we can add.

For example, we may not want developers to know the values of those app settings (developers don't really need to know credentials or connection strings for the production environment for example). We may also only want to allow access to some settings for different teams or users.

Azure Key Vault

One option we have for storing configuration values is Azure Key Vault. This provides advanced encryption and storage of sensitive values, as well as storage of encryption keys and certificates.

The advanced security capabilities and relatively low cost make key vault a go-to in every application I develop in Azure.

For app service settings we can use secrets in key vault to store our sensitive configuration, and reference these directly in the app service. This then abstracts away the configuration values from our app, and allows us to provide access on a per-secret basis (either by grouping settings into different key vaults, or using RBAC permissions at the secret level).

Adding a key vault reference

Key vault references can be added with the following syntax:

@Microsoft.KeyVault(VaultName=my-vault-name;SecretName=my-secret-name)

This will reference the latest version of the my-secret-name secret in the my-vault-name key vault.

You can also specify a particular version of a secret by including a SecretVersion parameter, e.g.:

@Microsoft.KeyVault(VaultName=my-vault-name;SecretName=my-secret-name;SecretVersion=ec96f02080254f109c51a1f14cdb1931)

Note that you can also use the URI of the secret in the reference instead, for example:

@Microsoft.KeyVault(SecretUri=https://my-vault-name.vault.azure.net/secrets/my-secret-name/)

Or, if using a version:

@Microsoft.KeyVault(SecretUri=https://my-vault-name.vault.azure.net/secrets/my-secret-name/ec96f02080254f109c51a1f14cdb1931)

Ensuring your app has access to the key vault

For your app to use key vault references it needs to have access to the vault where the secrets are stored. For this, you can use a managed identity.

App services can use either a system-assigned or user-assigned managed identity to access the vault. I prefer to use a system-assigned identity for this purpose, unless you have multiple apps/services that all have the exact same access requirements, or you need to access the secrets at the time the app is created (where the system-assigned identity won't be available yet).

Create a system-assigned identity for your app

1. Go to the Identity blade for your app service in the Azure portal
2. Select On for the system-assigned managed identity for your app and save the changes

Grant the app's system-assigned identity access to the vault

The way to grant permission for your app will depend on the permissions model of your key vault (either RBAC or Access Policies).

Role-Based Access Control (RBAC)

1. Go to the Access Control (IAM) section of your key vault in the Azure portal
2. Select add a role (note that you will need permissions to be able to edit role assignments for the vault, e.g. the User Access Administrator or Owner roles)

3. Choose the Key Vault Secrets User role, and then select the system-assigned managed identity for the app

These steps will grant your app read-only access to all the secrets within the key vault. You can grant different roles if your app needs access to keys/certificates as well, or needs write access to any of the objects in the vault.

You can also grant your app access to specific secrets in the vault by following the same steps, but using the Access Control (IAM) section of the individual secrets. Note that this approach is generally okay for one or two secrets, but if you only want to grant access to some of the secrets in a vault then it is often easier to move these secrets into their own vault.

Access Policies

1. Go to the Access Policies sections of your key vault in the Azure portal
2. Select 'Create' to add an access policy

3. Select the Get and List permissions under secrets on the Permissions tab, and search for the system-assigned managed identity for your app on the Principal tab

These steps will grant your app read-only access to all the secrets within the key vault. Again, you can assign additional permissions to secrets/keys/certificates here if they are needed by your app.

Note that unlike with RBAC, there is no way to grant access only to specific secrets in the vault with access policies. For that reason it is recommended to use RBAC as the permissions model wherever possible. There are some scenarios though where you have to use access policies still.

Verifying key vault references

If your key vault reference is defined correctly and your app has the necessary permissions in the vault, you will see a green tick next to that environment variable on the app service. If there are any issues with the key vault reference, you will see a red X:

If you select the key vault reference, then it will give you more information about the error. Here's an example where it's trying to reference a secret that doesn't exist in the key vault:

If it's not obvious how to solve the issue, then check out my troubleshooting guide that talks through some of the key things to check (especially if you're using private networking).

Wrapping up

Hopefully this helps you get started with using key vault references in Azure app service - they really are an invaluable tool in keeping your configuration values secure.

If you'd like more information on why we use configuration values, check out my post here.

Thanks for reading.