Partager via

Azure Key Vault Secret client library for JavaScript - version 4.11.1

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 en utilisant des clés sécurisées. Si vous souhaitez en savoir plus sur Azure Key Vault, vous pouvez consulter : Qu’est-ce que Azure Key Vault ?

La gestion Azure Key Vault Secrets vous permet de stocker et de contrôler de manière sécurisée l’accès aux jetons, mots de passe, certificats, clés API et autres secrets.

Utilisez la bibliothèque client pour Azure Key Vault Secrets dans votre Node.js application 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 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 :

Mise en route

Environnements actuellement pris en charge

Conditions préalables

  • Un abonnement Azure
  • Une ressource Key Vault
  • 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, vous pouvez utiliser le Azure CLI en suivant les étapes de ce document.

Installer le package

Installez la bibliothèque client Azure Key Vault Secret en utilisant npm :

npm install @azure/keyvault-secrets

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.

Concepts clés

  • Le client Secret est l’interface principale pour interagir avec les méthodes API liées aux secrets dans l’API Azure Key Vault provenant 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 Secrète 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 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 n’arrive que si le Key Vault a activé soft-delete.
  • 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 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 SecretClient, 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 SecretClient. Une fois ces éléments importés, 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 secrets client and connect to the service
const client = new SecretClient(url, credential);

Pour les environnements de navigateur, utilisez le InteractiveBrowserCredential à partir du package @azure/identity pour l’authentification.

import { InteractiveBrowserCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new SecretClient(url, credential);

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 { 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 couvrant 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 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 soft-delete est activé pour le Key Vault, cette opération ne qualifiera le secret que de secret supprimé. 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

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

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, veuillez lire le guide contribution pour en savoir plus sur la construction et le test du code.

  • Last updated on