Bibliothèque cliente Azure Key Vault Certificates pour JavaScript - version 4.8.0

  • Article

Azure Key Vault est un service cloud qui fournit un stockage sécurisé et une gestion automatisée des certificats utilisés dans une application cloud. Plusieurs certificats et plusieurs versions du même certificat peuvent être conservés dans azure Key Vault. Chaque certificat du coffre est associé à une stratégie qui contrôle l’émission et la durée de vie du certificat, ainsi que les actions à entreprendre en tant que certificats qui arrivent à expiration.

Si vous souhaitez en savoir plus sur Azure Key Vault, consultez : Qu’est-ce qu’Azure Key Vault ?

Utilisez la bibliothèque cliente pour les certificats Azure Key Vault dans votre application Node.js pour :

  • Obtenir, définir et supprimer un certificat.
  • Mettez à jour un certificat, ses attributs, son émetteur, sa stratégie, son opération et ses contacts.
  • Sauvegardez et restaurez un certificat.
  • Obtenir, vider ou récupérer un certificat supprimé.
  • Obtenez toutes les versions d’un certificat.
  • Obtenez tous les certificats.
  • Obtenez tous les certificats supprimés.

Remarque : Ce package ne peut pas être utilisé dans le navigateur en raison des limitations du service Azure Key Vault. Reportez-vous à ce document pour obtenir des conseils.

Liens clés :

Prise en main

Environnements actuellement pris en charge

Prérequis

Installer le package

Installer la bibliothèque cliente Azure Key Vault Certificates à l’aide de npm

npm install @azure/keyvault-certificates

Installer la bibliothèque d’identités

Key Vault clients s’authentifient à l’aide de la bibliothèque d’identités Azure. Installez-le également à l’aide de npm

npm install @azure/identity

Configurer TypeScript

Les utilisateurs TypeScript doivent avoir installé des définitions de type de nœud :

npm install @types/node

Vous devez également activer compilerOptions.allowSyntheticDefaultImports dans votre tsconfig.json. Notez que si vous avez activé compilerOptions.esModuleInterop, allowSyntheticDefaultImports est activé par défaut. Pour plus d’informations, consultez le manuel des options du compilateur de TypeScript .

Authentification avec Azure Active Directory

Le service Key Vault s’appuie sur Azure Active Directory pour authentifier les demandes adressées à ses API. Le package @azure/identity fournit divers types d’informations d’identification que votre application peut utiliser à cette fin. Le FICHIER README pour @azure/identity fournit plus de détails et d’exemples pour vous aider à démarrer.

Pour interagir avec le service Azure Key Vault, vous devez créer un instance de la CertificateClient classe, une URL de coffre et un objet d’informations d’identification. Les exemples présentés dans ce document utilisent un objet d’informations d’identification nommé DefaultAzureCredential, qui convient à la plupart des scénarios, y compris aux environnements de développement et de production locaux. En outre, nous vous recommandons d’utiliser une identité managée pour l’authentification dans les environnements de production.

Vous trouverez plus d’informations sur les différentes méthodes d’authentification et leurs types d’informations d’identification correspondants dans la documentation Azure Identity.

Voici un exemple rapide. Tout d’abord, importez DefaultAzureCredential et CertificateClient:

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

Une fois ceux-ci importés, nous pouvons ensuite nous connecter au service de coffre de clés :

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

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);

Concepts clés

  • Le client Certificats est l’interface principale permettant d’interagir avec les méthodes d’API liées aux certificats dans l’API Azure Key Vault à partir d’une application JavaScript. Une fois initialisé, il fournit un ensemble de méthodes de base qui peuvent être utilisées pour créer, lire, mettre à jour et supprimer des certificats.
  • Une version de certificat est une version d’un certificat dans le Key Vault. Chaque fois qu’un utilisateur affecte une valeur à un nom de certificat unique, une nouvelle version de ce certificat est créée. La récupération d’un certificat par un nom retourne toujours la valeur la plus récente affectée, sauf si une version spécifique est fournie à la requête.
  • La suppression réversible permet aux coffres de clés de prendre en charge la suppression et le vidage en deux étapes distinctes, de sorte que les certificats supprimés ne sont pas immédiatement perdus. Cela se produit uniquement si la suppression réversible du Key Vault est activée.
  • Une sauvegarde de certificat peut être générée à partir de n’importe quel certificat créé. Ces sauvegardes sont fournies sous forme de données binaires et ne peuvent être utilisées que pour régénérer un certificat précédemment supprimé.

