Bibliothèque de client Azure Key Vault Secret pour JavaScript - version 4.8.0

  • Article

Azure Key Vault est un service qui vous permet de chiffrer des clés d’authentification, des clés de compte de stockage, des clés de chiffrement de données, des fichiers .pfx et des mots de passe à l’aide de clés sécurisées. Si vous souhaitez en savoir plus sur Azure Key Vault, vous pouvez consulter : Qu’est-ce qu’Azure Key Vault ?

La gestion des secrets Azure Key Vault vous permet de stocker en toute sécurité et de contrôler étroitement l’accès aux jetons, mots de passe, certificats, clés API et autres secrets.

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

  • Obtenir, définir et supprimer des secrets.
  • Mettez à jour un secret et ses attributs.
  • Sauvegardez et restaurez un secret.
  • Obtenir, vider ou récupérer un secret supprimé.
  • Obtenez toutes les versions d’un secret.
  • Obtenez tous les secrets.
  • Obtenir tous les secrets 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

Installez la bibliothèque de client Azure Key Vault Secret à l’aide de npm :

npm install @azure/keyvault-secrets

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 des définitions de type node installées :

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 .

Concepts clés

  • Le client secret est l’interface principale permettant d’interagir avec les méthodes d’API liées aux secrets 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 secrets.
  • Une version de secret est une version d’un secret dans le Key Vault. Chaque fois qu’un utilisateur affecte une valeur à un nom de secret unique, une nouvelle version de ce secret est créée. La récupération d’un secret par un nom renvoie toujours la dernière valeur 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 secrets supprimés ne sont pas immédiatement perdus. Cela se produit uniquement si la suppression réversible est activée sur le Key Vault.
  • Une sauvegarde de secret peut être générée à partir de n’importe quel secret créé. Ces sauvegardes sont fournies sous forme de données binaires et ne peuvent être utilisées que pour régénérer un secret précédemment supprimé.

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 SecretClient 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, notamment 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 SecretClient:

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

Une fois ceux-ci importés, nous pouvons ensuite nous connecter au service Key Vault :

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

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 secrets client and connect to the service
const client = new SecretClient(url, credential);

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 { SecretClient } = require("@azure/keyvault-secrets");

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 SecretClient(url, credential, {
  serviceVersion: "7.0",
});

Exemples

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

Création et définition d’un secret

setSecret affecte une valeur fournie au nom de secret spécifié. Si un secret portant le même nom existe déjà, une nouvelle version du secret est créée.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue");
  console.log("result: ", result);
}

main();

Obtention d’un secret

Le moyen le plus simple de lire des secrets à partir du coffre consiste à obtenir un secret par nom. Cette opération récupère la version la plus récente du secret. Vous pouvez éventuellement obtenir une autre version de la clé si vous la spécifiez dans le cadre des paramètres facultatifs.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const latestSecret = await client.getSecret(secretName);
  console.log(`Latest version of the secret ${secretName}: `, latestSecret);
  const specificSecret = await client.getSecret(secretName, { version: latestSecret.properties.version! });
  console.log(`The secret ${secretName} at the version ${latestSecret.properties.version!}: `, specificSecret);
}

main();

Création et mise à jour de secrets avec des attributs

Un secret peut avoir plus d’informations que son nom et sa valeur. Ils peuvent également inclure les attributs suivants :

  • tags: tout ensemble de clés-valeurs qui peut être utilisé pour rechercher et filtrer des secrets.
  • contentType: toute chaîne qui peut être utilisée pour aider le récepteur du secret à comprendre comment utiliser la valeur du secret.
  • enabled: valeur booléenne qui détermine si la valeur secrète peut être lue ou non.
  • notBefore: date donnée après laquelle la valeur du secret peut être récupérée.
  • expiresOn: date donnée après laquelle la valeur du secret ne peut pas être récupérée.

Un objet avec ces attributs peut être envoyé en tant que troisième paramètre de setSecret, juste après le nom et la valeur du secret, comme suit :

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue", {
    enabled: false,
  });
}

main();

Cela crée une nouvelle version du même secret, qui aura les derniers attributs fournis.

Les attributs peuvent également être mis à jour vers une version de secret existante avec updateSecretProperties, comme suit :

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.getSecret(secretName);
  await client.updateSecretProperties(secretName, result.properties.version, { enabled: false });
}

main();

Suppression d’un secret

La beginDeleteSecret méthode démarre la suppression d’un secret. Ce processus se produit en arrière-plan dès que les ressources nécessaires sont disponibles.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  await client.beginDeleteSecret(secretName);
}

main();

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

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  const deletedSecret = poller.getResult();

  // The secret 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 secret this way:
  await client.getDeletedSecret(secretName);

  // Deleted secrets can also be recovered or purged.

  // recoverDeletedSecret returns a poller, just like beginDeleteSecret.
  const recoverPoller = await client.beginRecoverDeletedSecret(secretName);
  await recoverPoller.pollUntilDone();

  // And then, to purge the deleted secret:
  await client.purgeDeletedSecret(secretName);
}

main();

Étant donné que la suppression complète des secrets prend un certain temps, beginDeleteSecret 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

Le polleur reçu vous permet d’obtenir le secret supprimé 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 secret soit supprimé, soit en attendant que le processus soit terminé :

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  let deletedSecret = poller.getResult();

  // Or you can wait until the secret finishes being deleted:
  deletedSecret = await poller.pollUntilDone();
  console.log(deletedSecret);
}

main();

Une autre façon d’attendre que le secret soit entièrement supprimé consiste à effectuer des appels individuels, comme suit :

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");
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 SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

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

  console.log(`The secret ${secretName} is fully deleted`);
}

main();

Itération des listes de secrets

À l’aide de SecretClient, vous pouvez récupérer et itérer tous les secrets d’un Key Vault, ainsi que tous les secrets supprimés et les versions d’un secret spécifique. Les méthodes d’API suivantes sont disponibles :

  • listPropertiesOfSecrets répertorie tous vos secrets non supprimés par leur nom, uniquement à leurs dernières versions.
  • listDeletedSecrets répertoriera tous vos secrets supprimés en fonction de leur nom, uniquement à leurs dernières versions.
  • listPropertiesOfSecretVersions répertorie toutes les versions d’un secret basé sur un nom de secret.

Qui peut être utilisé comme suit :

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let secretProperties of client.listPropertiesOfSecrets()) {
    console.log("Secret properties: ", secretProperties);
  }
  for await (let deletedSecret of client.listDeletedSecrets()) {
    console.log("Deleted secret: ", deletedSecret);
  }
  for await (let versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
    console.log("Version properties: ", versionProperties);
  }
}

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 { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let page of client.listPropertiesOfSecrets().byPage()) {
    for (let secretProperties of page) {
      console.log("Secret properties: ", secretProperties);
    }
  }
  for await (let page of client.listDeletedSecrets().byPage()) {
    for (let deletedSecret of page) {
      console.log("Deleted secret: ", deletedSecret);
    }
  }
  for await (let page of client.listPropertiesOfSecretVersions(secretName).byPage()) {
    for (let versionProperties of page) {
      console.log("Version properties: ", versionProperties);
    }
  }
}

main();

Dépannage

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.

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

É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