Bibliothèque de client Certificats Azure Key Vault pour JavaScript - version 4.9.0

Article
10/16/2024

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 a une stratégie associée qui contrôle l’émission et la durée de vie du certificat, ainsi que les actions à entreprendre en tant que certificats à expiration.

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

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

Obtenez, définissez et supprimez un certificat.
Mettez à jour un certificat, ses attributs, son émetteur, sa stratégie, son opération et ses contacts.
Sauvegardez et restaurez un certificat.
Obtenez, videz ou récupérez 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 :

code source
package (npm)
Documentation de référence de l’API
documentation produit
Exemples

Commencer

Environnements actuellement pris en charge

versions LTS de Node.js

Conditions préalables

Un abonnement Azure
Un Azure Key Vault existant. Si vous devez créer un coffre de clés, vous pouvez le faire dans le portail Azure en suivant les étapes décrites dans ce document. Vous pouvez également utiliser Azure CLI en suivant ces étapes.

Installer le package

Installer la bibliothèque de client Certificats Azure Key Vault à l’aide de npm

npm install @azure/keyvault-certificates

Installer la bibliothèque d’identités

Les clients Key Vault 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é les définitions de type Node :

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 manuel des options du compilateur de TypeScript.

Authentification auprès d’Azure Active Directory

Le service Key Vault s’appuie sur Azure Active Directory pour authentifier les demandes auprès de ses API. Le package @azure/identity fournit divers types d’informations d’identification que votre application peut utiliser pour ce faire. Le 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 une instance de la classe CertificateClient, 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 les environnements de développement et de production locaux. En outre, nous vous recommandons d’utiliser une d’identité managée pour l’authentification dans les environnements de production.

Vous trouverez plus d’informations sur différentes façons d’authentifier 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 ces informations importées, nous pouvons ensuite nous connecter au service key vault :

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 Certificates est l’interface principale pour 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 coffre de clés. 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 dernière valeur affectée, sauf si une version spécifique est fournie à la requête.
suppression réversible permet aux coffres de clés de prendre en charge la suppression et la purge en deux étapes distinctes, de sorte que les certificats supprimés ne sont pas immédiatement perdus. Cela se produit uniquement si key Vault a suppression réversible activée.
Un de sauvegarde de certificat peut être généré à partir de n’importe quel certificat créé. Ces sauvegardes sont des données binaires et peuvent être utilisées uniquement pour régénérer un certificat précédemment supprimé.

Spécification de la version de l’API de 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 de certificats Azure Key Vault. Les scénarios abordés ici sont les suivants :

Création et définition d’un certificat.
Obtenir un certificat Key Vault.
Obtenir les informations complètes d’un certificat.
Certificats au format PEM.
Répertorier tous les certificats.
Mise à jour d’un certificat.
Suppression d’un certificat.
itération des listes de certificats.

Création et définition d’un certificat

beginCreateCertificate cré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 de 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: n’importe quel 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 portant le même nom crée une nouvelle version du même certificat, qui aura les derniers attributs fournis.

Étant donné que les certificats prennent un certain temps pour être entièrement créés, beginCreateCertificate retourne un objet d’interrogation qui suit l’opération de longue durée sous-jacente en fonction de 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

La façon la 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 pour utiliser les fonctionnalités clés et secrets. Examinons la composition d’un certificat Key Vault :

Lorsqu’un certificat Key Vault est créé, une clé adressable et un secret sont également créés avec le même nom. La clé Key Vault autorise les opérations de clé et le secret Key Vault permet la récupération de 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 secret Key Vault, avec le certificat public inclus, nous pouvons la récupérer à l’aide du client Secrets Key Vault.

// 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 pourrez le récupérer au format PEM. Avant de montrer comment créer des certificats PEM, commençons par découvrir comment récupérer une clé secrète PEM à partir d’un certificat PKCS 12 en premier.

À 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 propriété contentType 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 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);

N’oubliez pas que votre certificat public se trouvera 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

listPropertiesOfCertificates répertorie tous les certificats du coffre de clés.

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 méthode beginDeleteCertificate configure un certificat pour suppression. Ce processus se produit en arrière-plan dès que les ressources nécessaires sont disponibles.

Si de suppression réversible est activée pour le coffre de clés, cette opération étiquette uniquement le certificat en tant que certificat supprimé. Un certificat supprimé ne peut pas être mis à jour. Ils peuvent uniquement être lus, récupérés ou vidés.

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 méthode beginDeleteCertificate avant que le certificat supprimé soit disponible pour ê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 dans 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 par leurs noms, uniquement aux 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 à la fois. 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 à découvrir des informations utiles sur les échecs. Pour afficher 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 la @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 :

Contribuant

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

Partager via