Biblioteka klienta certyfikatów usługi Azure Key Vault dla języka JavaScript — wersja 4.9.0

Artykuł
10/17/2024

Azure Key Vault to usługa w chmurze, która zapewnia bezpieczny magazyn i zautomatyzowane zarządzanie certyfikatami używanymi w całej aplikacji w chmurze. Wiele certyfikatów i wiele wersji tego samego certyfikatu można przechowywać w usłudze Azure Key Vault. Każdy certyfikat w magazynie ma skojarzone z nim zasady, które kontrolują wystawianie i okres istnienia certyfikatu wraz z akcjami, które mają być podejmowane jako certyfikaty w pobliżu wygaśnięcia.

Jeśli chcesz dowiedzieć się więcej o usłudze Azure Key Vault, warto zapoznać się z tematem: Co to jest usługa Azure Key Vault?

Użyj biblioteki klienta dla certyfikatów usługi Azure Key Vault w aplikacji Node.js, aby:

Pobieranie, ustawianie i usuwanie certyfikatu.
Zaktualizuj certyfikat, jego atrybuty, wystawcę, zasady, operację i kontakty.
Tworzenie kopii zapasowej i przywracanie certyfikatu.
Pobieranie, przeczyszczanie lub odzyskiwanie usuniętego certyfikatu.
Pobierz wszystkie wersje certyfikatu.
Pobierz wszystkie certyfikaty.
Pobierz wszystkie usunięte certyfikaty.

Uwaga: nie można używać tego pakietu w przeglądarce z powodu ograniczeń usługi Azure Key Vault, zapoznaj się z tym dokumencie wskazówki.

Kluczowe linki:

kod źródłowy
pakiet (npm)
Dokumentacja referencyjna interfejsu API
dokumentacja produktu
przykładów

Wprowadzenie

Obecnie obsługiwane środowiska

wersje Node.js LTS

Warunki wstępne

subskrypcji platformy Azure
Istniejąca azure Key Vault. Jeśli musisz utworzyć magazyn kluczy, możesz to zrobić w witrynie Azure Portal, wykonując kroki opisane w tym dokumencie. Alternatywnie użyj interfejsu wiersza polecenia platformy Azure, wykonując tych kroków.

Instalowanie pakietu

Instalowanie biblioteki klienta certyfikatów usługi Azure Key Vault przy użyciu narzędzia npm

npm install @azure/keyvault-certificates

Instalowanie biblioteki tożsamości

Klienci usługi Key Vault uwierzytelniają się przy użyciu biblioteki tożsamości platformy Azure. Zainstaluj go również przy użyciu narzędzia npm

npm install @azure/identity

Konfigurowanie języka TypeScript

Użytkownicy języka TypeScript muszą mieć zainstalowane definicje typu węzła:

npm install @types/node

Należy również włączyć compilerOptions.allowSyntheticDefaultImports w tsconfig.json. Należy pamiętać, że jeśli włączono compilerOptions.esModuleInterop, allowSyntheticDefaultImports jest domyślnie włączona. Aby uzyskać więcej informacji, zobacz podręcznik opcje kompilatora języka TypeScript.

Uwierzytelnianie za pomocą usługi Azure Active Directory

Usługa Key Vault korzysta z usługi Azure Active Directory do uwierzytelniania żądań w swoich interfejsach API. Pakiet @azure/identity udostępnia różne typy poświadczeń, których aplikacja może użyć do tego celu. Plik README dla @azure/identity zawiera więcej szczegółów i przykładów, które ułatwiają rozpoczęcie pracy.

Aby móc korzystać z usługi Azure Key Vault, należy utworzyć wystąpienie klasy CertificateClient, adres URL magazynu i obiekt poświadczeń. Przykłady przedstawione w tym dokumencie używają obiektu poświadczeń o nazwie DefaultAzureCredential, który jest odpowiedni dla większości scenariuszy, w tym lokalnych środowisk programistycznych i produkcyjnych. Ponadto zalecamy użycie tożsamości zarządzanej do uwierzytelniania w środowiskach produkcyjnych.

Więcej informacji na temat różnych sposobów uwierzytelniania i odpowiadających im typów poświadczeń można znaleźć w dokumentacji Azure Identity.

Oto szybki przykład. Najpierw zaimportuj DefaultAzureCredential i CertificateClient:

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

Po zaimportowaniu tych elementów możemy nawiązać połączenie z usługą key vault:

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

Kluczowe pojęcia

