Setup Azure Key Vault

This article shows how to implement Azure Key Vault with Cosmos using a “password-less” connection from the Publisher and Editor App Services to the vault.

Install the Key Vault

Using the Azure Portal navigate to the Resource Group where Cosmos is installed and click the “Create” button near the top of the page.  Type “key vault” in the search bar.  When the item appears as shown below, click “Create.”

Next, give the vault a unique name, make sure the Region is the same as where your Cosmos is installed. Finally, check the pricing tier are correct, then click “Review + create”. On the next page, click the “Create” button when ready.

Configure Networking

If a VNet is installed, you will have to add the vault to it. With the Azure Portal navigate to your Resource Group and select the Key Vault. On the left edge of the page, select “Settings” then “Networking.”

On the next screen select “Allow public access from specific virtual networks and IP addresses.” Then select “Add a virtual network” followed by “Add existing virtual network.”

Now select the existing virtual network and the default subnet.  Below this dialog is an “Enable” button. Go ahead and select it.

Once the service points have been enabled click on the “Add” button.

There is one more setting to make. In order to add “secrets” to your Key Vault, you need to allow your computer to connect to it through the firewall.  Do this by clicking on “Add your client IP address.” In the input field type your public IP address.  If you do not know what it is, open this web page. Click “Apply” when ready.

Configure Permissions

Now you will have to grant three “Role Assignments.” One to allow you to create and manage secrets in the vault, and two that allow the Publisher and Editor to read secrets from the vault.

Give yourself access

On the left edge of the Key Vault page, select “Access Control (IAM).”  Then click on the “Add” button followed by selecting the “Add role assignment” choice.

The next screen provides a list of roles.  Look for the role “Key Vault Secrets Officer.” Select it then click the “Next” button near the bottom of the page.

Now you will see a role assignment dialog. Make sure “User, group, or service principal” is selected, then click “Select members.”

Now search for yourself on the “Select members” dialog.

Find and select yourself, then click on the “Select” button.  This will return you to the Role assignment page, where you will then click on the “Review + assign” button.

Give App Services Permissions

Return now to the Access control (IAM) page, click again on “Add” then “Add role assignment.”

From the role list, find and select the “Key Vault Secrets User” role, then click “Next.”

On the Role Assignment dialog, select “Managed identity” then click on “Select members.”

On the next dialog select “App Service” for managed identity and then find and select the Publisher and Editor app services.

Click the “Select” button to return to the Add role assignment page. At the bottom click “Review + assign,” then click it again.

Create a “Secret” In Key Vault

In this example we are going to create a SendGrid secret in Key Vault.  On the left edge menu of the Key Vault page expand “Objects” then click “Secrets.” Next click “Generate/Import.”

From the “Create a secret” dialog enter the secret name and input the actual secret into the “Secret value” input field. At the bottom of the dialog click “Create.”

Now you should see something like this:

Add Secret to App Services

Now we are going to enable the Editor App Service to read the secret in the Key Vault.  Using the Azure Portal navigate to the Resource Group where Cosmos is installed, then select the “Editor” App Service. Expand “Settings” and select “Environment variables.”

Find the variable and click to edit.  In our example, we are going to have the Send Grid key come from the Key Vault.

Insert the following code in the “Value” field of the environment variable--but change the VaultName and SecretName to match your vault and secret.

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

In our present example, the entry would look like this:

Click the “Apply” button twice near the bottom of the page, then click “Confirm.”  At first there will be a blue information symbol notifying you that the value is coming from Azure Key Vault.  Wait a minute or two then refresh the environment variables list.

If the app service was able to read the secret, the icon will change to a green check mark.

Now repeat this procedure if the secret will be used by the Publisher.