Azure Key Vault Certificates bibliothèque client pour JavaScript - version 4.10.3

Azure Key Vault est un service cloud qui offre un stockage sécurisé et une gestion automatisée des certificats utilisés dans une application cloud. Plusieurs certificats, ainsi que 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 que Azure Key Vault ?

Utilisez la bibliothèque client pour Azure Key Vault certificats dans votre Node.js de demande 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 paquet ne peut pas être utilisé dans le navigateur en raison de Azure Key Vault limitations de service, veuillez consulter ce document pour des conseils.

Liens clés :

Commencer

Environnements actuellement pris en charge

Conditions préalables

  • Un abonnement Azure
  • Un Azure Key Vault existant. Si vous devez créer un coffre-fort à clés, vous pouvez le faire dans le Portail Azure en suivant les étapes de ce document. Sinon, utilisez la Azure CLI en suivant ces étapes.

Installer le package

Installer la bibliothèque client Azure Key Vault Certificates en utilisant npm

npm install @azure/keyvault-certificates

Installer la bibliothèque d’identités

Les clients Key Vault s’authentifient via la bibliothèque Azure Identity. 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 avec Azure Active Directory

Le service Key Vault s’appuie sur Azure Active Directory pour authentifier les requêtes vers 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 des exemples pour vous aider à démarrer.

Pour interagir avec le service Azure Key Vault, vous devrez créer une instance de la classe CertificateClient, une URL vault et un objet d’identifiants. 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 pouvez trouver plus d’informations sur les différentes méthodes d’authentification et leurs types de titres correspondants dans le Azure Documentation d’identité.

Voici un exemple rapide. Tout d’abord, importez DefaultAzureCredential et CertificateClient. Une fois ces informations importées, nous pouvons ensuite nous connecter au service key vault :

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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 API liées aux certificats dans l’API Azure Key Vault depuis 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 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 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 n’arrive que si le Key Vault a activé soft-delete.
  • 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écifier la version de l’API du service Azure Key Vault

Par défaut, ce paquet 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 :

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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.5",
});

Exemples

Les sections suivantes fournissent des extraits de code qui couvrent certaines des tâches courantes utilisant les certificats Azure Key Vault. Les scénarios abordés ici sont les suivants :

Création et définition d’un certificat

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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.
await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
});

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.
import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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",
};

await client.beginCreateCertificate(certificateName, certificatePolicy, {
  enabled,
  tags,
});

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é :

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

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

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

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

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

console.log(`The certificate ${certificateName} is fully created`);

Obtenir 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.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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 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,
);

Obtention des informations complètes d’un certificat

Le design d'Azure Key Vault fait des distinctions nettes entre clés, secrets et certificats. Les fonctionnalités Certificats du service Key Vault ont été conçues en exploitant ses fonctionnalités Clés et Secrets. Évaluons la composition d'un certificat Key Vault :

Lorsqu’un certificat Key Vault est créé, une clé adressable et un secret sont également créés sous le même nom. La clé Key Vault permet des opérations de clé 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 publiques x509. 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 en utilisant le client Key Vault Secrets.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { writeFileSync } from "node:fs";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const secretClient = new SecretClient(keyVaultUrl, credential);

const certificateName = "MyCertificateName";

// 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:
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 travailler avec des certificats au format PEM, vous pouvez demander au service Key Vault de Azure de créer et gérer vos certificats en 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 publique et privée d’un certificat formaté PEM en utilisant les clients Key Vault for Certificates and Secrets :

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);
const secretClient = new SecretClient(keyVaultUrl, credential);
// 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.
});
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 listera tous les certificats dans le Key Vault.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const certificateProperties of client.listPropertiesOfCertificates()) {
  console.log("Certificate properties: ", certificateProperties);
}
for await (const deletedCertificate of client.listDeletedCertificates()) {
  console.log("Deleted certificate: ", deletedCertificate);
}
for await (const certificateProperties of client.listPropertiesOfCertificateVersions(
  certificateName,
)) {
  console.log("Certificate properties: ", certificateProperties);
}

Mise à jour d’un certificat

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

const result = await client.getCertificate(certificateName);
await client.updateCertificateProperties(certificateName, result.properties.version, {
  enabled: false,
  tags: {
    myCustomTag: "myCustomTagsValue",
  },
});

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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",
});

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 soft-delete est activé pour le Key Vault, cette opération ne qualifiera le certificat que de supprimé. Un certificat supprimé ne peut pas être mis à jour. Ils peuvent uniquement être lus, récupérés ou vidés.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

É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 :

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const certificateProperties of client.listPropertiesOfCertificates()) {
  console.log("Certificate properties: ", certificateProperties);
}
for await (const deletedCertificate of client.listDeletedCertificates()) {
  console.log("Deleted certificate: ", deletedCertificate);
}
for await (const certificateProperties of client.listPropertiesOfCertificateVersions(
  certificateName,
)) {
  console.log("Certificate properties: ", certificateProperties);
}

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 :

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const page of client.listPropertiesOfCertificates().byPage()) {
  for (const certificateProperties of page) {
    console.log("Certificate properties: ", certificateProperties);
  }
}
for await (const page of client.listDeletedCertificates().byPage()) {
  for (const deletedCertificate of page) {
    console.log("Deleted certificate: ", deletedCertificate);
  }
}
for await (const page of client.listPropertiesOfCertificateVersions(certificateName).byPage()) {
  for (const certificateProperties of page) {
    console.log("Properties of certificate: ", certificateProperties);
  }
}

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 dépannage pour plus de détails sur la manière de diagnostiquer différents scénarios de défaillance.

Étapes suivantes

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

Contribuant

Si vous souhaitez contribuer à cette bibliothèque, veuillez lire le guide contribution pour en savoir plus sur la construction et le test du code.

  • Last updated on