Partager via

Bibliothèque cliente secrète Azure Key Vault pour JavaScript - version 4.10.0

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 et de contrôler en toute sécurité l’accès aux jetons, mots de passe, certificats, clés API et autres secrets.

Utilisez la bibliothèque cliente pour les secrets Azure Key Vault 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.
  • Obtenez, videz ou récupérez un secret supprimé.
  • Obtenez toutes les versions d’un secret.
  • Obtenez tous les secrets.
  • Obtenez 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 :

Mise en route

Environnements actuellement pris en charge

Conditions préalables

Installer le package

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

npm install @azure/keyvault-secrets

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.

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 coffre de clés. 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 retourne toujours la dernière valeur attribué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 secrets supprimés ne sont pas immédiatement perdus. Cela se produit uniquement si key Vault a suppression réversible activée.
  • Une sauvegarde secrète peut être générée à partir de n’importe quel secret créé. Ces sauvegardes sont des données binaires et peuvent être utilisées uniquement pour régénérer un secret précédemment supprimé.

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 SecretClient, 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 SecretClient. Une fois ces informations importées, nous pouvons ensuite nous connecter au service Key Vault :

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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 keys client and connect to the service
const client = new SecretClient(url, credential);

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 :

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

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

Exemples

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

Création et définition d’un secret

setSecret attribue 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.

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

const result = await client.setSecret(secretName, "MySecretValue");
console.log("result: ", result);

Obtention d’un secret

La façon la plus simple de lire les 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.

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

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

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: n’importe quel ensemble de clés-valeurs qui peuvent être utilisées 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 secrète.
  • 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 secrète peut être récupérée.
  • expiresOn: date donnée après laquelle la valeur secrète 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 :

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

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

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 secrète existante avec updateSecretProperties, comme suit :

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

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

Suppression d’un secret

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

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

await client.beginDeleteSecret(secretName);

Si de suppression réversible est activée pour le coffre de clés, cette opération étiquette uniquement le secret en tant que secret supprimé secret. Impossible de mettre à jour un secret supprimé. Ils peuvent uniquement être lus, récupérés ou vidés.

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

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

Étant donné que les secrets prennent un certain temps pour être entièrement supprimés, beginDeleteSecret retourne un objet Poller qui effectue le suivi de 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 permettra 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é :

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

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

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

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

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

const poller = await client.beginDeleteSecret(secretName);
while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

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

Itération des listes de secrets

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

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

Qui peut être utilisé comme suit :

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

for await (const secretProperties of client.listPropertiesOfSecrets()) {
  console.log("Secret properties: ", secretProperties);
}

for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("Deleted secret: ", deletedSecret);
}

for await (const versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
  console.log("Version properties: ", versionProperties);
}

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 { SecretClient } from "@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";

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

Résolution des problèmes

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

Étapes suivantes

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

Contribuer

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.

  • Last updated on