Azure Key Vault-Clientbibliothek für JavaScript – Version 4.10.0

Azure Key Vault ist ein Dienst, mit dem Sie Authentifizierungsschlüssel, Speicherkontoschlüssel, Datenverschlüsselungsschlüssel, PFX-Dateien und Kennwörter mithilfe gesicherter Schlüssel verschlüsseln können. Wenn Sie mehr über Azure Key Vault wissen möchten, können Sie folgendes überprüfen: Was ist Azure Key Vault?

Die Verwaltung von Azure Key Vault Secrets ermöglicht es Ihnen, den Zugriff auf Token, Kennwörter, Zertifikate, API-Schlüssel und andere geheime Schlüssel sicher zu speichern und streng zu steuern.

Verwenden Sie die Clientbibliothek für Azure Key Vault Secrets in Ihrer Node.js Anwendung, um:

Abrufen, Festlegen und Löschen geheimer Schlüssel.
Aktualisieren Sie einen geheimen Schlüssel und die Attribute.
Sichern und Wiederherstellen eines geheimen Schlüssels.
Dient zum Abrufen, Löschen oder Wiederherstellen eines gelöschten Geheimschlüssels.
Rufen Sie alle Versionen eines geheimen Schlüssels ab.
Rufen Sie alle geheimen Schlüssel ab.
Rufen Sie alle gelöschten geheimen Schlüssel ab.

Hinweis: Dieses Paket kann aufgrund von Azure Key Vault-Dienstbeschränkungen nicht im Browser verwendet werden. Weitere Informationen finden Sie in diesem Dokument.

Wichtige Links:

Erste Schritte

Derzeit unterstützte Umgebungen

LTS-Versionen von Node.js

Voraussetzungen

Ein Azure-Abonnement
Eine Key Vault-Ressource
Eine vorhandene Azure Key Vault-. Wenn Sie einen Schlüsseltresor erstellen müssen, können Sie dies im Azure-Portal tun, indem Sie die Schritte in dieses Dokumentsausführen. Alternativ können Sie die Azure CLI verwenden, indem Sie die Schritte in diesem Dokumentausführen.

Installiere das Paket

Installieren Sie die Clientbibliothek des geheimen Azure Key Vault-Schlüssels mithilfe von npm:

npm install @azure/keyvault-secrets

Installieren der Identitätsbibliothek

Key Vault-Clients authentifizieren sich mithilfe der Azure Identity Library. Installieren sie auch mithilfe von npm

npm install @azure/identity

Konfigurieren von TypeScript

TypeScript-Benutzer müssen Knotentypdefinitionen installiert haben:

npm install @types/node

Sie müssen auch compilerOptions.allowSyntheticDefaultImports in Ihrem tsconfig.jsonaktivieren. Wenn Sie compilerOptions.esModuleInteropaktiviert haben, ist allowSyntheticDefaultImports standardmäßig aktiviert. Weitere Informationen finden Sie im Compileroptionenhandbuch TypeScript.

Wichtige Begriffe

Der geheimen Client ist die primäre Schnittstelle für die Interaktion mit den API-Methoden im Zusammenhang mit geheimen Schlüsseln in der Azure Key Vault-API aus einer JavaScript-Anwendung. Nach der Initialisierung stellt sie einen grundlegenden Satz von Methoden bereit, mit denen geheime Schlüssel erstellt, gelesen, aktualisiert und gelöscht werden können.
Eine Geheime Version ist eine Version eines geheimen Schlüssels im Key Vault. Jedes Mal, wenn ein Benutzer einem eindeutigen geheimen Namen einen Wert zuweist, wird eine neue Version dieses geheimen Schlüssels erstellt. Wenn Sie einen geheimen Schlüssel anhand eines Namens abrufen, wird immer der neueste Wert zurückgegeben, es sei denn, eine bestimmte Version wird der Abfrage bereitgestellt.
soft delete ermöglicht Es Key Vaults, das Löschen und Löschen als zwei separate Schritte zu unterstützen, sodass gelöschte Geheime nicht sofort verloren gehen. Dies geschieht nur, wenn der Key Vault soft-delete aktiviert hat.
Eine Geheime Sicherung kann aus jedem erstellten geheimen Schlüssel generiert werden. Diese Sicherungen sind binärdaten und können nur verwendet werden, um einen zuvor gelöschten Geheimschlüssel neu zu generieren.

Authentifizieren mit Azure Active Directory

Der Key Vault-Dienst basiert auf Azure Active Directory, um Anforderungen an seine APIs zu authentifizieren. Das @azure/identity-Paket bietet eine Vielzahl von Anmeldeinformationstypen, die Ihre Anwendung verwenden kann, um dies zu tun. Die README für @azure/identity enthält weitere Details und Beispiele für die ersten Schritte.

Um mit dem Azure Key Vault-Dienst zu interagieren, müssen Sie eine Instanz der SecretClient Klasse, eine Vault-URL und ein Anmeldeinformationsobjekt erstellen. In den Beispielen in diesem Dokument wird ein Anmeldeinformationsobjekt namens DefaultAzureCredentialverwendet, das für die meisten Szenarien geeignet ist, einschließlich lokaler Entwicklungs- und Produktionsumgebungen. Darüber hinaus empfehlen wir die Verwendung einer verwalteten Identität für die Authentifizierung in Produktionsumgebungen.

Weitere Informationen zu verschiedenen Möglichkeiten der Authentifizierung und der entsprechenden Anmeldeinformationstypen finden Sie in der Azure Identity-Dokumentation.

Hier ist ein schnelles Beispiel. Importieren Sie zunächst DefaultAzureCredential und SecretClient. Sobald diese importiert wurden, können wir als Nächstes eine Verbindung mit dem Key Vault-Dienst herstellen:

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

