@azure/keyvault-certificates v4.7.0

Azure Key Vault Certificates client library for JS

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 keys that are protected by hardware security modules (HSMs). 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:

• Get, set and delete a certificate.
• Update a certificate, it's attributes, issuer, policy, operation and contacts.
• Backup and restore a certificate.
• Get, purge or recover a deleted certificate.
• Get all the versions of a certificate.
• Get all certificates.
• Get all deleted certificates.

Please Note: This is a preview version of the Key Vault Certificates library.

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

Getting started

Install the package

Install the Azure Key Vault Certificates client library using npm

npm install @azure/keyvault-certificates

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.

Configure Typescript

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.

Configuring your Key Vault

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 delete get list create deleteissuers 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>

Key concepts

• The Certificates client is the primary interface to interact with the API methods related to certificates in the Azure Key Vault API from a JavaScript application. Once initialized, it provides a basic set of methods that can be used to create, read, update and delete certificates.
• A Certificate version is a version of a certificate in the Key Vault. Each time a user assigns a value to a unique certificate name, a new version of that certificate is created. Retrieving a certificate by a name will always return the latest value assigned, unless a specific version is provided to the query.
• Soft delete allows Key Vaults to support deletion and purging as two separate steps, so deleted certificates are not immediately lost. This only happens if the Key Vault has soft-delete enabled.
• A Certificate backup can be generated from any created certificate. These backups come as binary data, and can only be used to regenerate a previously deleted certificate.

Authenticating the client

To use the key vault from TypeScript/JavaScript, you need to first authenticate with the key vault service. To authenticate, first we import the identity and CertificatesClient, which will connect to the key vault.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificatesClient } from "@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:

// 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 CertificatesClient(url, credential);

Examples

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:

• Creating and setting a certificate.
• Getting a certificate.
• Certificate attributes.
• Updating a certificate.
• Deleting a certificate.
• Iterating lists of certificates.

Creating and setting a certificate

setCertificate 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 certificateName = "MyCertificateName";
const result = await client.createCertificate(certificateName, {
  issuerParameters: { name: "Self" },
});

Besides the name of the certificate, you can also pass the following attributes:

• certificatePolicy: The policy of the certificate.
• 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 certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerParameters: { name: "Self" }
}
const enabled = true;
const tags = {
  myCustomTag: "myCustomTagsValue"
};
const result = await client.createCertificate(
  certificateName,
  certificatePolicy,
  enabled,
  tags
);

Calling to createCertificate with the same name will create a new version of the same certificate, which will have the latest provided attributes.

Get a certificate

The simplest way to read certificates back from the vault is to get a certificate by name. getCertificateWithPolicy 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 getCertificate if you specify the version. getCertificate does not return the certificate's policy.

const latestCertificate = await client.getCertificateWithPolicy(certificateName);
console.log(`Latest version of the certificate ${certificateName}: `, getResult);
const specificCertificate = await client.getCertificate(certificateName, latestCertificate.version!);
console.log(`The certificate ${certificateName} at the version ${latestCertificate.version!}: `, getResult);

List all versions of a certificate

listCertificateVersions will list versions of the given certificate.

for await (let certificate of client.listCertificateVersions(certificateName)) {
  console.log("version: ", certificate.version);
}

List all certificates

listCertificates will list all certificates in the Key Vault.

for await (let listedCertificate of client.listCertificates()) {
  console.log("certificate: ", listedCertificate);
}

Updating a certificate

The certificate attributes can be updated to an existing certificate version with updateCertificate, as follows:

const result = client.getCertificateWithPolicy(certificateName);
await client.updateCertificate(certificateName, result.version, {
  certificatePolicy: {
    issuerParameters: { name: "Self" }
  },
  certificateAttributes: {
    enabled: false
  },
  tags: {
    myCustomTag: "myCustomTagsValue"
  }
});

The certificate's policy can also be updated individually with updateCertificatePolicy, as follows:

const result = client.getCertificateWithPolicy(certificateName);
await client.updateCertificatePolicy(certificateName, {
  issuerParameters: { name: "Self" }
});

Deleting a certificate

The deleteCertificate method sets a certificate up for deletion. This process will happen in the background as soon as the necessary resources are available.

await client.deleteCertificate(certificateName);

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.

await client.deleteCertificate(certificateName);

// If soft-delete is enabled, we can eventually do:
await client.getDeletedCertificate(certificateName);
// Deleted certificates can also be recovered or purged:
await client.recoverDeletedCertificate(certificateName);
// await client.purgeDeletedCertificate(certificateName);

Since the deletion of a certificate won't happen instantly, some time is needed after the deleteCertificate method is called before the deleted certificate is available to be read, recovered or purged.

Troubleshooting

Enable logs

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

• Getting debug logs from the Key Vault Certificates SDK

export DEBUG=azure*

Next steps

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

Contributing

This project welcomes contributions and suggestions. Please read the contributing guidelines for detailed information about how to contribute and what to expect while contributing.

Testing

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 remotely available endpoints are executed using previously recorded HTTP request and responses.

Our integration tests will run against the live resources, which are determined by the environment variables you provide. To run the integration tests, you can run npm run integration-test, but make sure to provide the following environment 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.

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.