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

  • Artikel

Azure Key Vault ist ein Clouddienst, der eine sichere Speicherung und automatisierte Verwaltung von Zertifikaten ermöglicht, die in einer Cloudanwendung verwendet werden. Mehrere Zertifikate und mehrere Versionen desselben Zertifikats können im Azure-Key Vault beibehalten werden. Jedem Zertifikat im Tresor ist eine Richtlinie zugeordnet, die die Ausstellung und Lebensdauer des Zertifikats sowie Aktionen steuert, die als Zertifikate kurz vor Ablauf ausgeführt werden sollen.

Wenn Sie mehr über Azure Key Vault erfahren möchten, sollten Sie folgendes lesen: Was ist Azure Key Vault?

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

  • Abrufen, Festlegen und Löschen eines Zertifikats.
  • Aktualisieren Eines Zertifikats, seiner Attribute, des Ausstellers, der Richtlinie, des Vorgangs und der Kontakte.
  • Sichern und Wiederherstellen eines Zertifikats
  • Abrufen, Bereinigen oder Wiederherstellen eines gelöschten Zertifikats.
  • Ruft alle Versionen eines Zertifikats ab.
  • Rufen Sie alle Zertifikate ab.
  • Ruft alle gelöschten Zertifikate ab.

Hinweis: Dieses Paket kann aufgrund von Einschränkungen des Azure Key Vault-Diensts 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 der Azure Key Vault Certificates-Clientbibliothek mithilfe von npm

npm install @azure/keyvault-certificates

Installieren der Identitätsbibliothek

Key Vault Clients sich mithilfe der Azure-Identitätsbibliothek authentifizieren. 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, wenn Sie aktiviert compilerOptions.esModuleInterophaben, allowSyntheticDefaultImports standardmäßig aktiviert ist. Weitere Informationen finden Sie im Handbuch für Compileroptionen von TypeScript .

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 CertificateClient -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 Sie DefaultAzureCredential zunächst und CertificateClient:

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

Nachdem diese importiert wurden, können wir als Nächstes eine Verbindung mit dem Schlüsseltresordienst herstellen:

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

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 certificates client and connect to the service
const client = new CertificateClient(url, credential);

Wichtige Begriffe

  • Der Zertifikate-Client ist die primäre Schnittstelle für die Interaktion mit den API-Methoden im Zusammenhang mit Zertifikaten in der Azure Key Vault-API aus einer JavaScript-Anwendung. Nach der Initialisierung werden grundlegende Methoden bereitgestellt, die zum Erstellen, Lesen, Aktualisieren und Löschen von Zertifikaten verwendet werden können.
  • Eine Zertifikatversion ist eine Version eines Zertifikats im Key Vault. Jedes Mal, wenn ein Benutzer einem eindeutigen Zertifikatnamen einen Wert zuweist, wird eine neue Version dieses Zertifikats erstellt. Das Abrufen eines Zertifikats nach einem Namen gibt immer den zuletzt zugewiesenen Wert zurück, es sei denn, eine bestimmte Version wird für die Abfrage bereitgestellt.
  • Vorläufiges Löschen ermöglicht es Key Vaults, das Löschen und Löschen als zwei separate Schritte zu unterstützen, sodass gelöschte Zertifikate nicht sofort verloren gehen. Dies geschieht nur, wenn für die Key Vault vorläufiges Löschen aktiviert ist.
  • Eine Zertifikatsicherung kann aus jedem erstellten Zertifikat generiert werden. Diese Sicherungen sind binärdaten und können nur verwendet werden, um ein zuvor gelöschtes Zertifikat erneut zu generieren.

Angeben der API-Version des Azure Key Vault-Diensts

Standardmäßig verwendet dieses Paket die neueste Azure Key Vault-Dienstversion, die ist7.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 { CertificateClient } = require("@azure/keyvault-certificates");

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 CertificateClient(url, credential, {
  serviceVersion: "7.0",
});

Beispiele

