TLDR; this article tells you why you should use Azure KeyVault to store and manage your secrets. Furthermore, it takes you all the way from local development to deployed on Azure (there are some differences in how to authenticate).
Azure Key Vault service is a service on Azure. It's a vault for your secrets that is encrypted. It solves the following problems:
Key Vault greatly reduces the chances that secrets may be accidentally leaked. There are also some additional benefits such as:
Secrets are separate from code Application developers no longer need to store security information in their application.
Access via URIs. Your applications can securely access the information they need by using URIs. These URIs allow the applications to retrieve specific versions of a secret.
No need for custom code. There is no need to write custom code to protect any of the secret information stored in Key Vault.
Monitoring, you can enable logging for your Vaults. You can configure the monitoring to:
Authentication via AAD, Azure active directory. Access to a Key Vault requires proper authentication and authorization. Authentication is done via Azure Active Directory.
Two ways to authorize. Authorization may be done via Azure role-based access control (Azure RBAC) or Key Vault access policy
Learn module Azure Key Vault. If you are completely new to Key Vault this is the best place to start. It takes you through explaining what Key Vault is, what to use it for. How to run something locally and how to deploy it to the cloud.
Quickstart Node.js This is a quickstartt that tells you how to work with secrets locally using Node.js. Great no-nonsense guide if you want to get started quickly.
Quickstart .NET A good quick start article showing how to create a Key Vault, use the .NET SDK and a service principal to authenticate.
KeyVault secrets. Good page that gives more ooof an understanding of how secrets are stored and what different permission levels exist among other things.
An important thing to realize when you want to read from the Key Vault within an app is that you need two different approaches depending on whether you are developing locally, or you have deployed the app to Azure. Why is that?
Let's explain the two different situations:
In development locally, you can be authenticated by using either Azure CLI and the az login
command. You can also use the Azure extension for VS Code and log in to Azure that way. What happens when you use either of those methods a credential is created on your machine. If you then use the official SDKs for your chosen platform, it will be able to authenticate using said credential.
When deployed on Azure. To reiterate, your code will most likely use an SDK for a supported language platform like .NET, Node.js, Python etc. Now, the SDK works for you in both when developing locally and deployed to Azure. It looks for credentials in many places like Az CLI and Visual Studio Code as we've already mentioned. However, once deployed, your app has access to neither of those two, so what does it do? It uses either environment variables (in App Settings for example) or it uses a so called managed identity to authenticate.
A managed identity is an impersonated identity you can create, either based on your service (a web app for example) or based on your user. What you do is to run a command, with either your user or your app as an argument, and back comes an identity and a secret. Here's an example of how you can create such an identity:
az webapp identity assign \
--resource-group "<resource group name>" \
--name "<your-unique-app-name>"
The above command returns a principal id that you will use as an argument in the next command. Once you have that identity created you need to assign it to the Key Vault using az keyvault set policy
:
az keyvault set-policy \
--secret-permissions get list \
--name "<your-unique-vault-name>" \
--object-id "<your-managed-identity-principalid>"
After that, you are ready to deploy your app to Azure and Azure Active Directory will authenticate your app and let you read from the Key Vault. This will all be shown in detail further down in the article, but now you know roughly what goes on.
The set-policy
command above not only associates your identity to the KeyVault, it also sets permissions. The argument --secret-permissions
contains a list of permissions that determines if you are able to read, write and manage secrets. Be as restrictive as you can who can do what with your Key Vault. In general, I reason like this when it comes to permissions:
Even though Key Vault helps you keep your secrets secure, it can still leak if you're not careful. You don't want to ever show the value of a secret on a web page or as part of an error. What you can do, is to have a safe behavior and ensure you do things such as:
Next, you will be taken through a series of steps where you will get to do the following:
To create a Key Vault, follow these steps:
az login
: az login
Select the user you want to login with.
az group create --name "<a name for resource group>" -l "EastUS"
az keyvault
command below: az keyvault create --name "<unique vault name>" --resource-group "keyvaultrg" --location "EastUS"
az keyvault secret set
: az keyvault secret set --vault-name "<unique vault name>" --name "mySecret" --value "abc123"
az keyvault secret show
: az keyvault secret show --vault-name="<unique vault name>" --name="mySecret"
There's SDKs for most major platforms. I'll be selecting the Node.js one for this demo. If you want the C# one you can select this language pivot:
az login
to ensure you are logged into Azure before proceeding. This will place a credential on your machine that the SDK will be able to pick up. az login
Select the Azure user that you want and then close the browser windows when asked.
npm init
command like so: npm init -y
npm install
command like so: npm install @azure/identity @azure/keyvault-secrets dotenv
dotenv
is not part of the SDK, it just let's us define some environment variables in a .env file and they get read to the env variables at initialization.
require('dotenv').config()
const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");
The first line ensures values from the .env file is read in. Given the upcoming code the content of .env file should look something like this:
VAULT_NAME=<key vault value, change me>
const secretName = "mySecret";
const keyVaultName = process.env["VAULT_NAME"];
const KVUri = "https://" + keyVaultName + ".vault.azure.net";
const credential = new DefaultAzureCredential();
const client = new SecretClient(KVUri, credential);
Note how the first two lines help construct the URL to the Key Vault given it's name, that it reads from VAULT_NAME
variable from our .env file. Next an instantiation of DefaultAzureCredential
is done. This instance will find the credential produced by az login
.
NOTE, we will need to change how this authentication happens once we deploy the app, but this works for now.
async function main() {
const retrievedSecret = await
client.getSecret(secretName);
console.log(retrievedSecret);
}
main();
"start": "node app.js"
npm start
This should give you a response looking something like this:
{
value: 'abc123',
name: 'mySecret',
properties: {
expiresOn: undefined,
createdOn: 2021-01-11T18:06:19.000Z,
updatedOn: 2021-01-11T18:06:19.000Z,
value: 'abc123',
id: 'https://<key vault name>.vault.azure.net/secrets/mySecret/<the secret>',
tags: { 'file-encoding': 'utf-8' },
vaultUrl: 'https://<key vault name>.vault.azure.net',
name: 'mySecret',
version: '<version>',
enabled: true,
recoverableDays: 90,
recoveryLevel: 'Recoverable+Purgeable'
}
You can see that you are able to successfully retrieve the value of your secret from the Key Vault and via code. Great, congrats.
As we are looking to deploy our app next, there are two things we need to do:
First, we will need to rebuild the app to Express. We do this just so we can interact with the app once deployed. We will display the value of the secret.
Don't do this in a real scenario, this is just to show that we have the proper access to the Key Vault.
npm install
npm install express
// this is not needed when deployed
// require('dotenv').config()
const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");
const app = require('express')();
const port = process.env.PORT || 3000;
const keyVaultName = process.env["VAULT_NAME"];
const KVUri = "https://" + keyVaultName + ".vault.azure.net";
const credential = new DefaultAzureCredential();
const client = new SecretClient(KVUri, credential);
const secretName = "mySecret";
app.get('/api/test', async(req, res) => {
const secret = await getSecret();
res.type('text');
res.send(secret);
});
async function getSecret() {
const retrievedSecret = await client.getSecret(secretName);
return retrievedSecret;
}
app.listen(port, () => {
console.log('server running');
})
What we have now is an express app with a route to /api/test
.
npm start
in the console. In the browser, navigate to http://localhost:3000/api/test
. It should show your secret as a JSON response.Because we plan to deploy this on Azure we need to make sure our app properly authenticates to Azure AD and that the Key Vault is ok with us reading from it. There's just a few steps to make that happen:
az appservice plan create
, like so: az appservice plan create \
--name "<unique service plan name for your subscription>" \
--sku FREE \
--location centralus \
--resource-group "<existing resource group>"
az webapp create
: az webapp create \
--plan "<unique service plan name for your subscription>" \
--runtime "node|10.6" \
--resource-group "<existing resource group>" \
--name "<unique app name>"
az webapp config appsettings set
: az webapp config appsettings set \
--resource-group "<existing resource group>" \
--name "<unique app name>" \
--settings 'VAULT_NAME=<your-unique-vault-name>' 'SCM_DO_BUILD_DURING_DEPLOYMENT=true'
The command above will ensure that process.env['VAULT_NAME']
will get populated once deployed. Also we no longer need the dotenv
lib to read from the .env file.
There are two things that needs doing. Creating the impersonated identity and assigning the identity to the Key Vault, and in doing so give the needed permissions to be able to read the secrets values.
az webapp identity assign
: az webapp identity assign \
--resource-group "<existing resource group>" \
--name "<unique app name>"
This will produce a JSON response that contains a field principalId. You will use that in the next command to associate an identity with a Key Vault, while adding a set of permissions.
az keyvault set-policy
: az keyvault set-policy \
--secret-permissions get list \
--name "<your-unique-vault-name>" \
--object-id "<principalId>"
Here we can see how we assign get
and list
as permissions for our identity, when it gets associated to the Key Vault. That's what's needed for the app to be able to read from the Key Vault.
We would have needed another set of permissions if we wanted to create or delete a secret for example.
To deploy the app, there's only one command we need to run. All that's needed is to compress the application and deploy it.
zip site.zip * -x node_modules/
az webapp deployment source config-zip \
--src site.zip \
--resource-group "<existing resource group>" \
--name "<unique app name>"
The above command will pack up all your files, node_modules excluded, into a file site.zip. Then the files are deployed. A few minutes later you will app your app up and running and your Key Vault showing the value of your secret mySecret if you navigate to deployedUrl/api/test
This article was somewhat long, but it did tell you why you should use the Azure Key Vault service. It also told you how to work with the Key Vault in local development and finally how you needed to change your source code and thereby prepare it for deployment. I hope it was helpful.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.