Angeben der Azure Key Vault-Dienst-API-Version

Standardmäßig verwendet dieses Paket die neueste Azure Key Vault-Dienstversion, die 7.1ist. Die einzige unterstützte Version ist 7.0. Sie können die verwendete Dienstversion ändern, indem Sie die Option serviceVersion im Clientkonstruktor wie unten gezeigt festlegen:

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

Beispiele

In den folgenden Abschnitten werden Codeausschnitte bereitgestellt, die einige der allgemeinen Aufgaben mit Azure Key Vault Secrets abdecken. Die hier behandelten Szenarien bestehen aus:

Erstellen und Festlegen eines geheimen.
Abrufen eines geheimen.
Erstellen und Aktualisieren geheimer Schlüssel mit Attributen.
Löschen eines geheimen.
Iterieren von Listen von Geheimnissen.

Erstellen und Festlegen eines geheimen Schlüssels

setSecret weist dem angegebenen geheimen Namen einen angegebenen Wert zu. Wenn bereits ein Geheimschlüssel mit demselben Namen vorhanden ist, wird eine neue Version des geheimen Schlüssels erstellt.

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

Abrufen eines geheimen Schlüssels

Die einfachste Möglichkeit, geheime Schlüssel aus dem Tresor zu lesen, besteht darin, einen geheimen Schlüssel anhand des Namens zu erhalten. Dadurch wird die neueste Version des geheimen Schlüssels abgerufen. Sie können optional eine andere Version des Schlüssels abrufen, wenn Sie ihn als Teil der optionalen Parameter angeben.

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

Erstellen und Aktualisieren geheimer Schlüssel mit Attributen

Ein Geheimer Schlüssel kann mehr Informationen als seinen Namen und seinen Wert enthalten. Sie können auch die folgenden Attribute enthalten:

tags: Jeder Satz von Schlüsselwerten, mit denen geheime Schlüssel gesucht und gefiltert werden können.
contentType: Jede Zeichenfolge, die verwendet werden kann, um dem Empfänger des geheimen Schlüssels zu helfen, zu verstehen, wie der geheime Wert verwendet wird.
enabled: Ein boolescher Wert, der bestimmt, ob der geheime Wert gelesen werden kann.
notBefore: Ein bestimmtes Datum, nach dem der geheime Wert abgerufen werden kann.
expiresOn: Ein bestimmtes Datum, nach dem der geheime Wert nicht abgerufen werden kann.

Ein Objekt mit diesen Attributen kann wie folgt als dritter Parameter von setSecretgesendet werden:

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

Dadurch wird eine neue Version desselben geheimen Schlüssels erstellt, die über die neuesten bereitgestellten Attribute verfügt.

Attribute können auch mit updateSecretPropertiesauf eine vorhandene geheime Version aktualisiert werden:

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

Löschen eines Geheimnisses

Die beginDeleteSecret-Methode startet das Löschen eines geheimen Schlüssels. Dieser Vorgang erfolgt im Hintergrund, sobald die erforderlichen Ressourcen verfügbar sind.

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

Wenn vorläufig gelöschte für den Key Vault aktiviert ist, bezeichnet dieser Vorgang nur den geheimen Schlüssel als gelöschten geheimen Schlüssels. Ein gelöschter geheimer Schlüssel kann nicht aktualisiert werden. Sie können nur gelesen, wiederhergestellt oder gelöscht werden.

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

Da Secrets einige Zeit in Anspruch nehmen, um vollständig gelöscht zu werden, gibt beginDeleteSecret ein Poller-Objekt zurück, das den zugrunde liegenden Long Running Operation gemäß unseren Richtlinien nachverfolgt: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Der empfangene Abrufer ermöglicht Es Ihnen, den gelöschten geheimen Schlüssel durch Aufrufen von poller.getResult()abzurufen. Sie können auch warten, bis der Löschvorgang abgeschlossen ist, entweder durch Ausführen einzelner Dienstaufrufe, bis der geheime Schlüssel gelöscht wird, oder indem Sie warten, bis der Vorgang abgeschlossen ist:

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

Eine weitere Möglichkeit, zu warten, bis der geheime Schlüssel vollständig gelöscht wird, besteht darin, einzelne Anrufe wie folgt zu erledigen:

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

Durchlaufen von Listen mit geheimen Schlüsseln

Mit dem SecretClient können Sie alle geheimen Schlüssel in einem Schlüsseltresor sowie alle gelöschten Geheimschlüssel und die Versionen eines bestimmten geheimen Schlüssels abrufen und durchlaufen. Die folgenden API-Methoden sind verfügbar:

listPropertiesOfSecrets listet alle nicht gelöschten geheimen Schlüssel anhand ihrer Namen nur auf deren neuesten Versionen auf.
listDeletedSecrets listet alle gelöschten geheimen Schlüssel anhand ihrer Namen nur auf deren neuesten Versionen auf.
listPropertiesOfSecretVersions listet alle Versionen eines geheimen Schlüssels basierend auf einem geheimen Namen auf.

Dies kann wie folgt verwendet werden:

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

Alle diese Methoden geben alle verfügbaren Ergebnisse gleichzeitig zurück. Um sie nach Seiten abzurufen, fügen Sie .byPage() direkt nach dem Aufrufen der API-Methode hinzu, die Sie verwenden möchten, wie folgt:

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

Problembehandlung

Weitere Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie in unserem Anleitung zur Problembehandlung.

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

Nächste Schritte

Weitere Codebeispiele finden Sie über die folgenden Links:

Mitarbeit

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.

Feedback

War diese Seite hilfreich?

Last updated on 2025-06-13