Die folgenden Abschnitte enthalten Codeausschnitte, die einige der allgemeinen Aufgaben mit Azure Key Vault Certificates behandeln. Die szenarien, die hier behandelt werden, bestehen aus:

Erstellen und Festlegen eines Zertifikats

beginCreateCertificateerstellt ein Zertifikat, das im Azure-Key Vault gespeichert werden soll. Wenn bereits ein Zertifikat mit demselben Namen vorhanden ist, wird eine neue Version des Zertifikats erstellt.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  // Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
  await client.beginCreateCertificate(certificateName, {
    issuerName: "Self",
    subject: "cn=MyCert",
  });
}

main();

Neben dem Namen des Zertifikats und der Richtlinie können Sie auch die folgenden Eigenschaften in einem dritten Argument mit optionalen Werten übergeben:

  • enabled: Ein boolescher Wert, der bestimmt, ob das Zertifikat verwendet werden kann oder nicht.
  • tags: Beliebiger Satz von Schlüssel-Werten, die zum Durchsuchen und Filtern von Zertifikaten verwendet werden können.
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};
const enabled = true;
const tags = {
  myCustomTag: "myCustomTagsValue",
};

async function main() {
  await client.beginCreateCertificate(certificateName, certificatePolicy, {
    enabled,
    tags,
  });
}

main();

Wenn Sie mit demselben Namen aufrufen, beginCreateCertificate wird eine neue Version desselben Zertifikats erstellt, das über die zuletzt bereitgestellten Attribute verfügt.

Da die vollständige Erstellung von Zertifikaten einige Zeit in Anspruch nimmt, wird ein Abrufobjekt zurückgegeben, beginCreateCertificate das den zugrunde liegenden lang andauernden Vorgang gemäß unseren Richtlinien nachverfolgt: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Mit dem empfangenen Abrufprogramm können Sie das erstellte Zertifikat abrufen, indem Sie aufrufen poller.getResult(). Sie können auch warten, bis der Löschvorgang abgeschlossen ist, indem Sie entweder einzelne Dienstaufrufe ausführen, bis das Zertifikat erstellt wird, oder indem Sie warten, bis der Prozess abgeschlossen ist:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

async function main() {
  const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

  // You can use the pending certificate immediately:
  const pendingCertificate = poller.getResult();

  // Or you can wait until the certificate finishes being signed:
  const keyVaultCertificate = await poller.pollUntilDone();
  console.log(keyVaultCertificate);
}

main();

Eine weitere Möglichkeit, zu warten, bis das Zertifikat signiert ist, besteht darin, einzelne Aufrufe wie folgt auszuführen:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
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 CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

async function main() {
  const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

  while (!poller.isDone()) {
    await poller.poll();
    await delay(5000);
  }

  console.log(`The certificate ${certificateName} is fully created`);
}

main();

Abrufen eines Key Vault-Zertifikats

Die einfachste Möglichkeit, Zertifikate aus dem Tresor zurückzulesen, besteht darin, ein Zertifikat anhand des Namens abzurufen. getCertificate ruft die neueste Version des Zertifikats zusammen mit der Zertifikatrichtlinie ab. Sie können optional eine andere Version des Zertifikats abrufen, indem Sie aufrufen getCertificateVersion , wenn Sie die Version angeben. getCertificateVersion gibt die Richtlinie des Zertifikats nicht zurück.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const latestCertificate = await client.getCertificate(certificateName);
  console.log(`Latest version of the certificate ${certificateName}: `, latestCertificate);
  const specificCertificate = await client.getCertificateVersion(
    certificateName,
    latestCertificate.properties.version
  );
  console.log(
    `The certificate ${certificateName} at the version ${latestCertificate.properties.version}: `,
    specificCertificate
  );
}

main();

Abrufen der vollständigen Informationen eines Zertifikats

