@azure/keyvault-secrets

Azure Key Vault is a service that allows you to encrypt authentication keys,storage account keys, data encryption keys, .pfx files, and passwords by usingkeys that are protected by hardware security modules (HSMs). If you would liketo know more about Azure Key Vault, you may want to review "What is Azure KeyVault?".

Azure Key Vault Secrets management allows you to securely store andtightly control access to tokens, passwords, certificates, API keys,and other secrets.

Use the client library for Azure Key Vault Secrets in your Node.js application to

• Get, set and delete a secret.
• Update a secret and it's attributes.
• Backup and restore a secret.
• Get, purge or recover a deleted secret.
• Get all the versions of a secret.
• Get all secrets.
• Get all deleted secrets.

Source code | Package (npm) | API Reference Documentation | Product documentation | Samples

Prerequisites: You must have an Azure subscription and a Key Vault resource to use this package.If you are using this package in a Node.js application, then use Node.js 6.x or higher.

To quickly create the needed Key Vault resources in Azure and to receive a connection string for them, you can deploy our sample template by clicking:

Install the Azure Key Vault Secret client library using npm:

npm install @azure/keyvault-secrets

Key Vault clients authenticate using the Azure Identity Library. Install it as well using npm

npm install @azure/identity

TypeScript users need to have Node type definitions installed:

npm install @types/node

You also need to enable compilerOptions.allowSyntheticDefaultImports in your tsconfig.json. Note that if you have enabled compilerOptions.esModuleInterop, allowSyntheticDefaultImports is enabled by default. See TypeScript's compiler options handbook for more information.

Use the Azure Cloud Shell snippet below to create/get client secret credentials.

• Create a service principal and configure its access to Azure resources:

  az ad sp create-for-rbac -n <your-application-name> --skip-assignment

  Output:

  { "appId": "generated-app-ID", "displayName": "dummy-app-name", "name": "http://dummy-app-name", "password": "random-password", "tenant": "tenant-ID" }

• Use the above returned credentials information to set AZURE_CLIENT_ID(appId), AZURE_CLIENT_SECRET(password) and AZURE_TENANT_ID(tenant) environment variables. The following example shows a way to do this in Bash:

   export AZURE_CLIENT_ID="generated-app-ID" export AZURE_CLIENT_SECRET="random-password" export AZURE_TENANT_ID="tenant-ID"

• Grant the above mentioned application authorization to perform secret operations on the keyvault:

  az keyvault set-policy --name <your-key-vault-name> --spn $AZURE_CLIENT_ID --secret-permissions backup delete get list purge recover restore set

  --secret-permissions:Accepted values: backup, delete, get, list, purge, recover, restore, set

• Use the above mentioned Key Vault name to retrieve details of your Vault which also contains your Key Vault URL:

  az keyvault show --name <your-key-vault-name>

• The Secret client is the primary interface to interact with the API methodsrelated to secrets in the Azure Key Vault API from a JavaScript application.Once initialized, it provides a basic set of methods that can be used tocreate, read, update and delete secrets.
• A Secret version is a version of a secret in the Key Vault.Each time a user assigns a value to a unique secret name, a new versionof that secret is created. Retrieving a secret by a name will always returnthe latest value assigned, unless a specific version is provided to thequery.
• Soft delete allows Key Vaults to support deletion and purging as twoseparate steps, so deleted secrets are not immediately lost. This only happens if the Key Vaulthas soft-deleteenabled.
• A Secret backup can be generated from any created secret. These backups come asbinary data, and can only be used to regenerate a previously deleted secret.

The Key Vault service relies on Azure Active Directory to authenticate requests to its APIs. The @azure/identity package provides a variety of credential types that your application can use to do this. The README for @azure/identity provides more details and samples to get you started.

Here's a quick example. First, import DefaultAzureCredential and SecretClient:

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

Once these are imported, we can next connect to the Key Vault service. To do this, we'll need to copy some settings from the Key Vault we are connecting to into our environment variables. Once they are in our environment, we can access them with the following code:

const { DefaultAzureCredential } = require("@azure/identity"); const { SecretClient } = require("@azure/keyvault-secrets"); const credential = new DefaultAzureCredential(); const vaultName = "<YOUR KEYVAULT NAME>"; const url = `https://${vaultName}.vault.azure.net`; const client = new SecretClient(url, credential);

The following sections provide code snippets that cover some of the commontasks using Azure Key Vault Secrets. The scenarios that are covered here consist of:

