Azure Key Vault is a service that allows you to encrypt authentication keys, storage account keys, data encryption keys, .pfx files, and passwords by using secured keys. If you would like to know more about Azure Key Vault, you may want to review: What is Azure Key Vault?
Azure Key Vault Certificates allows you to securely manage, store and tightly control your certificates.
Use the client library for Azure Key Vault Certificates in your Node.js application to:
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 Certificates client library using npm
npm install @azure/keyvault-certificates
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 certificate operations on the keyvault:
az keyvault set-policy --name <your-key-vault-name> --spn $AZURE_CLIENT_ID --certificate-permissions backup create delete deleteissuers get getissuers import list listissuers managecontacts manageissuers purge recover restore setissuers update
--certificate-permissions: Accepted values: backup, create, delete, deleteissuers, get, getissuers, import, list, listissuers, managecontacts, manageissuers, purge, recover, restore, setissuers, update
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 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 CertificateClient
:
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
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 { CertificateClient } = require("@azure/keyvault-certificates");
// DefaultAzureCredential expects the following three environment variables:
// * AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// * AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// * AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
// Lastly, create our certificates client and connect to the service
const client = new CertificateClient(url, credential);
The following sections provide code snippets that cover some of the common tasks using Azure Key Vault Certificates. The scenarios that are covered here consist of:
beginCreateCertificate
creates a certificate to be stored in the Azure Key Vault. If
a certificate with the same name already exists, a new version of the
certificate is created.
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const credential = new DefaultAzureCredential();
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new CertificateClient(url, credential);
const certificateName = "MyCertificateName";
async function main() {
// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
await client.beginCreateCertificate(certificateName, {
issuerName: "Self",
subject: "cn=MyCert"
});
}
main();
Besides the name of the certificate and the policy, you can also pass the following properties in a third argument with optional values:
enabled
: A boolean value that determines whether the certificate can be used or not.tags
: Any set of key-values that can be used to search and filter certificates.const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const credential = new DefaultAzureCredential();
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new CertificateClient(url, credential);
const certificateName = "MyCertificateName";
// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
const certificatePolicy = {
issuerName: "Self",
subject: "cn=MyCert"
};
const enabled = true;
const tags = {
myCustomTag: "myCustomTagsValue"
};
async function main() {
await client.beginCreateCertificate(certificateName, certificatePolicy, {
enabled,
tags
});
}
main();
Calling to beginCreateCertificate
with the same name will create a new version of
the same certificate, which will have the latest provided attributes.
Since Certificates take some time to get fully created, beginCreateCertificate
returns a poller object that keeps track of the underlying Long Running
Operation according to our guidelines:
https://azure.github.io/azure-sdk/typescript_design.html#ts-lro
The received poller will allow you to get the created certificate by calling to poller.getResult()
.
You can also wait until the deletion finishes, either by running individual service
calls until the certificate is created, or by waiting until the process is done:
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const credential = new DefaultAzureCredential();
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new CertificateClient(url, credential);
const certificateName = "MyCertificateName";
const certificatePolicy = {
issuerName: "Self",
subject: "cn=MyCert"
};
async function main() {
const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);
// You can use the pending certificate immediately:
const pendingCertificate = poller.getResult();
// Or you can wait until the certificate finishes being signed:
const keyVaultCertificate = await poller.pollUntilDone();
console.log(keyVaultCertificate);
}
main();
Another way to wait until the certificate is signed is to do individual calls, as follows:
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const { delay } = require("@azure/core-http");
const credential = new DefaultAzureCredential();
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new CertificateClient(url, credential);
const certificateName = "MyCertificateName";
const certificatePolicy = {
issuerName: "Self",
subject: "cn=MyCert"
};
async function main() {
const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);
while (!poller.isDone()) {
await poller.poll();
await delay(5000);
}
console.log(`The certificate ${certificateName} is fully created`);
}
main();
The simplest way to read certificates back from the vault is to get a
certificate by name. getCertificate
will retrieve the most recent
version of the certificate, along with the certificate's policy. You can
optionally get a different version of the certificate by calling
getCertificateVersion
if you specify the version. getCertificateVersion
does not return
the certificate's policy.
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const credential = new DefaultAzureCredential();
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new CertificateClient(url, credential);
const certificateName = "MyCertificateName";
async function main() {
const latestCertificate = await client.getCertificate(certificateName);
console.log(`Latest version of the certificate ${certificateName}: `, latestCertificate);
const specificCertificate = await client.getCertificateVersion(
certificateName,
latestCertificate.properties.version
);
console.log(
`The certificate ${certificateName} at the version ${latestCertificate.properties.version}: `,
specificCertificate
);
}
main();
listPropertiesOfCertificateVersions
will list versions of the given certificate.
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const credential = new DefaultAzureCredential();
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new CertificateClient(url, credential);
const certificateName = "MyCertificateName";
async function main() {
for await (let certificateProperties of client.listPropertiesOfCertificateVersions(certificateName)) {
console.log("version: ", certificateProperties.version);
}
}
main();
listPropertiesOfCertificates
will list all certificates in the Key Vault.
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const credential = new DefaultAzureCredential();
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new CertificateClient(url, credential);
async function main() {
for await (let certificateProperties of client.listPropertiesOfCertificates()) {
console.log("Certificate properties: ", certificateProperties);
}
}
main();
The certificate attributes can be updated to an existing certificate version with
updateCertificate
, as follows:
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const credential = new DefaultAzureCredential();
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new CertificateClient(url, credential);
const certificateName = "MyCertificateName";
async function main() {
const result = await client.getCertificate(certificateName);
await client.updateCertificateProperties(certificateName, result.properties.version, {
enabled: false,
tags: {
myCustomTag: "myCustomTagsValue"
}
});
}
main();
The certificate's policy can also be updated individually with updateCertificatePolicy
, as follows:
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const credential = new DefaultAzureCredential();
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new CertificateClient(url, credential);
const certificateName = "MyCertificateName";
async function main() {
const result = client.getCertificate(certificateName);
// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
await client.updateCertificatePolicy(certificateName, {
issuerName: "Self",
subject: "cn=MyCert"
});
}
main();
The beginDeleteCertificate
method sets a certificate up for deletion. This process will
happen in the background as soon as the necessary resources are available.
If soft-delete is enabled for the Key Vault, this operation will only label the certificate as a deleted certificate. A deleted certificate can't be updated. They can only be either read, recovered or purged.
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const credential = new DefaultAzureCredential();
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new CertificateClient(url, credential);
const certificateName = "MyCertificateName";
async function main() {
const poller = await client.beginDeleteCertificate(certificateName);
// You can use the deleted certificate immediately:
const deletedCertificate = poller.getResult();
// The certificate is being deleted. Only wait for it if you want to restore it or purge it.
await poller.pollUntilDone();
// You can also get the deleted certificate this way:
await client.getDeletedCertificate(certificateName);
// Deleted certificates can also be recovered or purged.
// recoverDeletedCertificate returns a poller, just like beginDeleteCertificate.
// const recoverPoller = await client.beginRecoverDeletedCertificate(certificateName);
// await recoverPoller.pollUntilDone();
// If a certificate is done and the KeyVault has soft-delete enabled, the certificate can be purged with:
await client.purgeDeletedCertificate(certificateName);
}
main();
Since the deletion of a certificate won't happen instantly, some time is needed
after the beginDeleteCertificate
method is called before the deleted certificate is
available to be read, recovered or purged.
Using the CertificateClient, you can retrieve and iterate through all of the certificates in a Certificate Vault, as well as through all of the deleted certificates and the versions of a specific certificate. The following API methods are available:
listPropertiesOfCertificates
will list all of your non-deleted certificates by their names, only
at their latest versions.listDeletedCertificates
will list all of your deleted certificates by their names,
only at their latest versions.listPropertiesOfCertificateVersions
will list all the versions of a certificate based on a certificate
name.Which can be used as follows:
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const credential = new DefaultAzureCredential();
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new CertificateClient(url, credential);
const certificateName = "MyCertificateName";
async function main() {
for await (let certificateProperties of client.listPropertiesOfCertificates()) {
console.log("Certificate properties: ", certificateProperties);
}
for await (let deletedCertificate of client.listDeletedCertificates()) {
console.log("Deleted certificate: ", deletedCertificate);
}
for await (let certificateProperties of client.listPropertiesOfCertificateVersions(certificateName)) {
console.log("Certificate properties: ", certificateProperties);
}
}
main();
All of these methods will return all of the available results at once. To
retrieve them by pages, add .byPage()
right after invoking the API method you
want to use, as follows:
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const credential = new DefaultAzureCredential();
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new CertificateClient(url, credential);
const certificateName = "MyCertificateName";
async function main() {
for await (let page of client.listPropertiesOfCertificates().byPage()) {
for (let certificateProperties of page) {
console.log("Certificate properties: ", certificateProperties);
}
}
for await (let page of client.listDeletedCertificates().byPage()) {
for (let deletedCertificate of page) {
console.log("Deleted certificate: ", deletedCertificate);
}
}
for await (let page of client.listPropertiesOfCertificateVersions(certificateName).byPage()) {
for (let certificateProperties of page) {
console.log("Properties of certificate: ", certificateProperties);
}
}
}
main();
You can set the following environment variable to get the debug logs when using this library.
export DEBUG=azure*
Please take a look at the samples directory for detailed examples on how to use this library.
To run our tests, first install the dependencies (with npm install
or rush install
),
then run the unit tests with: npm run unit-test
.
Some of our tests aim to reproduce the behavior of our library against remotely available endpoints. These are executed using previously recorded HTTP request and responses.
You can read more about the tests of this project here.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the 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 provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided 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 or contact opencode@microsoft.com with any additional questions or comments.
If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code
Generated using TypeDoc