Klient Certificates to podstawowy interfejs umożliwiający interakcję z metodami interfejsu API powiązanymi z certyfikatami w interfejsie API usługi Azure Key Vault z poziomu aplikacji JavaScript. Po zainicjowaniu udostępnia on podstawowy zestaw metod, których można użyć do tworzenia, odczytywania, aktualizowania i usuwania certyfikatów.
Wersja certyfikatu jest wersją certyfikatu w usłudze Key Vault. Za każdym razem, gdy użytkownik przypisuje wartość do unikatowej nazwy certyfikatu, tworzona jest nowa wersja tego certyfikatu. Pobranie certyfikatu według nazwy zawsze zwróci najnowszą przypisaną wartość, chyba że do zapytania zostanie podana określona wersja.
usuwanie nietrwałe umożliwia magazynom kluczy obsługę usuwania i przeczyszczania jako dwóch oddzielnych kroków, dlatego usunięte certyfikaty nie zostaną natychmiast utracone. Dzieje się tak tylko wtedy, gdy usługa Key Vault włączona usuwania nietrwałego.
kopii zapasowej certyfikatu można wygenerować na podstawie dowolnego utworzonego certyfikatu. Te kopie zapasowe są danymi binarnymi i mogą być używane tylko do ponownego generowania wcześniej usuniętego certyfikatu.

Określanie wersji interfejsu API usługi Azure Key Vault

Domyślnie ten pakiet używa najnowszej wersji usługi Azure Key Vault, która jest 7.1. Jedyną obsługiwaną wersją jest 7.0. Możesz zmienić używaną wersję usługi, ustawiając opcję serviceVersion w konstruktorze klienta, jak pokazano poniżej:

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

Przykłady

W poniższych sekcjach przedstawiono fragmenty kodu, które obejmują niektóre typowe zadania przy użyciu certyfikatów usługi Azure Key Vault. Scenariusze, które zostały tutaj omówione, składają się z następujących elementów:

Tworzenie i ustawianie certyfikatu.
Uzyskiwanie certyfikatu usługi Key Vault.
Uzyskiwanie pełnych informacji o certyfikacie.
Certyfikaty w formacie PEM.
Wyświetl listę wszystkich certyfikatów.
Aktualizowanie certyfikatu.
Usuwanie certyfikatu.
iteracja list certyfikatów.

Tworzenie i ustawianie certyfikatu

beginCreateCertificate tworzy certyfikat do przechowywania w usłudze Azure Key Vault. Jeśli certyfikat o tej samej nazwie już istnieje, zostanie utworzona nowa wersja certyfikatu.

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

Oprócz nazwy certyfikatu i zasad można również przekazać następujące właściwości w trzecim argumencie z opcjonalnymi wartościami:

enabled: wartość logiczna określająca, czy certyfikat może być używany, czy nie.
tags: dowolny zestaw klucz-wartości, który może służyć do wyszukiwania i filtrowania certyfikatów.

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

Wywołanie metody beginCreateCertificate o tej samej nazwie spowoduje utworzenie nowej wersji tego samego certyfikatu, która będzie mieć najnowsze podane atrybuty.

Ponieważ tworzenie w pełni utworzonych certyfikatów zajmuje trochę czasu, beginCreateCertificate zwraca obiekt poller, który śledzi podstawową operację długotrwałą zgodnie z naszymi wytycznymi: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Odebrany element poller umożliwi uzyskanie utworzonego certyfikatu przez wywołanie polecenia poller.getResult(). Możesz również poczekać na zakończenie usuwania, uruchamiając poszczególne wywołania usługi do momentu utworzenia certyfikatu lub czekając na zakończenie procesu:

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

Innym sposobem oczekiwania na podpisanie certyfikatu jest wykonywanie poszczególnych wywołań w następujący sposób:

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

Uzyskiwanie certyfikatu usługi Key Vault

Najprostszym sposobem odczytu certyfikatów z magazynu jest pobranie certyfikatu według nazwy. getCertificate pobierze najnowszą wersję certyfikatu wraz z zasadami certyfikatu. Opcjonalnie możesz pobrać inną wersję certyfikatu, wywołując getCertificateVersion, jeśli określisz wersję. getCertificateVersion nie zwraca zasad certyfikatu.

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

Uzyskiwanie pełnych informacji o certyfikacie

Projekt usługi Azure Key Vault umożliwia ostre rozróżnienie między kluczami, wpisami tajnymi i certyfikatami. Funkcje certyfikatów usługi Key Vault zostały zaprojektowane tak, aby korzystały z funkcji kluczy i wpisów tajnych. Oceńmy kompozycję certyfikatu usługi Key Vault:

Po utworzeniu certyfikatu usługi Key Vault adresowalny klucz i wpis tajny również są tworzone o tej samej nazwie. Klucz usługi Key Vault umożliwia wykonywanie operacji klucza, a wpis tajny usługi Key Vault umożliwia pobieranie wartości certyfikatu jako wpisu tajnego. Certyfikat usługi Key Vault zawiera również publiczne metadane certyfikatu x509. Źródło: skład certyfikatu.

