Azure Key Vault Secret-clientbibliotheek voor JavaScript - versie 4.10.0

2025-06-12

Azure Key Vault is een service waarmee u verificatiesleutels, opslagaccountsleutels, gegevensversleutelingssleutels, PFX-bestanden en wachtwoorden kunt versleutelen met behulp van beveiligde sleutels. Als u meer wilt weten over Azure Key Vault, kunt u het volgende bekijken: Wat is Azure Key Vault?

Met Azure Key Vault-geheimenbeheer kunt u de toegang tot tokens, wachtwoorden, certificaten, API-sleutels en andere geheimen veilig opslaan en beheren.

Gebruik de clientbibliotheek voor Azure Key Vault-geheimen in uw Node.js toepassing om het volgende te doen:

Geheimen ophalen, instellen en verwijderen.
Werk een geheim bij en dit zijn kenmerken.
Back-up maken en een geheim herstellen.
Een verwijderd geheim ophalen, opschonen of herstellen.
Haal alle versies van een geheim op.
Haal alle geheimen op.
Haal alle verwijderde geheimen op.

Opmerking: dit pakket kan niet worden gebruikt in de browser vanwege servicebeperkingen van Azure Key Vault. Raadpleeg dit document voor hulp.

Sleutelkoppelingen:

Aan de slag

Momenteel ondersteunde omgevingen

LTS-versies van Node.js

Vereiste voorwaarden

Een Azure-abonnement
Een Key Vault-resource
Een bestaande Azure Key Vault-. Als u een sleutelkluis moet maken, kunt u dit doen in Azure Portal door de stappen in dit document te volgen. U kunt de Azure CLI ook gebruiken door de stappen in dit document te volgen.

Installeer het pakket

Installeer de Azure Key Vault Secret-clientbibliotheek met behulp van npm:

npm install @azure/keyvault-secrets

De identiteitsbibliotheek installeren

Key Vault-clients verifiëren met behulp van de Azure Identity Library. Installeer het ook met npm

npm install @azure/identity

TypeScript configureren

TypeScript-gebruikers moeten knooppunttypedefinities hebben geïnstalleerd:

npm install @types/node

U moet ook compilerOptions.allowSyntheticDefaultImports inschakelen in uw tsconfig.json. Houd er rekening mee dat als u compilerOptions.esModuleInterophebt ingeschakeld, allowSyntheticDefaultImports standaard is ingeschakeld. Zie het handboek voor compileropties van TypeScript voor meer informatie.

Belangrijke concepten

De Secret-client is de primaire interface voor interactie met de API-methoden met betrekking tot geheimen in de Azure Key Vault-API vanuit een JavaScript-toepassing. Zodra het is geïnitialiseerd, biedt het een basisset methoden die kunnen worden gebruikt voor het maken, lezen, bijwerken en verwijderen van geheimen.
Een Geheime versie is een versie van een geheim in Key Vault. Telkens wanneer een gebruiker een waarde toewijst aan een unieke geheime naam, wordt er een nieuwe versie van dat geheim gemaakt. Het ophalen van een geheim op basis van een naam retourneert altijd de meest recente waarde die is toegewezen, tenzij er een specifieke versie aan de query wordt verstrekt.
Voorlopig verwijderen kan Key Vaults ondersteuning bieden voor verwijdering en opschonen als twee afzonderlijke stappen, zodat verwijderde geheimen niet onmiddellijk verloren gaan. Dit gebeurt alleen als key vault voorlopig verwijderen is ingeschakeld.
Een Back-up van geheim kan worden gegenereerd op basis van elk gemaakt geheim. Deze back-ups worden geleverd als binaire gegevens en kunnen alleen worden gebruikt om een eerder verwijderd geheim opnieuw te genereren.

Verifiëren met Azure Active Directory

De Key Vault-service is afhankelijk van Azure Active Directory voor het verifiëren van aanvragen voor de BIJBEHORENDE API's. Het @azure/identity-pakket biedt verschillende referentietypen die uw toepassing hiervoor kan gebruiken. De LEESMIJ voor @azure/identity biedt meer informatie en voorbeelden om u op weg te helpen.

Als u wilt communiceren met de Azure Key Vault-service, moet u een exemplaar van de klasse SecretClient maken, een kluis-URL en een referentieobject. In de voorbeelden in dit document wordt een referentieobject met de naam DefaultAzureCredentialgebruikt. Dit is geschikt voor de meeste scenario's, waaronder lokale ontwikkel- en productieomgevingen. Daarnaast raden we u aan een beheerde identiteit te gebruiken voor verificatie in productieomgevingen.

Meer informatie over verschillende manieren om te verifiëren en de bijbehorende referentietypen vindt u in de Azure Identity-documentatie.

Hier volgt een snel voorbeeld. Importeer eerst DefaultAzureCredential en SecretClient. Zodra deze zijn geïmporteerd, kunnen we verbinding maken met de Key Vault-service:

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

