Quickstart: Azure Key Vault client library for Node.js (v4)

  • 5 minutes to read

Get started with the Azure Key Vault client library for Node.js. Follow the steps below to install the package and try out example code for basic tasks.

Azure Key Vault helps safeguard cryptographic keys and secrets used by cloud applications and services. Use the Key Vault client library for Node.js to:

  • Increase security and control over keys and passwords.
  • Create and import encryption keys in minutes.
  • Reduce latency with cloud scale and global redundancy.
  • Simplify and automate tasks for SSL/TLS certificates.
  • Use FIPS 140-2 Level 2 validated HSMs.

API reference documentation | Library source code | Package (npm)

Prerequisites

This quickstart assumes you are running Azure CLI in a Linux terminal window.

Setting up

Install the package

From the console window, install the Azure Key Vault secrets library for Node.js.

npm install @azure/keyvault-secrets

For this quickstart, you will need to install the azure.identity package as well:

npm install @azure/identity

Create a resource group and key vault

This quickstart uses a pre-created Azure key vault. You can create a key vault by following the steps in the Azure CLI quickstart, Azure PowerShell quickstart, or Azure portal quickstart. Alternatively, you can simply run the Azure CLI commands below.

Important

Each key vault must have a unique name. Replace with the name of your key vault in the following examples.

az group create --name "myResourceGroup" -l "EastUS"

az keyvault create --name <your-unique-keyvault-name> -g "myResourceGroup"

Create a service principal

The simplest way to authenticate an cloud-based application is with a managed identity; see Use an App Service managed identity to access Azure Key Vault for details. For the sake of simplicity however, this quickstarts creates a console application. Authenticating a desktop application with Azure requires the use of a service principal and an access control policy.

Create a service principle using the Azure CLI az ad sp create-for-rbac command:

az ad sp create-for-rbac -n "http://mySP" --sdk-auth

This operation will return a series of key / value pairs.

{
  "clientId": "7da18cae-779c-41fc-992e-0527854c6583",
  "clientSecret": "b421b443-1669-4cd7-b5b1-394d5c945002",
  "subscriptionId": "443e30da-feca-47c4-b68f-1636b75e16b3",
  "tenantId": "35ad10f1-7799-4766-9acf-f2d946161b77",
  "activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
  "resourceManagerEndpointUrl": "https://management.azure.com/",
  "activeDirectoryGraphResourceId": "https://graph.windows.net/",
  "sqlManagementEndpointUrl": "https://management.core.windows.net:8443/",
  "galleryEndpointUrl": "https://gallery.azure.com/",
  "managementEndpointUrl": "https://management.core.windows.net/"
}

Take note of the clientId and clientSecret, as we will use them in the Set environmental variable step below.

Give the service principal access to your key vault

Create an access policy for your key vault that grants permission to your service principal by passing the clientId to the az keyvault set-policy command. Give the service principal get, list, and set permissions for both keys and secrets.

az keyvault set-policy -n <your-unique-keyvault-name> --spn <clientId-of-your-service-principal> --secret-permissions delete get list set --key-permissions create decrypt delete encrypt get list unwrapKey wrapKey

Set environmental variables

The DefaultAzureCredential method in our application relies on three environmental variables: AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID. Set these variables to the clientId, clientSecret, and tenantId values you noted in the Create a service principal step using the export VARNAME=VALUE format. (This only sets the variables for your current shell and processes created from the shell; to permanently add these variables to your environment, edit your /etc/environment file.)

You will also need to save your key vault name as an environment variable called KEY_VAULT_NAME.

export AZURE_CLIENT_ID=<your-clientID>

export AZURE_CLIENT_SECRET=<your-clientSecret>

export AZURE_TENANT_ID=<your-tenantId>

export KEY_VAULT_NAME=<your-key-vault-name>

Object model

The Azure Key Vault client library for Node.js allows you to manage keys and related assets such as certificates and secrets. The code samples below will show you how to create a client, set a secret, retrieve a secret, and delete a secret.

The entire console app is available at https://github.com/Azure-Samples/key-vault-dotnet-core-quickstart/tree/master/key-vault-console-app.

Code examples

Add directives

Add the following directives to the top of your code:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

Authenticate and create a client

Authenticating to your key vault and creating a key vault client depends on the environmental variables from the Set environmental variables step above, and the SecretClient constructor.

The name of your key vault is expanded to the key vault URI, in the format https://<your-key-vault-name>.vault.azure.net.

const keyVaultName = process.env["KEY_VAULT_NAME"];
const KVUri = "https://" + keyVaultName + ".vault.azure.net";

const credential = new DefaultAzureCredential();
const client = new SecretClient(KVUri, credential);

Save a secret

Now that your application is authenticated, you can put a secret into your keyvault using the client.setSecret method This requires a name for the secret -- we're using "mySecret" in this sample.

await client.setSecret(secretName, secretValue);

You can verify that the secret has been set with the az keyvault secret show command:

az keyvault secret show --vault-name <your-unique-keyvault-name> --name mySecret

Retrieve a secret

You can now retrieve the previously set value with the client.getSecret method.

const retrievedSecret = await client.getSecret(secretName);

Your secret is now saved as retrievedSecret.value.

Delete a secret

Finally, let's delete the secret from your key vault with the client.beginDeleteSecret method.

await client.beginDeleteSecret(secretName)

You can verify that the secret is gone with the az keyvault secret show command:

az keyvault secret show --vault-name <your-unique-keyvault-name> --name mySecret

Clean up resources

When no longer needed, you can use the Azure CLI or Azure PowerShell to remove your key vault and the corresponding resource group.

az group delete -g "myResourceGroup"

Remove-AzResourceGroup -Name "myResourceGroup"

Sample code

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const readline = require('readline');

function askQuestion(query) {
    const rl = readline.createInterface({
        input: process.stdin,
        output: process.stdout,
    });

    return new Promise(resolve => rl.question(query, ans => {
        rl.close();
        resolve(ans);
    }))
}

async function main() {

  const keyVaultName = process.env["KEY_VAULT_NAME"];
  const KVUri = "https://" + keyVaultName + ".vault.azure.net";

  const credential = new DefaultAzureCredential();
  const client = new SecretClient(KVUri, credential);

  const secretName = "mySecret";
  var secretValue = await askQuestion("Input the value of your secret > ");

  console.log("Creating a secret in " + keyVaultName + " called '" + secretName + "' with the value '" + secretValue + "` ...");
  await client.setSecret(secretName, secretValue);

  console.log("Done.");

  console.log("Forgetting your secret.");
  secretValue = "";
  console.log("Your secret is '" + secretValue + "'.");

  console.log("Retrieving your secret from " + keyVaultName + ".");

  const retrievedSecret = await client.getSecret(secretName);

  console.log("Your secret is '" + retrievedSecret.value + "'.");
  console.log("Deleting your secret from " + keyVaultName + " ...");

  await client.beginDeleteSecret(secretName);

  console.log("Done.");

}

main()

Next steps

In this quickstart you created a key vault, stored a secret, and retrieved that secret. To learn more about Key Vault and how to integrate it with your applications, continue on to the articles below.