Freigeben über


Clientbibliothek für Azure Key Vault-Zertifikate für JavaScript – Version 4.9.0

Azure Key Vault ist ein Clouddienst, der sichere Speicherung und automatisierte Verwaltung von Zertifikaten bereitstellt, die in einer Cloudanwendung verwendet werden. Mehrere Zertifikate und mehrere Versionen desselben Zertifikats können im Azure Key Vault aufbewahrt werden. Jedes Zertifikat im Tresor verfügt über eine Richtlinie, die die Ausstellung und Lebensdauer des Zertifikats steuert, zusammen mit Aktionen, die als Zertifikate im Nahen Ablauf ausgeführt werden sollen.

Wenn Sie mehr über Azure Key Vault wissen möchten, können Sie folgendes überprüfen: Was ist Azure Key Vault?

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

  • Abrufen, Festlegen und Löschen eines Zertifikats.
  • Aktualisieren Sie ein Zertifikat, seine Attribute, Aussteller, Richtlinien, Vorgänge und Kontakte.
  • Sichern und Wiederherstellen eines Zertifikats.
  • Dient zum Abrufen, Löschen oder Wiederherstellen eines gelöschten Zertifikats.
  • Rufen Sie alle Versionen eines Zertifikats ab.
  • Abrufen aller Zertifikate.
  • Ruft alle gelöschten Zertifikate 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

Voraussetzungen

Installieren des Pakets

Installieren der Clientbibliothek für Azure Key Vault-Zertifikate mithilfe von npm

npm install @azure/keyvault-certificates

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.

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 CertificateClient 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 CertificateClient:

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

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

Schlüsselkonzepte

  • Der -Zertifikatclient 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 stellt sie einen grundlegenden Satz von Methoden bereit, 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. Wenn Sie ein Zertifikat 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 Zertifikate nicht sofort verloren gehen. Dies geschieht nur, wenn der Key Vault soft-delete aktiviert hat.
  • 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 neu zu generieren.

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:

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-Zertifikaten abdecken. Die hier behandelten Szenarien bestehen aus:

Erstellen und Festlegen eines Zertifikats

beginCreateCertificate erstellt 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: Jeder Satz von Schlüsselwerten, die zum Suchen 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();

Durch das Aufrufen von beginCreateCertificate mit demselben Namen wird eine neue Version desselben Zertifikats erstellt, die über die neuesten bereitgestellten Attribute verfügt.

Da Zertifikate einige Zeit in Anspruch nehmen, um vollständig erstellt zu werden, gibt beginCreateCertificate ein Pollerobjekt zurück, das den zugrunde liegenden Long Running-Vorgang gemäß unseren Richtlinien nachverfolgt: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Mit dem empfangenen Abrufer können Sie das erstellte Zertifikat abrufen, indem Sie poller.getResult()aufrufen. Sie können auch warten, bis der Löschvorgang abgeschlossen ist, entweder indem Sie einzelne Dienstaufrufe ausführen, bis das Zertifikat erstellt wurde, oder indem Sie warten, bis der Vorgang 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 zu erledigen:

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 zum Lesen von Zertifikaten aus dem Tresor 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 getCertificateVersion aufrufen, 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

Das Design von Azure Key Vault macht scharfe Unterscheidungen zwischen Schlüsseln, Geheimnissen und Zertifikaten. Die Zertifikatfeatures des Key Vault-Diensts wurden entwickelt, um die Schlüssel- und Geheimschlüsselfunktionen zu nutzen. Bewerten wir die Zusammensetzung eines Key Vault-Zertifikats:

Wenn ein Key Vault-Zertifikat erstellt wird, werden auch ein adressierbarer Schlüssel und geheimer Schlüssel mit demselben Namen erstellt. Der Schlüsseltresor ermöglicht Schlüsselvorgänge und der Schlüsseltresorschlüssel ermöglicht das Abrufen des Zertifikatwerts als geheimer Schlüssel. Ein Key Vault-Zertifikat enthält auch öffentliche x509-Zertifikatmetadaten. Quelle: Zusammensetzung eines Zertifikats.

Wenn Sie wissen, dass der private Schlüssel in einem Schlüsseltresorschlüssel gespeichert ist, wobei das öffentliche Zertifikat enthalten ist, können wir ihn mit dem Key Vault Secrets-Client 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. Indem Sie den Inhaltstyp Ihres Zertifikats angeben, können Sie es im PEM-Format abrufen. Bevor Sie zeigen, wie PEM-Zertifikate erstellt werden, erfahren Sie zunächst, 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 openssl verwenden, um den privaten Schlüssel wie folgt abzurufen:

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

Beachten Sie, dass sie in beiden Fällen von openssl aufgefordert werden, das Zum Erstellen des Zertifikats verwendete Kennwort einzugeben. Der beispielcode, den wir bisher verwendet haben, hat kein Kennwort angegeben, sodass Sie -passin 'pass:' am Ende jedes Befehls anfügen 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 bereitstellen.

Das folgende Beispiel zeigt, wie Sie die öffentlichen und privaten Teile eines PEM-formatierten Zertifikats mithilfe der Key Vault-Clients für Zertifikate und Geheime Schlüssel 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);

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

Alle Zertifikate auflisten

listPropertiesOfCertificates listet 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 Richtlinie des Zertifikats kann auch einzeln mit updateCertificatePolicyaktualisiert werden, wie folgt:

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 für das Löschen fest. Dieser Vorgang erfolgt im Hintergrund, sobald die erforderlichen Ressourcen verfügbar sind.

Wenn vorläufig gelöschte für den Key Vault aktiviert ist, bezeichnet dieser Vorgang das Zertifikat nur als gelöschten Zertifikats. 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, wird einige Zeit benötigt, nachdem die beginDeleteCertificate Methode aufgerufen wird, 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 über 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 anhand ihrer Namen nur auf deren neuesten Versionen auf.
  • listDeletedCertificates listet alle Gelöschten Zertifikate nur nach ihren Namen auf.
  • listPropertiesOfCertificateVersions listet alle Versionen eines Zertifikats basierend auf einem Zertifikatnamen auf.

Dies 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 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:

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

Fehlerbehebung

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

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

Nächste Schritte

Weitere Codebeispiele finden Sie über die folgenden Links:

Beitragend

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.

Aufrufe