Wiedząc, że klucz prywatny jest przechowywany w kluczu tajnym usługi Key Vault z dołączonym certyfikatem publicznym, możemy go pobrać przy użyciu klienta wpisów tajnych usługi Key Vault.

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

Należy pamiętać, że domyślnie typ zawartości certyfikatów to PKCS 12. Określając typ zawartości certyfikatu, będzie można pobrać go w formacie PEM. Przed pokazaniem sposobu tworzenia certyfikatów PEM najpierw przyjrzyjmy się sposobom pobierania klucza tajnego PEM z certyfikatu PKCS 12.

Za pomocą opensslmożna pobrać certyfikat publiczny w formacie PEM przy użyciu następującego polecenia:

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

Możesz również użyć openssl, aby pobrać klucz prywatny w następujący sposób:

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

Pamiętaj, że w obu przypadkach polecenie openssl wyświetli monit o podanie hasła użytego do utworzenia certyfikatu. Przykładowy kod, którego używaliśmy do tej pory, nie określił hasła, więc można dołączyć -passin 'pass:' na końcu każdego polecenia.

Certyfikaty w formacie PEM

Jeśli chcesz pracować z certyfikatami w formacie PEM, możesz poinformować usługę Key Vault platformy Azure, aby utworzyć certyfikaty w formacie PEM i zarządzać nimi, podając właściwość contentType w momencie tworzenia certyfikatów.

W poniższym przykładzie pokazano, jak utworzyć i pobrać publiczne i prywatne części certyfikatu sformatowanego za pomocą klientów usługi Key Vault dla certyfikatów i wpisów tajnych:

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

Należy pamiętać, że certyfikat publiczny będzie znajdować się w tym samym obiekcie blob zawartości co klucz prywatny. Możesz użyć nagłówków PEM, aby wyodrębnić je odpowiednio.

Wyświetlanie listy wszystkich certyfikatów

listPropertiesOfCertificates wyświetli listę wszystkich certyfikatów w usłudze Key Vault.

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

Aktualizowanie certyfikatu

Atrybuty certyfikatu można zaktualizować do istniejącej wersji certyfikatu przy użyciu updateCertificate, w następujący sposób:

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

Zasady certyfikatu można również aktualizować indywidualnie przy użyciu updateCertificatePolicy, w następujący sposób:

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

Usuwanie certyfikatu

Metoda beginDeleteCertificate ustawia certyfikat do usunięcia. Ten proces będzie występować w tle natychmiast po udostępnieniu niezbędnych zasobów.

Jeśli usuwania nietrwałego jest włączona dla usługi Key Vault, ta operacja będzie oznaczać certyfikat tylko jako certyfikat usunięty. Nie można zaktualizować usuniętego certyfikatu. Mogą być tylko odczytywane, odzyskiwane lub czyszczone.

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

Ponieważ usunięcie certyfikatu nie nastąpi natychmiast, po wywołaniu metody beginDeleteCertificate jest potrzebny pewien czas, zanim usunięty certyfikat będzie dostępny do odczytu, odzyskania lub przeczyszczania.

Iterowanie list certyfikatów

Za pomocą obiektu CertificateClient można pobierać i iterować wszystkie certyfikaty w magazynie certyfikatów, a także za pośrednictwem wszystkich usuniętych certyfikatów i wersji określonego certyfikatu. Dostępne są następujące metody interfejsu API:

listPropertiesOfCertificates wyświetli listę wszystkich certyfikatów, które nie zostały usunięte według ich nazw, tylko w ich najnowszych wersjach.
listDeletedCertificates wyświetli listę wszystkich usuniętych certyfikatów według ich nazw, tylko w ich najnowszych wersjach.
listPropertiesOfCertificateVersions wyświetli listę wszystkich wersji certyfikatu na podstawie nazwy certyfikatu.

Których można użyć w następujący sposób:

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

Wszystkie te metody będą zwracać wszystkie dostępne wyniki jednocześnie. Aby pobrać je według stron, dodaj .byPage() bezpośrednio po wywołaniu metody interfejsu API, której chcesz użyć, w następujący sposób:

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

Rozwiązywanie problemów

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @azure/logger:

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

setLogLevel("info");

Zobacz nasz przewodnik rozwiązywania problemów z , aby uzyskać szczegółowe informacje na temat diagnozowania różnych scenariuszy awarii.

Następne kroki

Więcej przykładów kodu można znaleźć za pośrednictwem następujących linków:

przykłady certyfikatów usługi Key Vault (JavaScript)
przykłady certyfikatów usługi Key Vault (TypeScript)
Przypadki testowe certyfikatów usługi Key Vault

Przyczyniając się

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.

wrażenia

Udostępnij za pośrednictwem