Azure Key Vault Secret-Clientbibliothek für JavaScript – Version 4.8.0

  • Artikel

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

Mit azure Key Vault Secrets Management können Sie den Zugriff auf Token, Kennwörter, Zertifikate, API-Schlüssel und andere Geheimnisse sicher speichern und kontrollieren.

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

  • Abrufen, Festlegen und Löschen von Geheimnissen.
  • Aktualisieren Sie ein Geheimnis und seine Attribute.
  • Sichern und Wiederherstellen eines Geheimnisses
  • Abrufen, Bereinigen oder Wiederherstellen eines gelöschten Geheimnisses.
  • Rufen Sie alle Versionen eines Geheimnisses ab.
  • Alle Geheimnisse abrufen.
  • Rufen Sie alle gelöschten Geheimnisse 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

Die derzeitig unterstützten Umgebungen

Voraussetzungen

Installieren des Pakets

Installieren Sie die Azure Key Vault Secret-Clientbibliothek mithilfe von npm:

npm install @azure/keyvault-secrets

Installieren der Identitätsbibliothek

Key Vault Clients authentifizieren sich mithilfe der Azure Identity Library. Installieren Sie es 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 in Ihrem tsconfig.json aktivieren compilerOptions.allowSyntheticDefaultImports . Beachten Sie, dass , allowSyntheticDefaultImports wenn Sie aktiviert compilerOptions.esModuleInterophaben, standardmäßig aktiviert ist. Weitere Informationen finden Sie im Handbuch für Compileroptionen von TypeScript .

Wichtige Begriffe

  • Der Geheimclient ist die primäre Schnittstelle für die Interaktion mit den API-Methoden im Zusammenhang mit Geheimnissen in der Azure Key Vault-API aus einer JavaScript-Anwendung. Nach der Initialisierung stellt es einen grundlegenden Satz von Methoden bereit, die zum Erstellen, Lesen, Aktualisieren und Löschen von Geheimnissen verwendet werden können.
  • Eine Geheimnisversion ist eine Version eines Geheimnisses im Key Vault. Jedes Mal, wenn ein Benutzer einem eindeutigen Geheimnisnamen einen Wert zuweist, wird eine neue Version dieses Geheimnisses erstellt. Beim Abrufen eines Geheimnisses durch einen Namen wird immer der zuletzt zugewiesene Wert zurückgegeben, es sei denn, die Abfrage wird mit einer bestimmten Version versehen.
  • Vorläufiges Löschen ermöglicht es Key Vaults, das Löschen und Löschen in zwei separaten Schritten zu unterstützen, sodass gelöschte Geheimnisse nicht sofort verloren gehen. Dies geschieht nur, wenn für die Key Vault vorläufiges Löschen aktiviert ist.
  • Eine geheime Sicherung kann aus jedem erstellten Geheimnis generiert werden. Diese Sicherungen werden als Binärdaten verwendet und können nur verwendet werden, um ein zuvor gelöschtes Geheimnis neu zu generieren.

Authentifizieren mit Azure Active Directory

Der Key Vault-Dienst verwendet Azure Active Directory, um Anforderungen an seine APIs zu authentifizieren. Das @azure/identity Paket bietet eine Vielzahl von Anmeldeinformationstypen, die Ihre Anwendung dazu verwenden kann. Die INFOdatei 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 instance der SecretClient Klasse, eine Tresor-URL und ein Anmeldeinformationsobjekt erstellen. Die in diesem Dokument gezeigten Beispiele verwenden ein Anmeldeinformationsobjekt namens DefaultAzureCredential, das für die meisten Szenarien geeignet ist, einschließlich lokaler Entwicklungs- und Produktionsumgebungen. Darüber hinaus wird die Verwendung einer verwalteten Identität für die Authentifizierung in Produktionsumgebungen empfohlen.

Weitere Informationen zu verschiedenen Authentifizierungsmethoden und den entsprechenden Anmeldeinformationstypen finden Sie in der Dokumentation zu Azure Identity.

Hier sehen Sie ein kurzes Beispiel. Importieren DefaultAzureCredential Sie zunächst und SecretClient:

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

Sobald diese importiert wurden, können wir als nächstes eine Verbindung mit dem Key Vault-Dienst herstellen:

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

Angeben der Azure Key Vault-Dienst-API-Version

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

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

Beispiele