setSecret assigns a provided value to the specified secret name. If a secretwith the same name already exists, then a new version of the secret is created.

const { DefaultAzureCredential } = require("@azure/identity"); const { SecretClient } = require("@azure/keyvault-secrets"); const credential = new DefaultAzureCredential(); const vaultName = "<YOUR KEYVAULT NAME>"; const url = `https://${vaultName}.vault.azure.net`; const client = new SecretClient(url, credential); const secretName = "MySecretName"; async function main() { const result = await client.setSecret(secretName, "MySecretValue"); console.log("result: ", result); } main();

The simplest way to read secrets back from the vault is to get a secret byname. This will retrieve the most recent version of the secret. You canoptionally get a different version of the key if you specify it as part of theoptional parameters.

const { DefaultAzureCredential } = require("@azure/identity"); const { SecretClient } = require("@azure/keyvault-secrets"); const credential = new DefaultAzureCredential(); const vaultName = "<YOUR KEYVAULT NAME>"; const url = `https://${vaultName}.vault.azure.net`; const client = new SecretClient(url, credential); const secretName = "MySecretName"; async function main() { const latestSecret = await client.getSecret(secretName); console.log(`Latest version of the secret ${secretName}: `, latestSecret); const specificSecret = await client.getSecret(secretName, { version: latestSecret.version! }); console.log(`The secret ${secretName} at the version ${latestSecret.version!}: `, specificSecret); } main();

A secret can have more information than its name and its value. They can also includethe following attributes:

• tags: Any set of key-values that can be used to search and filter secrets.
• contentType: Any string that can be used to help the receiver of the secret understand how to use the secret value.
• enabled: A boolean value that determines whether the secret value can be read or not.
• notBefore: A given date after which the secret value can be retrieved.
• expires: A given date after which the secret value cannot be retrieved.

An object with these attributes can be sent as the third parameter of setSecret, right after the secret's name and value, as follows:

const { DefaultAzureCredential } = require("@azure/identity"); const { SecretClient } = require("@azure/keyvault-secrets"); const credential = new DefaultAzureCredential(); const vaultName = "<YOUR KEYVAULT NAME>"; const url = `https://${vaultName}.vault.azure.net`; const client = new SecretClient(url, credential); const secretName = "MySecretName"; async function main() { const result = await client.setSecret(secretName, "MySecretValue", { enabled: false }); } main();

This will create a new version of the same secret, which will have the latestprovided attributes.

Attributes can also be updated to an existing secret version with updateSecretAttributes, as follows:

const { DefaultAzureCredential } = require("@azure/identity"); const { SecretClient } = require("@azure/keyvault-secrets"); const credential = new DefaultAzureCredential(); const vaultName = "<YOUR KEYVAULT NAME>"; const url = `https://${vaultName}.vault.azure.net`; const client = new SecretClient(url, credential); const secretName = "MySecretName"; async function main() { const result = client.getSecret(secretName); await client.updateSecretAttributes(secretName, result.parameters.version, { enabled: false }); } main();

The beginDeleteSecret method starts the deletion of a Secret.This process will happen in the background as soon as the necessary resourcesare available.

const { DefaultAzureCredential } = require("@azure/identity"); const { SecretClient } = require("@azure/keyvault-secrets"); const credential = new DefaultAzureCredential(); const vaultName = "<YOUR KEYVAULT NAME>"; const url = `https://${vaultName}.vault.azure.net`; const client = new SecretClient(url, credential); const secretName = "MySecretName"; async function main() { await client.beginDeleteSecret(secretName); } main();

If soft-deleteis enabled for the Key Vault, this operation will only label the secret as adeleted secret. A deleted secret can't be updated. They can only be eitherread, recovered or purged.

const { DefaultAzureCredential } = require("@azure/identity"); const { SecretClient } = require("@azure/keyvault-secrets"); const credential = new DefaultAzureCredential(); const vaultName = "<YOUR KEYVAULT NAME>"; const url = `https://${vaultName}.vault.azure.net`; const client = new SecretClient(url, credential); const secretName = "MySecretName"; async function main() { const poller = await client.beginDeleteSecret(secretName) const deletedSecret = poller.getResult(); await poller.pollUntilDone(); await client.getDeletedSecret(secretName); const recoverPoller = await client.beginRecoverDeletedSecret(secretName); const recoverPoller.pollUntilDone(); await client.purgeDeletedSecret(secretName); } main();

Since Secrets take some time to get fully deleted, beginDeleteSecretreturns a Poller object that keeps track of the underlying Long RunningOperation according to our guidelines: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