Der Entwurf von Azure Key Vault unterscheidet deutlich zwischen Schlüsseln, Geheimnissen und Zertifikaten. Die Zertifikatfeatures des Key Vault Diensts wurden unter Verwendung der Schlüssel- und Geheimnisfunktionen entwickelt. Im Folgenden wird die Zusammensetzung eines Key Vault-Zertifikats ausgewertet:

Wenn ein Key Vault-Zertifikat erstellt wird, werden auch ein adressierbarer Schlüssel und ein Geheimnis gleichen Namens erstellt. Der Key Vault-Schlüssel ermöglicht Schlüsselvorgänge, und das Key Vault-Geheimnis ermöglicht den Abruf des Zertifikatwerts als Geheimnis. Ein Key Vault-Zertifikat enthält auch öffentliche X509-Zertifikatmetadaten. Quelle: Zusammensetzung eines Zertifikats.

Da wir wissen, dass der private Schlüssel in einem Key Vault Geheimnis gespeichert ist und das öffentliche Zertifikat enthalten ist, können wir ihn mithilfe des Key Vault Secrets-Clients abrufen.

// Using the same credential object we used before,
// and the same keyVaultUrl,
// let's create a SecretClient
import { SecretClient } from "@azure/keyvault-secrets";

const secretClient = new SecretClient(keyVaultUrl, credential);

// Assuming you've already created a Key Vault certificate,
// and that certificateName contains the name of your certificate
const certificateSecret = await secretClient.getSecret(certificateName);

// Here we can find both the private key and the public certificate, in PKCS 12 format:
const PKCS12Certificate = certificateSecret.value!;

// You can write this into a file:
fs.writeFileSync("myCertificate.p12", PKCS12Certificate);

Beachten Sie, dass der Inhaltstyp der Zertifikate standardmäßig PKCS 12 ist. Wenn Sie den Inhaltstyp Ihres Zertifikats angeben, können Sie es im PEM-Format abrufen. Bevor Sie zeigen, wie PEM-Zertifikate erstellt werden, sehen wir uns zunächst an, wie Sie zuerst einen geheimen PEM-Schlüssel aus einem PKCS 12-Zertifikat abrufen.

Mit opensslkönnen Sie das öffentliche Zertifikat im PEM-Format mit dem folgenden Befehl abrufen:

openssl pkcs12 -in myCertificate.p12 -out myCertificate.crt.pem -clcerts -nokeys

Sie können auch verwenden openssl , um den privaten Schlüssel wie folgt abzurufen:

openssl pkcs12 -in myCertificate.p12 -out myCertificate.key.pem -nocerts -nodes

Beachten Sie, dass openssl Sie in beiden Fällen nach dem Kennwort zum Erstellen des Zertifikats fragt. Der bisher verwendete Beispielcode hat kein Kennwort angegeben, sodass Sie an das Ende jedes Befehls anfügen -passin 'pass:' können.

Zertifikate im PEM-Format

Wenn Sie mit Zertifikaten im PEM-Format arbeiten möchten, können Sie den Key Vault Dienst von Azure anweisen, Ihre Zertifikate im PEM-Format zu erstellen und zu verwalten, indem Sie die contentType -Eigenschaft zum Zeitpunkt der Erstellung der Zertifikate angeben.

Das folgende Beispiel zeigt, wie Sie die öffentlichen und privaten Teile eines PEM-formatierten Zertifikats mithilfe der Key Vault Clients für Zertifikate und Geheimnisse erstellen und abrufen:

// Creating the certificate
const certificateName = "MyCertificate";
const createPoller = await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
  contentType: "application/x-pem-file", // Here you specify you want to work with PEM certificates.
});
const keyVaultCertificate = await createPoller.pollUntilDone();

// Getting the PEM formatted private key and public certificate:
const certificateSecret = await secretClient.getSecret(certificateName);
const PEMPair = certificateSecret.value!;

console.log(PEMPair);

Beachten Sie, dass sich Ihr öffentliches Zertifikat im gleichen Inhaltsblob wie Ihr privater Schlüssel befinden wird. Sie können die PEM-Header verwenden, um sie entsprechend zu extrahieren.