De API-versie van de Azure Key Vault-service opgeven

Dit pakket maakt standaard gebruik van de nieuwste versie van de Azure Key Vault-service die 7.1is. De enige andere versie die wordt ondersteund, is 7.0. U kunt de serviceversie wijzigen die wordt gebruikt door de optie in te stellen serviceVersion in de clientconstructor, zoals hieronder wordt weergegeven:

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

Voorbeelden

De volgende secties bevatten codefragmenten die betrekking hebben op enkele algemene taken met behulp van Azure Key Vault-geheimen. De scenario's die hier worden behandeld, bestaan uit:

een geheimmaken en instellen.
Een geheimophalen.
geheimen maken en bijwerken met kenmerken.
een geheimverwijderen.
Lijsten met geheimen herhalen.

Een geheim maken en instellen

setSecret wijst een opgegeven waarde toe aan de opgegeven geheime naam. Als er al een geheim met dezelfde naam bestaat, wordt er een nieuwe versie van het geheim gemaakt.

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

Een geheim ophalen

De eenvoudigste manier om geheimen terug te lezen uit de kluis is door een geheim op naam te krijgen. Hiermee wordt de meest recente versie van het geheim opgehaald. U kunt desgewenst een andere versie van de sleutel ophalen als u deze opgeeft als onderdeel van de optionele parameters.

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

Geheimen maken en bijwerken met kenmerken

Een geheim kan meer informatie hebben dan de naam en de waarde ervan. Ze kunnen ook de volgende kenmerken bevatten:

tags: elke set sleutelwaarden die kunnen worden gebruikt om geheimen te doorzoeken en te filteren.
contentType: elke tekenreeks die kan worden gebruikt om de ontvanger van het geheim te helpen begrijpen hoe de geheime waarde moet worden gebruikt.
enabled: een Booleaanse waarde die bepaalt of de geheime waarde al dan niet kan worden gelezen.
notBefore: een bepaalde datum waarna de geheime waarde kan worden opgehaald.
expiresOn: een bepaalde datum waarna de geheime waarde niet kan worden opgehaald.

Een object met deze kenmerken kan als de derde parameter van setSecretworden verzonden, direct na de naam en waarde van het geheim, als volgt:

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

Hiermee maakt u een nieuwe versie van hetzelfde geheim, met de meest recente opgegeven kenmerken.

Kenmerken kunnen als volgt worden bijgewerkt naar een bestaande geheime versie met updateSecretProperties:

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

Een geheim verwijderen

Met de methode beginDeleteSecret wordt het verwijderen van een geheim gestart. Dit proces vindt plaats op de achtergrond zodra de benodigde resources beschikbaar zijn.

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

Als voorlopig verwijderen is ingeschakeld voor de Sleutelkluis, wordt met deze bewerking alleen het geheim gelabeld als een verwijderd geheim. Een verwijderd geheim kan niet worden bijgewerkt. Ze kunnen alleen worden gelezen, hersteld of verwijderd.

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

Omdat geheimen enige tijd in beslag nemen om volledig te worden verwijderd, retourneert beginDeleteSecret een Poller-object dat de onderliggende langdurige bewerking bijhoudt volgens onze richtlijnen: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Met de ontvangen poller kunt u het verwijderde geheim ophalen door naar poller.getResult()aan te roepen. U kunt ook wachten totdat het verwijderen is voltooid, door afzonderlijke service-aanroepen uit te voeren totdat het geheim is verwijderd of door te wachten totdat het proces is voltooid:

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

Een andere manier om te wachten totdat het geheim volledig is verwijderd, is als volgt afzonderlijke aanroepen uit te voeren:

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

Lijsten met geheimen herhalen

Met behulp van SecretClient kunt u alle geheimen in een Key Vault ophalen en herhalen, evenals door alle verwijderde geheimen en de versies van een specifiek geheim. De volgende API-methoden zijn beschikbaar:

listPropertiesOfSecrets vermeldt al uw niet-verwijderde geheimen op hun naam, alleen in de nieuwste versies.
listDeletedSecrets vermeldt al uw verwijderde geheimen op hun naam, alleen in de nieuwste versies.
listPropertiesOfSecretVersions worden alle versies van een geheim weergegeven op basis van een geheime naam.

Dit kan als volgt worden gebruikt:

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

Al deze methoden retourneren alle beschikbare resultaten tegelijk. Als u ze op pagina's wilt ophalen, voegt u .byPage() toe nadat u de API-methode hebt aangeroepen die u wilt gebruiken, als volgt:

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

Probleemoplossingsproces

Raadpleeg onze gids voor probleemoplossing voor meer informatie over het vaststellen van verschillende foutscenario's.

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Volgende stappen

U vindt meer codevoorbeelden via de volgende koppelingen:

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

Feedback

Is deze pagina nuttig?