Die folgenden Abschnitte enthalten Codeausschnitte, die einige der häufigen Aufgaben mit Azure Key Vault Secrets behandeln. Die hier behandelten Szenarien bestehen aus:

Erstellen und Festlegen eines Geheimnisses

setSecret weist dem angegebenen Geheimnisnamen einen angegebenen Wert zu. Wenn bereits ein Geheimnis mit demselben Namen vorhanden ist, wird eine neue Version des Geheimnisses erstellt.

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

Abrufen eines Geheimnisses

Die einfachste Möglichkeit zum Zurücklesen von Geheimnissen aus dem Tresor besteht darin, ein Geheimnis anhand des Namens abzurufen. Dadurch wird die neueste Version des Geheimnisses abgerufen. Sie können optional eine andere Version des Schlüssels abrufen, wenn Sie ihn als Teil der optionalen Parameter angeben.

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

Erstellen und Aktualisieren von Geheimnissen mit Attributen

Ein Geheimnis kann mehr Informationen als sein Name und seinen Wert enthalten. Sie können auch die folgenden Attribute enthalten:

  • tags: Beliebiger Satz von Schlüsselwerten, die zum Suchen und Filtern von Geheimnissen verwendet werden können.
  • contentType: Jede Zeichenfolge, die verwendet werden kann, um dem Empfänger des Geheimnisses zu helfen, zu verstehen, wie der Geheimniswert verwendet wird.
  • enabled: Ein boolescher Wert, der bestimmt, ob der Geheimwert gelesen werden kann oder nicht.
  • notBefore: Ein bestimmtes Datum, nach dem der Geheimwert abgerufen werden kann.
  • expiresOn: Ein bestimmtes Datum, nach dem der Geheimwert nicht abgerufen werden kann.

Ein Objekt mit diesen Attributen kann wie folgt als dritter Parameter von setSecretgesendet werden, direkt nach dem Namen und Wert des Geheimnisses:

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

Dadurch wird eine neue Version desselben Geheimnisses erstellt, die über die zuletzt bereitgestellten Attribute verfügt.

Attribute können auch wie folgt auf eine vorhandene geheime Version mit updateSecretPropertiesaktualisiert werden:

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

Löschen eines Geheimnisses

Die beginDeleteSecret -Methode beginnt mit dem Löschen eines Geheimnisses. Dieser Prozess erfolgt im Hintergrund, sobald die erforderlichen Ressourcen verfügbar sind.

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

Wenn vorläufiges Löschen für die Key Vault aktiviert ist, wird das Geheimnis durch diesen Vorgang nur als gelöschtes Geheimnis bezeichnet. Ein gelöschtes Geheimnis kann nicht aktualisiert werden. Sie können nur gelesen, wiederhergestellt oder gelöscht werden.

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

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

Mit dem empfangenen Abfrageprogramm können Sie das gelöschte Geheimnis abrufen, indem Sie aufrufen poller.getResult(). Sie können auch warten, bis der Löschvorgang abgeschlossen ist, entweder indem Sie einzelne Dienstaufrufe ausführen, bis das Geheimnis gelöscht wird, oder indem Sie warten, bis der Vorgang abgeschlossen ist:

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

Eine weitere Möglichkeit, zu warten, bis das Geheimnis vollständig gelöscht ist, besteht darin, einzelne Aufrufe wie folgt auszuführen:

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

Durchlaufen von Geheimnislisten

Mithilfe des SecretClient können Sie alle Geheimnisse in einem Key Vault sowie alle gelöschten Geheimnisse und die Versionen eines bestimmten Geheimnisses abrufen und durchlaufen. Die folgenden API-Methoden sind verfügbar:

  • listPropertiesOfSecrets listet alle ihre nicht gelöschten Geheimnisse nur in den neuesten Versionen nach ihren Namen auf.
  • listDeletedSecrets listet alle gelöschten Geheimnisse nur in den neuesten Versionen mit ihren Namen auf.
  • listPropertiesOfSecretVersions listet alle Versionen eines Geheimnisses basierend auf einem Geheimnisnamen auf.

Diese kann wie folgt verwendet werden:

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

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

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

Problembehandlung

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

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel in @azure/logger aufrufen:

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

setLogLevel("info");

Nächste Schritte

Weitere Codebeispiele finden Sie unter den folgenden Links:

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.

Aufrufe