Auflisten aller Zertifikate

listPropertiesOfCertificateslistet alle Zertifikate im Key Vault auf.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

async function main() {
  for await (let certificateProperties of client.listPropertiesOfCertificates()) {
    console.log("Certificate properties: ", certificateProperties);
  }
}

main();

Aktualisieren eines Zertifikats

Die Zertifikatattribute können wie folgt auf eine vorhandene Zertifikatversion mit updateCertificateaktualisiert werden:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const result = await client.getCertificate(certificateName);
  await client.updateCertificateProperties(certificateName, result.properties.version, {
    enabled: false,
    tags: {
      myCustomTag: "myCustomTagsValue",
    },
  });
}

main();

Die Zertifikatrichtlinie kann auch wie folgt einzeln mit updateCertificatePolicyaktualisiert werden:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const result = client.getCertificate(certificateName);
  // Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
  await client.updateCertificatePolicy(certificateName, {
    issuerName: "Self",
    subject: "cn=MyCert",
  });
}

main();

Löschen eines Zertifikats

Die beginDeleteCertificate -Methode legt ein Zertifikat zum Löschen fest. Dieser Prozess erfolgt im Hintergrund, sobald die erforderlichen Ressourcen verfügbar sind.

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

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const poller = await client.beginDeleteCertificate(certificateName);

  // You can use the deleted certificate immediately:
  const deletedCertificate = poller.getResult();

  // The certificate 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 certificate this way:
  await client.getDeletedCertificate(certificateName);

  // Deleted certificates can also be recovered or purged.

  // recoverDeletedCertificate returns a poller, just like beginDeleteCertificate.
  // const recoverPoller = await client.beginRecoverDeletedCertificate(certificateName);
  // await recoverPoller.pollUntilDone();

  // If a certificate is done and the Key Vault has soft-delete enabled, the certificate can be purged with:
  await client.purgeDeletedCertificate(certificateName);
}

main();

Da das Löschen eines Zertifikats nicht sofort erfolgt, ist nach dem Aufruf der beginDeleteCertificate Methode einige Zeit erforderlich, bevor das gelöschte Zertifikat gelesen, wiederhergestellt oder gelöscht werden kann.

Durchlaufen von Zertifikatlisten

Mit dem CertificateClient können Sie alle Zertifikate in einem Zertifikattresor sowie alle gelöschten Zertifikate und die Versionen eines bestimmten Zertifikats abrufen und durchlaufen. Die folgenden API-Methoden sind verfügbar:

  • listPropertiesOfCertificates listet alle nicht gelöschten Zertifikate nur in den neuesten Versionen mit ihren Namen auf.
  • listDeletedCertificates listet alle gelöschten Zertifikate nur in den neuesten Versionen mit ihren Namen auf.
  • listPropertiesOfCertificateVersions listet alle Versionen eines Zertifikats basierend auf einem Zertifikatnamen auf.

Diese kann wie folgt verwendet werden:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  for await (let certificateProperties of client.listPropertiesOfCertificates()) {
    console.log("Certificate properties: ", certificateProperties);
  }
  for await (let deletedCertificate of client.listDeletedCertificates()) {
    console.log("Deleted certificate: ", deletedCertificate);
  }
  for await (let certificateProperties of client.listPropertiesOfCertificateVersions(
    certificateName
  )) {
    console.log("Certificate properties: ", certificateProperties);
  }
}

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 { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  for await (let page of client.listPropertiesOfCertificates().byPage()) {
    for (let certificateProperties of page) {
      console.log("Certificate properties: ", certificateProperties);
    }
  }
  for await (let page of client.listDeletedCertificates().byPage()) {
    for (let deletedCertificate of page) {
      console.log("Deleted certificate: ", deletedCertificate);
    }
  }
  for await (let page of client.listPropertiesOfCertificateVersions(certificateName).byPage()) {
    for (let certificateProperties of page) {
      console.log("Properties of certificate: ", certificateProperties);
    }
  }
}

main();

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

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

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