Azure Key Vault Secret client library för JavaScript - version 4.11.1

Azure Key Vault är en tjänst som låter dig kryptera autentiseringsnöcklar, lagringskontonycklar, datakrypteringsnycklar, .pfx-filer och lösenord genom att använda säkra nycklar. Om du vill veta mer om Azure Key Vault kan du vilja läsa: Vad är Azure Key Vault?

Azure Key Vault Secrets-hantering gör det möjligt för dig att säkert lagra och noggrant kontrollera åtkomst till tokens, lösenord, certifikat, API-nycklar och andra hemligheter.

Använd klientbiblioteket för Azure Key Vault Secrets i din Node.js applikation för att:

Hämta, ange och ta bort hemligheter.
Uppdatera en hemlighet och dess attribut.
Säkerhetskopiera och återställa en hemlighet.
Hämta, rensa eller återställa en borttagen hemlighet.
Hämta alla versioner av en hemlighet.
Hämta alla hemligheter.
Hämta alla borttagna hemligheter.

Observera: Detta paket kan inte användas i webbläsaren på grund av Azure Key Vault begränsningar i tjänsten, vänligen se detta dokument för vägledning.

Nyckellänkar:

Komma igång

Miljöer som stöds för närvarande

LTS-versioner av Node.js

Förutsättningar

Ett Azure abonnemang
En Key Vault resurs
En befintlig Azure Key Vault. Om du behöver skapa ett nyckelvalv kan du göra det i Azure Portal genom att följa stegen i detta dokument. Alternativt kan du använda Azure CLI genom att följa stegen i detta dokument.

Installera paketet

Installera Azure Key Vault Secret-klientbiblioteket med npm:

npm install @azure/keyvault-secrets

Installera identitetsbiblioteket

Key Vault-klienter autentiserar sig med Azure Identity Library. Installera den också med npm

npm install @azure/identity

Konfigurera TypeScript

TypeScript-användare måste ha definitioner av nodtyp installerade:

npm install @types/node

Du måste också aktivera compilerOptions.allowSyntheticDefaultImports i din tsconfig.json. Observera att om du har aktiverat compilerOptions.esModuleInteropär allowSyntheticDefaultImports aktiverat som standard. Mer information finns i TypeScripts handbok för kompilatoralternativ.

Viktiga begrepp

Secret-klienten är det primära gränssnittet för att interagera med API-metoder relaterade till hemligheter i Azure Key Vault API från en JavaScript-applikation. När den har initierats innehåller den en grundläggande uppsättning metoder som kan användas för att skapa, läsa, uppdatera och ta bort hemligheter.
En Secret version är en version av en hemlighet i Key Vault. Varje gång en användare tilldelar ett värde till ett unikt hemligt namn skapas en ny version av den hemligheten. Om du hämtar en hemlighet med ett namn returneras alltid det senaste tilldelade värdet, såvida inte en specifik version tillhandahålls till frågan.
Mjuk borttagning tillåter att Key Vaults stöder borttagning och rensning som två separata steg, så borttagna hemligheter går inte omedelbart förlorade. Detta händer bara om Key Vault har soft-delete aktiverat.
En hemlig säkerhetskopia kan genereras från alla skapade hemligheter. Dessa säkerhetskopior kommer som binära data och kan bara användas för att återskapa en tidigare borttagen hemlighet.

Autentiering med Azure Active Directory

Key Vault-tjänsten förlitar sig på Azure Active Directory för att autentisera förfrågningar till dess API:er. @azure/identity-paketet innehåller en mängd olika typer av autentiseringsuppgifter som programmet kan använda för att göra detta. README för @azure/identity ger fler detaljer och exempel för att komma igång.

För att interagera med Azure Key Vault-tjänsten behöver du skapa en instans av klassen SecretClient, en vault-url och ett legitimeringsobjekt. Exemplen som visas i det här dokumentet använder ett autentiseringsobjekt med namnet DefaultAzureCredential, vilket är lämpligt för de flesta scenarier, inklusive lokala utvecklings- och produktionsmiljöer. Dessutom rekommenderar vi att du använder en hanterad identitet för autentisering i produktionsmiljöer.

Du kan hitta mer information om olika sätt att autentisera sig och deras motsvarande behörighetstyper i Azure Identity documentation.

Här är ett snabbt exempel. Importera först DefaultAzureCredential och SecretClient. När dessa är importerade kan vi sedan ansluta till Key Vault-tjänsten:

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