Spécification de la version de l’API du service Azure Key Vault

Par défaut, ce package utilise la dernière version du service Azure Key Vault qui est 7.1. La seule autre version prise en charge est 7.0. Vous pouvez modifier la version du service utilisée en définissant l’option serviceVersion dans le constructeur client, comme indiqué ci-dessous :

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`;

// Change the Azure Key Vault service API version being used via the `serviceVersion` option
const client = new CertificateClient(url, credential, {
  serviceVersion: "7.0",
});

Exemples

Les sections suivantes fournissent des extraits de code qui couvrent certaines des tâches courantes à l’aide d’Azure Key Vault Certificates. Les scénarios abordés ici sont les suivants :

Création et définition d’un certificat

beginCreateCertificatecrée un certificat à stocker dans azure Key Vault. Si un certificat portant le même nom existe déjà, une nouvelle version du certificat est créée.

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();

Outre le nom du certificat et la stratégie, vous pouvez également passer les propriétés suivantes dans un troisième argument avec des valeurs facultatives :

  • enabled: valeur booléenne qui détermine si le certificat peut être utilisé ou non.
  • tags: ensemble de clés-valeurs qui peuvent être utilisées pour rechercher et filtrer des certificats.
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();

L’appel à beginCreateCertificate avec le même nom crée une nouvelle version du même certificat, qui aura les derniers attributs fournis.

Étant donné que la création complète des certificats prend un certain temps, beginCreateCertificate retourne un objet poller qui effectue le suivi de l’opération de longue durée sous-jacente conformément à nos instructions : https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

L’polleur reçu vous permet d’obtenir le certificat créé en appelant à poller.getResult(). Vous pouvez également attendre la fin de la suppression, soit en exécutant des appels de service individuels jusqu’à ce que le certificat soit créé, soit en attendant que le processus soit terminé :

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();

Une autre façon d’attendre que le certificat soit signé consiste à effectuer des appels individuels, comme suit :

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
const { delay } = require("@azure/core-util");

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();

Obtention d’un certificat Key Vault

Le moyen le plus simple de lire des certificats à partir du coffre consiste à obtenir un certificat par nom. getCertificate récupère la version la plus récente du certificat, ainsi que la stratégie du certificat. Vous pouvez éventuellement obtenir une autre version du certificat en appelant getCertificateVersion si vous spécifiez la version. getCertificateVersion ne retourne pas la stratégie du certificat.

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();

Obtention des informations complètes d’un certificat

La conception d’Azure Key Vault fait des distinctions nettes entre les clés, les secrets et les certificats. Les fonctionnalités de certificats du service Key Vault ont été conçues en utilisant ses fonctionnalités Clés et Secrets. Évaluons la composition d’un certificat Key Vault :

Lorsqu’un certificat Key Vault est créé, une clé et un secret adressables sont également créés avec le même nom. La clé Key Vault permet d’exécuter des opérations sur les clés et le secret Key Vault permet de récupérer la valeur du certificat en tant que secret. Un certificat Key Vault contient également des métadonnées de certificat x509 publiques. Source : composition d’un certificat.

Sachant que la clé privée est stockée dans un Key Vault Secret, avec le certificat public inclus, nous pouvons la récupérer à l’aide du client Key Vault Secrets.

// Using the same credential object we used before,
// and the same keyVaultUrl,
// let's create a SecretClient
import { SecretClient } from "@azure/keyvault-secrets";

const secretClient = new SecretClient(keyVaultUrl, credential);

// Assuming you've already created a Key Vault certificate,
// and that certificateName contains the name of your certificate
const certificateSecret = await secretClient.getSecret(certificateName);

// Here we can find both the private key and the public certificate, in PKCS 12 format:
const PKCS12Certificate = certificateSecret.value!;

// You can write this into a file:
fs.writeFileSync("myCertificate.p12", PKCS12Certificate);

Notez que, par défaut, le type de contenu des certificats est PKCS 12. En spécifiant le type de contenu de votre certificat, vous pouvez le récupérer au format PEM. Avant de montrer comment créer des certificats PEM, nous allons d’abord explorer comment récupérer une clé secrète PEM à partir d’un certificat PKCS 12.

À l’aide de openssl, vous pouvez récupérer le certificat public au format PEM à l’aide de la commande suivante :

openssl pkcs12 -in myCertificate.p12 -out myCertificate.crt.pem -clcerts -nokeys

Vous pouvez également utiliser openssl pour récupérer la clé privée, comme suit :

openssl pkcs12 -in myCertificate.p12 -out myCertificate.key.pem -nocerts -nodes

Notez que dans les deux cas, openssl vous demande le mot de passe utilisé pour créer le certificat. L’exemple de code que nous avons utilisé jusqu’à présent n’a pas spécifié de mot de passe. Vous pouvez donc ajouter -passin 'pass:' à la fin de chaque commande.

Certificats au format PEM

Si vous souhaitez utiliser des certificats au format PEM, vous pouvez indiquer au service Key Vault d’Azure de créer et de gérer vos certificats au format PEM en fournissant la contentType propriété au moment de la création des certificats.

L’exemple suivant montre comment créer et récupérer les parties publiques et privées d’un certificat au format PEM à l’aide des clients Key Vault pour les certificats et les secrets :

// Creating the certificate
const certificateName = "MyCertificate";
const createPoller = await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
  contentType: "application/x-pem-file", // Here you specify you want to work with PEM certificates.
});
const keyVaultCertificate = await createPoller.pollUntilDone();

// Getting the PEM formatted private key and public certificate:
const certificateSecret = await secretClient.getSecret(certificateName);
const PEMPair = certificateSecret.value!;

console.log(PEMPair);

Gardez à l’esprit que votre certificat public se trouve dans le même objet blob de contenu que votre clé privée. Vous pouvez utiliser les en-têtes PEM pour les extraire en conséquence.

Répertorier tous les certificats

listPropertiesOfCertificatesrépertoriera tous les certificats dans le 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();

Mise à jour d’un certificat

Les attributs de certificat peuvent être mis à jour vers une version de certificat existante avec updateCertificate, comme suit :

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();

La stratégie du certificat peut également être mise à jour individuellement avec updateCertificatePolicy, comme suit :

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();

Suppression d’un certificat

La beginDeleteCertificate méthode définit un certificat pour suppression. Ce processus se produit en arrière-plan dès que les ressources nécessaires sont disponibles.

Si la suppression réversible est activée pour le Key Vault, cette opération étiquette uniquement le certificat en tant que certificat supprimé. Un certificat supprimé ne peut pas être mis à jour. Elles peuvent uniquement être lues, récupérées ou purgées.

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 Key Vault has soft-delete enabled, the certificate can be purged with:
  await client.purgeDeletedCertificate(certificateName);
}

main();

Étant donné que la suppression d’un certificat ne se produit pas instantanément, un certain temps est nécessaire après l’appel de la beginDeleteCertificate méthode avant que le certificat supprimé puisse être lu, récupéré ou vidé.

Itération des listes de certificats

À l’aide de CertificateClient, vous pouvez récupérer et itérer tous les certificats d’un coffre de certificats, ainsi que tous les certificats supprimés et les versions d’un certificat spécifique. Les méthodes d’API suivantes sont disponibles :

  • listPropertiesOfCertificates répertorie tous vos certificats non supprimés par leur nom, uniquement à leurs dernières versions.
  • listDeletedCertificates répertorie tous vos certificats supprimés en fonction de leur nom, uniquement dans leurs dernières versions.
  • listPropertiesOfCertificateVersions répertorie toutes les versions d’un certificat en fonction d’un nom de certificat.

Qui peut être utilisé comme suit :

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();

Toutes ces méthodes retournent tous les résultats disponibles en même temps. Pour les récupérer par pages, ajoutez .byPage() juste après l’appel de la méthode d’API que vous souhaitez utiliser, comme suit :

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();

Dépannage

L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour avoir un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans @azure/logger :

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Consultez notre guide de résolution des problèmes pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

Étapes suivantes

Vous trouverez d’autres exemples de code via les liens suivants :

Contribution

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Impressions