Azure Key Vault Hemligt klientbibliotek för JavaScript – version 4.8.0

Artikel
02/16/2024

Azure Key Vault är en tjänst som gör att du kan kryptera autentiseringsnycklar, lagringskontonycklar, datakrypteringsnycklar, PFX-filer och lösenord med hjälp av skyddade nycklar. Om du vill veta mer om Azure Key Vault kanske du vill granska: Vad är Azure Key Vault?

Med Azure Key Vault Secrets Management kan du lagra och kontrollera åtkomsten till token, lösenord, certifikat, API-nycklar och andra hemligheter på ett säkert sätt.

Använd klientbiblioteket för Azure Key Vault Secrets i ditt Node.js-program 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.

Obs! Det här paketet kan inte användas i webbläsaren på grund av begränsningar i Azure Key Vault-tjänsten. Mer information finns i det här dokumentet.

Nyckellänkar:

Komma igång

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

LTS-versioner av Node.js

Förutsättningar

En Azure-prenumeration
En Key Vault resurs
En befintlig Azure-Key Vault. Om du behöver skapa ett nyckelvalv kan du göra det i Azure-portalen genom att följa stegen i det här dokumentet. Du kan också använda Azure CLI genom att följa stegen i det här dokumentet.

Installera paketet

Installera Azure Key Vault Secret-klientbiblioteket med npm:

npm install @azure/keyvault-secrets

Installera identitetsbiblioteket

Key Vault klienter autentiserar med hjälp av Azure Identity Library. Installera den också med npm

npm install @azure/identity

Konfigurera TypeScript

TypeScript-användare måste ha nodtypsdefinitioner installerade:

npm install @types/node

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

Viktiga begrepp

Den hemliga klienten är det primära gränssnittet för att interagera med API-metoderna som är relaterade till hemligheter i Azure Key Vault-API:et från ett JavaScript-program. 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 hemlig 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 hemligheten. Om du hämtar en hemlighet med ett namn returneras alltid det senaste tilldelade värdet, såvida inte en specifik version anges för frågan.
Mjuk borttagning gör att Key Vaults stöder borttagning och rensning som två separata steg, så borttagna hemligheter går inte omedelbart förlorade. Detta inträffar bara om Key Vault har mjuk borttagning aktiverat.
En säkerhetskopia av hemligheter 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.

Autentisera med Azure Active Directory

Key Vault-tjänsten förlitar sig på Azure Active Directory för att autentisera begäranden till dess API:er. Paketet @azure/identity innehåller en mängd olika typer av autentiseringsuppgifter som ditt program kan använda för att göra detta. README för @azure/identity innehåller mer information och exempel för att komma igång.

För att interagera med Tjänsten Azure Key Vault måste du skapa en instans av SecretClient klassen, en valv-URL och ett autentiseringsobjekt. Exemplen som visas i det här dokumentet använder ett autentiseringsuppgiftsobjekt 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 hittar mer information om olika sätt att autentisera och deras motsvarande typer av autentiseringsuppgifter i Azure Identity-dokumentationen.

Här är ett snabbt exempel. Importera först DefaultAzureCredential och SecretClient:

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

När dessa har importerats kan vi ansluta till tjänsten 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);

Ange API-versionen för Azure Key Vault-tjänsten

Som standard använder det här paketet den senaste versionen av Azure Key Vault-tjänsten, 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:

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

Exempel

Följande avsnitt innehåller kodfragment som beskriver några av de vanliga uppgifterna med hjälp av Azure Key Vault Secrets. De scenarier som beskrivs här består av:

Skapa och ange en hemlighet.
Hämta en hemlighet.
Skapa och uppdatera hemligheter med attribut.
Tar bort en hemlighet.
Iterera 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.

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

Hämta en hemlighet

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

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

Skapa och uppdatera hemligheter med attribut

En hemlighet kan ha mer information än dess namn och 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 setSecretför , direkt efter hemlighetens namn och värde enligt följande:

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

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

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

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

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.

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

Om mjuk borttagning är aktiverat för Key Vault märker den här åtgärden bara hemligheten som en borttagen hemlighet. Det går inte att uppdatera en borttagen hemlighet. De kan bara läsas, återställas eller rensas.

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

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 är klar, antingen genom att köra enskilda tjänstanrop tills hemligheten har tagits bort eller genom att vänta tills processen är klar:

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

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

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

Itererande listor över hemligheter

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

listPropertiesOfSecrets visar en lista över alla icke-borttagna hemligheter efter deras namn, endast i de senaste versionerna.
listDeletedSecrets visar en lista över 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:

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

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:

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

Felsökning

Mer information om hur du diagnostiserar olika felscenarier finns i vår felsökningsguide .

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg över 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:

Bidra

Om du vill bidra till det här biblioteket kan du läsa bidragsguiden för att lära dig mer om hur du skapar och testar koden.

Visningar

Dela via