För webbläsarmiljöer använder du InteractiveBrowserCredential från @azure/identity-paketet för att autentisera.

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

Specificering av Azure Key Vault service API-versionen

Som standard använder detta paket den senaste versionen Azure Key Vault service som är 7.1. Den enda andra versionen som stöds är 7.0. Du kan ändra den tjänstversion som används genom att ange alternativet serviceVersion i klientkonstruktorn enligt nedan:

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

Exempel

Följande avsnitt ger kodfragment som täcker några av de vanliga uppgifterna med Azure Key Vault Secrets. De scenarier som beskrivs här består av:

Skapa och ange en hemlig.
Skaffa en hemlighet.
Skapa och uppdatera hemligheter med attribut.
tar bort en hemlighet.
Itererande listor över hemligheter.

Skapa och ange en hemlighet

setSecret tilldelar ett angivet värde till det angivna hemliga namnet. Om det redan finns en hemlighet med samma namn skapas en ny version av hemligheten.

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

Hämta en hemlighet

Det enklaste sättet att läsa hemligheter från valvet är att hämta en hemlighet med namn. Då hämtas den senaste versionen av hemligheten. Du kan också hämta en annan version av nyckeln om du anger den som en del av de valfria parametrarna.

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

Skapa och uppdatera hemligheter med attribut

En hemlighet kan ha mer information än dess namn och dess värde. De kan också innehålla följande attribut:

tags: Alla uppsättningar med nyckelvärden som kan användas för att söka efter och filtrera hemligheter.
contentType: Alla strängar som kan användas för att hjälpa mottagaren av hemligheten att förstå hur man använder det hemliga värdet.
enabled: Ett booleskt värde som avgör om det hemliga värdet kan läsas eller inte.
notBefore: Ett angivet datum efter vilket det hemliga värdet kan hämtas.
expiresOn: Ett angivet datum efter vilket det hemliga värdet inte kan hämtas.

Ett objekt med dessa attribut kan skickas som den tredje parametern i setSecret, direkt efter hemlighetens namn och värde enligt följande:

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

Då skapas en ny version av samma hemlighet, som har de senaste attributen.

Attribut kan också uppdateras till en befintlig hemlig version med updateSecretProperties, enligt följande:

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

Ta bort en hemlighet

Metoden beginDeleteSecret startar borttagningen av en hemlighet. Den här processen sker i bakgrunden så snart de nödvändiga resurserna är tillgängliga.

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

Om soft-delete är aktiverat för Key Vault, kommer denna operation endast att märka hemligheten som en deleted hemlighet. Det går inte att uppdatera en borttagen hemlighet. De kan bara läsas, återställas eller rensas.

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

Eftersom hemligheter tar lite tid att ta bort helt returnerar beginDeleteSecret ett Poller-objekt som håller reda på den underliggande långvariga åtgärden enligt våra riktlinjer: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Med den mottagna pollern kan du hämta den borttagna hemligheten genom att anropa till poller.getResult(). Du kan också vänta tills borttagningen har slutförts, antingen genom att köra enskilda tjänstanrop tills hemligheten har tagits bort eller genom att vänta tills processen är klar:

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

Ett annat sätt att vänta tills hemligheten har tagits bort är att göra enskilda anrop på följande sätt:

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

Itererande listor över hemligheter

Med SecretClient kan du hämta och iterera alla hemligheter i en Key Vault, samt genom alla raderade hemligheter och versioner av en specifik hemlighet. Följande API-metoder är tillgängliga:

listPropertiesOfSecrets listar alla dina icke-borttagna hemligheter efter deras namn, endast i de senaste versionerna.
listDeletedSecrets listar alla borttagna hemligheter efter deras namn, endast i de senaste versionerna.
listPropertiesOfSecretVersions visar en lista över alla versioner av en hemlighet baserat på ett hemligt namn.

Som kan användas på följande sätt:

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

Alla dessa metoder returnerar alla tillgängliga resultat samtidigt. Om du vill hämta dem via sidor lägger du till .byPage() direkt efter att du har anropat den API-metod som du vill använda enligt följande:

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

Felsökning

Se vår felsökningsguide för detaljer om hur du diagnostiserar olika felscenarier.

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Nästa steg

Du hittar fler kodexempel via följande länkar:

Bidrag

Om du vill bidra till detta bibliotek, läs gärna guiden bidrag för att lära dig mer om hur man bygger och testar koden.

Feedback

Var den här sidan till hjälp?

Last updated on 2026-04-09