Freigeben über


Schnellstart: Azure Key Vault-Zertifikatclientbibliothek für JavaScript

Hier finden Sie Informationen zu den ersten Schritten mit der Azure Key Vault-Zertifikatclientbibliothek für JavaScript. Azure Key Vault ist ein Clouddienst, der als sicherer Speicher für Zertifikate fungiert. Dadurch können Schlüssel, Kennwörter, Zertifikate und andere Geheimnisse sicher gespeichert werden. Azure Key Vault-Instanzen können über das Azure-Portal erstellt und verwaltet werden. In dieser Schnellstartanleitung erfahren Sie, wie Sie mithilfe der JavaScript-Clientbibliothek Zertifikate in einem Azure-Schlüsseltresor erstellen, daraus abrufen und löschen.

Ressourcen der Key Vault-Clientbibliothek:

API-Referenzdokumentation | Quellcode der Bibliothek | Paket (npm)

Weitere Informationen zu Key Vault und Zertifikaten finden Sie unter folgenden Links:

Voraussetzungen

In diesem Schnellstart wird davon ausgegangen, dass Sie die Azure CLI ausführen.

Anmelden bei Azure

  1. Führen Sie den Befehl login aus.

    az login
    

    Die CLI öffnet Ihren Standardbrowser, sofern sie dazu in der Lage ist, und lädt eine Azure-Anmeldeseite.

    Öffnen Sie andernfalls die Browserseite https://aka.ms/devicelogin, und geben Sie den in Ihrem Terminal angezeigten Autorisierungscode ein.

  2. Melden Sie sich im Browser mit Ihren Anmeldeinformationen an.

Erstellen einer neuen Node.js-Anwendung

Erstellen Sie eine Node.js-Anwendung, die Ihren Schlüsseltresor verwendet.

  1. Erstellen Sie in einem Terminal einen Ordner namens key-vault-node-app und wechseln Sie in diesen Ordner:

    mkdir key-vault-node-app && cd key-vault-node-app
    
  2. Initialisieren Sie das Node.js-Projekt:

    npm init -y
    

Installieren von Key Vault-Paketen

  1. Installieren Sie über das Terminal die Azure Key Vault secrets library, @azure/keyvault-certificates für Node.js.

    npm install @azure/keyvault-certificates
    
  2. Installieren Sie die Azure Identity-Clientbibliothek, @azure/identity, um sich bei Key Vault zu authentifizieren.

    npm install @azure/identity
    

Gewähren des Zugriffs auf Ihren Schlüsseltresor

Um Ihrem Benutzerprinzipalnamen (User Principal Name, UPN) über die rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) Berechtigungen für Ihren Schlüsseltresor zu gewähren, weisen Sie ihm mithilfe des Azure CLI-Befehls az role assignment create eine Rolle zu.

az role assignment create --role "Key Vault Certificate Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Ersetzen Sie <upn>, <subscription-id>, <resource-group-name> und <your-unique-keyvault-name> durch Ihre tatsächlichen Werte. Ihr Benutzerprinzipalname (UPN) hat in der Regel das Format einer E-Mail-Adresse (z. B. username@domain.com).

Festlegen von Umgebungsvariablen

Diese Anwendung verwendet den Namen des Schlüsseltresors als Umgebungsvariable namens KEY_VAULT_URL.

set KEY_VAULT_URL=<your-key-vault-endpoint>

Authentifizieren und Erstellen eines Clients

Anwendungsanforderungen an die meisten Azure-Dienste müssen autorisiert werden. Die Verwendung der von der Azure-Identitätsclientbibliothek bereitgestellten Methode DefaultAzureCredential ist der empfohlene Ansatz zum Implementieren von kennwortlosen Verbindungen mit Azure-Diensten in Ihrem Code. DefaultAzureCredential unterstützt mehrere Authentifizierungsmethoden und bestimmt, welche Methode zur Laufzeit verwendet werden soll. Bei diesem Ansatz kann Ihre App unterschiedliche Authentifizierungsmethoden in verschiedenen Umgebungen (lokal gegenüber Produktion) verwenden, ohne umgebungsspezifischen Code zu implementieren.