The received poller will allow you to get the deleted secret by calling to poller.getResult().You can also wait until the deletion finishes, either by running individual servicecalls until the secret is deleted, or by waiting until the process is done:

const { DefaultAzureCredential } = require("@azure/identity"); const { SecretClient } = require("@azure/keyvault-secrets"); const credential = new DefaultAzureCredential(); const vaultName = "<YOUR KEYVAULT NAME>"; const url = `https://${vaultName}.vault.azure.net`; const client = new SecretClient(url, credential); const secretName = "MySecretName"; async function main() { const poller = await client.beginDeleteSecret(certificateName, certificatePolicy); let deletedSecret = poller.getResult(); await poller.poll(); console.log(poller.isDone()) deletedSecret = await poller.pollUntilDone(); console.log(deletedSecret); } main();

Using the SecretClient, you can retrieve and iterate through all of thesecrets in a Key Vault, as well as through all of the deleted secrets and theversions of a specific secret. The following API methods are available:

• listPropertiesOfSecrets will list all of your non-deleted secrets by their names, onlyat their latest versions.
• listDeletedSecrets will list all of your deleted secrets by their names,only at their latest versions.
• listPropertiesOfSecretVersions will list all the versions of a secret based on a secretname.

Which can be used as follows:

const { DefaultAzureCredential } = require("@azure/identity"); const { SecretClient } = require("@azure/keyvault-secrets"); const credential = new DefaultAzureCredential(); const vaultName = "<YOUR KEYVAULT NAME>"; const url = `https://${vaultName}.vault.azure.net`; const client = new SecretClient(url, credential); const secretName = "MySecretName"; async function main() { for await (let secretProperties of client.listPropertiesOfSecrets()) { console.log("Secret properties: ", secretProperties); } for await (let deletedSecret of client.listDeletedSecrets()) { console.log("Deleted secret: ", deletedSecret); } for await (let versionProperties of client.listPropertiesOfSecretVersions(secretName)) { console.log("Version properties: ", versionProperties); } } main();

All of these methods will return all of the available results at once. Toretrieve them by pages, add .byPage() right after invoking the API method youwant to use, as follows:

const { DefaultAzureCredential } = require("@azure/identity"); const { SecretClient } = require("@azure/keyvault-secrets"); const credential = new DefaultAzureCredential(); const vaultName = "<YOUR KEYVAULT NAME>"; const url = `https://${vaultName}.vault.azure.net`; const client = new SecretClient(url, credential); const secretName = "MySecretName"; async function main() { for await (let page of client.listPropertiesOfSecrets().byPage()) { for (let secretProperties of page) { console.log("Secret properties: ", secretProperties); } } for await (let page of client.listDeletedSecrets().byPage()) { for (let deletedSecret of page) { console.log("Deleted secret: ", deletedSecret); } } for await (let page of client.listPropertiesOfSecretVersions(secretName).byPage()) { for (let versionProperties of page) { console.log("Version properties: ", versionProperties); } } } main();

You can set the following environment variable to get the debug logs when using this library.

• Getting debug logs from the Key Vault Secrets SDK

export DEBUG=azure*

Please take a look at the samplesdirectory for detailed examples on how to use this library.

This project welcomes contributions and suggestions. Most contributions require you to agree to aContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant usthe rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to providea CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructionsprovided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct.For more information see the Code of Conduct FAQ orcontact opencode@microsoft.com with any additional questions or comments.

To run our tests, first install the dependencies (with npm install or rush install),then run the unit tests with: npm run unit-test.Our unit tests that target the behavior of our library against remotelyavailable endpoints are executed using previously recorded HTTP request andresponses.

Our integration tests will run against the live resources, which are determinedby the environment variables you provide. To run the integration tests, you canrun npm run integration-test, but make sure to provide the followingenvironment variables:

• AZURE_CLIENT_ID: The Client ID of your Azure account.
• AZURE_CLIENT_SECRET: The secret of your Azure account.
• AZURE_TENANT_ID: The Tenant ID of your Azure account.
• KEYVAULT_NAME: The name of the Key Vault you want to run the tests against.

WARNING:Integration tests will wipe all of the existing records in the targeted Key Vault.

ncG1vNJzZmiZqqq%2Fpr%2FDpJuom6Njr627wWeaqKqVY8SqusOorqxmnprBcHDWnploopGrrrSv0aKnrWeRr8KzsYyknLKukaq5tXnSnpqrnaSofHV6j2dnaKGembK5esetpKU%3D