In dieser Schnellstartanleitung authentifiziert sich DefaultAzureCredential mit den Anmeldeinformationen des lokalen Entwicklungsbenutzers, der bei der Azure CLI angemeldet ist, beim Schlüsseltresor. Wenn die Anwendung in Azure bereitgestellt wird, kann derselbe DefaultAzureCredential-Code automatisch eine verwaltete Identität ermitteln und verwenden, die App Service, einem virtuellen Computer oder anderen Diensten zugewiesen ist. Weitere Informationen finden Sie in der Übersicht zu verwalteten Identitäten.

In diesem Code wird der Endpunkt Ihres Schlüsseltresors verwendet, um den Schlüsseltresorclient zu erstellen. Das Endpunktformat sieht wie https://<your-key-vault-name>.vault.azure.net aus, kann sich jedoch für souveräne Clouds ändern. Weitere Informationen zur Authentifizierung beim Schlüsseltresor finden Sie im Entwicklerhandbuch.

Codebeispiel

Dieser Code verwendet die folgenden Key Vault-Zertifikatklassen und -methoden:

Einrichten des App-Frameworks

  • Erstellen Sie eine neue Textdatei und fügen Sie den folgenden Code in die Datei index.js ein.

    const { CertificateClient, DefaultCertificatePolicy } = require("@azure/keyvault-certificates");
    const { DefaultAzureCredential } = require("@azure/identity");
    
    async function main() {
      // If you're using MSI, DefaultAzureCredential should "just work".
      // Otherwise, DefaultAzureCredential expects the following three environment variables:
      // - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
      // - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
      // - AZURE_CLIENT_SECRET: The client secret for the registered application
      const credential = new DefaultAzureCredential();
    
      const keyVaultUrl = process.env["KEY_VAULT_URL"];
      if(!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");
    
      const client = new CertificateClient(keyVaultUrl, credential);
    
      const uniqueString = new Date().getTime();
      const certificateName = `cert${uniqueString}`;
    
      // Creating a self-signed certificate
      const createPoller = await client.beginCreateCertificate(
        certificateName,
        DefaultCertificatePolicy
      );
    
      const pendingCertificate = createPoller.getResult();
      console.log("Certificate: ", pendingCertificate);
    
      // To read a certificate with their policy:
      let certificateWithPolicy = await client.getCertificate(certificateName);
      // Note: It will always read the latest version of the certificate.
    
      console.log("Certificate with policy:", certificateWithPolicy);
    
      // To read a certificate from a specific version:
      const certificateFromVersion = await client.getCertificateVersion(
        certificateName,
        certificateWithPolicy.properties.version
      );
      // Note: It will not retrieve the certificate's policy.
      console.log("Certificate from a specific version:", certificateFromVersion);
    
      const updatedCertificate = await client.updateCertificateProperties(certificateName, "", {
        tags: {
          customTag: "value"
        }
      });
      console.log("Updated certificate:", updatedCertificate);
    
      // Updating the certificate's policy:
      await client.updateCertificatePolicy(certificateName, {
        issuerName: "Self",
        subject: "cn=MyOtherCert"
      });
      certificateWithPolicy = await client.getCertificate(certificateName);
      console.log("updatedCertificate certificate's policy:", certificateWithPolicy.policy);
    
      // delete certificate
      const deletePoller = await client.beginDeleteCertificate(certificateName);
      const deletedCertificate = await deletePoller.pollUntilDone();
      console.log("Recovery Id: ", deletedCertificate.recoveryId);
      console.log("Deleted Date: ", deletedCertificate.deletedOn);
      console.log("Scheduled Purge Date: ", deletedCertificate.scheduledPurgeDate);
    }
    
    main().catch((error) => {
      console.error("An error occurred:", error);
      process.exit(1);
    });
    

Ausführen der Beispielanwendung

  1. Führen Sie die App aus:

    node index.js
    
  2. Die Methoden create und get geben ein vollständiges JSON-Objekt für das Zertifikat zurück:

    {
      "keyId": undefined,
      "secretId": undefined,
      "name": "YOUR-CERTIFICATE-NAME",
        "reuseKey": false,
        "keyCurveName": undefined,
        "exportable": true,
        "issuerName": 'Self',
        "certificateType": undefined,
        "certificateTransparency": undefined
      },
      "properties": {
        "createdOn": 2021-11-29T20:17:45.000Z,
        "updatedOn": 2021-11-29T20:17:45.000Z,
        "expiresOn": 2022-11-29T20:17:45.000Z,
        "id": "https://YOUR-KEY-VAULT-NAME-ENDPOINT/certificates/YOUR-CERTIFICATE-NAME/YOUR-CERTIFICATE-VERSION",
        "enabled": false,
        "notBefore": 2021-11-29T20:07:45.000Z,
        "recoveryLevel": "Recoverable+Purgeable",
        "name": "YOUR-CERTIFICATE-NAME",
        "vaultUrl": "https://YOUR-KEY-VAULT-NAME-ENDPOINT",
        "version": "YOUR-CERTIFICATE-VERSION",
        "tags": undefined,
        "x509Thumbprint": undefined,
        "recoverableDays": 90
      }
    }
    
  • Erstellen Sie eine neue Textdatei, und fügen Sie den folgenden Code in die Datei index.js ein.

    import {
      CertificateClient,
      DefaultCertificatePolicy,
      KeyVaultCertificate,
      DeletedCertificate,
      CertificatePolicy,
      KeyVaultCertificateWithPolicy,
    } from "@azure/keyvault-certificates";
    import { DefaultAzureCredential } from "@azure/identity";
    import "dotenv/config";
    
    const credential = new DefaultAzureCredential();
    
    // Get Key Vault name from environment variables
    // such as `https://${keyVaultName}.vault.azure.net`
    const keyVaultUrl = process.env.KEY_VAULT_URL;
    if (!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");
    
    function printCertificate(
      certificate: KeyVaultCertificate | KeyVaultCertificateWithPolicy
    ): void {
      console.log("-- printCertificate ---------------------------");
    
      // if policy is defined, it's a KeyVaultCertificateWithPolicy
      if ((certificate as KeyVaultCertificateWithPolicy).policy) {
        const { name, properties, policy } =
          certificate as KeyVaultCertificateWithPolicy;
        const { createdOn, updatedOn, expiresOn, vaultUrl, version, tags } =
          properties;
        console.log("Certificate: ", {
          name,
          createdOn,
          updatedOn,
          expiresOn,
          vaultUrl,
          version,
        });
        console.log("Certificate Policy: ", policy);
        printObjectProperties(tags);
        return;
      } else {
        const { name, properties } = certificate;
        const { createdOn, updatedOn, expiresOn, vaultUrl, version, tags } =
          properties;
        console.log("Certificate: ", {
          name,
          createdOn,
          updatedOn,
          expiresOn,
          vaultUrl,
          version,
        });
        printObjectProperties(tags);
      }
    }
    // Object properties are tags and CertificatePolicy
    function printObjectProperties(obj: Record<string, any>): void {
      if (!obj) return;
    
      console.log("-- printObjectProperties ---------------------------");
    
      Object.entries(obj).forEach(([key, value]) => {
        if (key === "lifetimeActions") {
          console.log(`${key}: ${JSON.stringify(value)}`);
        } else {
          console.log(`${key}: ${value}`);
        }
      });
    }
    function printDeletedCertificate(deletedCertificate: DeletedCertificate): void {
      const { recoveryId, deletedOn, scheduledPurgeDate } = deletedCertificate;
      console.log("Deleted Certificate: ", {
        recoveryId,
        deletedOn,
        scheduledPurgeDate,
      });
    }
    async function main(): Promise<void> {
      // Create a new CertificateClient
      const client = new CertificateClient(keyVaultUrl, credential);
    
      // Create a unique certificate name
      const uniqueString = new Date().getTime().toString();
      const certificateName = `cert${uniqueString}`;
    
      // Creating a self-signed certificate
      const createPoller = await client.beginCreateCertificate(
        certificateName,
        DefaultCertificatePolicy
      );
    
      // Get the created certificate
      const pendingCertificate = await createPoller.getResult();
      printCertificate(pendingCertificate);
    
      // Get certificate by name
      let certificateWithPolicy = await client.getCertificate(certificateName);
      printCertificate(pendingCertificate);
    
      // Get certificate by version
      const certificateFromVersion = await client.getCertificateVersion(
        certificateName,
        certificateWithPolicy.properties.version!
      );
      printCertificate(certificateFromVersion);
    
      // Update properties of the certificate
      const updatedCertificate = await client.updateCertificateProperties(
        certificateName,
        certificateWithPolicy.properties.version!,
        {
          tags: {
            customTag: "my value",
          },
        }
      );
      printCertificate(updatedCertificate);
    
      // Updating the certificate's policy
      const certificatePolicy = await client.updateCertificatePolicy(
        certificateName,
        {
          issuerName: "Self",
          subject: "cn=MyOtherCert",
        }
      );
      printObjectProperties(certificatePolicy);
    
      // Get certificate again to see the updated policy
      certificateWithPolicy = await client.getCertificate(certificateName);
      printCertificate(certificateWithPolicy);
    
      // Delete certificate
      const deletePoller = await client.beginDeleteCertificate(certificateName);
      const deletedCertificate = await deletePoller.pollUntilDone();
      printDeletedCertificate(deletedCertificate);
    }
    
    main().catch((error) => {
      console.error("An error occurred:", error);
      process.exit(1);
    });
    

Ausführen der Beispielanwendung

  1. Erstellen Sie die TypeScript-App:

    tsc
    
  2. Führen Sie die App aus:

    node index.js
    
  3. Die Methoden create und get geben ein vollständiges JSON-Objekt für das Zertifikat zurück:

    {
      "keyId": undefined,
      "secretId": undefined,
      "name": "YOUR-CERTIFICATE-NAME",
        "reuseKey": false,
        "keyCurveName": undefined,
        "exportable": true,
        "issuerName": 'Self',
        "certificateType": undefined,
        "certificateTransparency": undefined
      },
      "properties": {
        "createdOn": 2021-11-29T20:17:45.000Z,
        "updatedOn": 2021-11-29T20:17:45.000Z,
        "expiresOn": 2022-11-29T20:17:45.000Z,
        "id": "https://YOUR-KEY-VAULT-NAME-ENDPOINT/certificates/YOUR-CERTIFICATE-NAME/YOUR-CERTIFICATE-VERSION",
        "enabled": false,
        "notBefore": 2021-11-29T20:07:45.000Z,
        "recoveryLevel": "Recoverable+Purgeable",
        "name": "YOUR-CERTIFICATE-NAME",
        "vaultUrl": "https://YOUR-KEY-VAULT-NAME-ENDPOINT",
        "version": "YOUR-CERTIFICATE-VERSION",
        "tags": undefined,
        "x509Thumbprint": undefined,
        "recoverableDays": 90
      }
    }
    

Integration mit App-Konfiguration

Das Azure SDK bietet eine Hilfsmethode, parseKeyVaultCertificateIdentifier, um die angegebene Key Vault-Zertifikat-ID zu parsen, die erforderlich ist, wenn Sie App Configuration-Verweise auf Key Vault verwenden. App Config speichert die Key Vault-Zertifikats-ID. Sie benötigen die Methode parseKeyVaultCertificateIdentifier, um diese ID zu analysieren und den Zertifikatsnamen zu erhalten. Sobald Sie den Zertifikatsnamen haben, können Sie das aktuelle Zertifikat mit dem Code aus diesem Schnellstart abrufen.

Nächste Schritte

In dieser Schnellstartanleitung haben Sie einen Schlüsseltresor erstellt, ein Zertifikat gespeichert und dieses Zertifikat abgerufen. Weitere Informationen zu Key Vault und zur Integration in Ihre Anwendungen finden Sie in den folgenden Artikeln: