Share via

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

  • Artykuł

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 zbliżające się do wygaśnięcia.

Jeśli chcesz dowiedzieć się więcej o usłudze Azure Key Vault, warto przejrzeć: 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:

  • Pobierz, ustaw i usuń certyfikat.
  • 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: ten pakiet nie może być używany w przeglądarce ze względu na ograniczenia usługi Azure Key Vault, zapoznaj się z tym dokumentem, aby uzyskać wskazówki.

Kluczowe linki:

Wprowadzenie

Obecnie obsługiwane środowiska

Wymagania wstępne

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

Key Vault klienci 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. Pamiętaj, że jeśli włączono compilerOptions.esModuleInteropusługę , allowSyntheticDefaultImports jest domyślnie włączona. Aby uzyskać więcej informacji, zobacz podręcznik dotyczący opcji 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 zawiera @azure/identity więcej szczegółów i przykładów, aby rozpocząć pracę.

Aby móc korzystać z usługi Azure Key Vault, należy utworzyć wystąpienie CertificateClient klasy, 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 usługi 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ą magazynu kluczy:

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 certyfikatów jest podstawowym interfejsem umożliwiającym 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 podstawowy zestaw metod, których można użyć do tworzenia, odczytywania, aktualizowania i usuwania certyfikatów.
  • Wersja certyfikatu jest wersją certyfikatu w Key Vault. Za każdym razem, gdy użytkownik przypisuje wartość do unikatowej nazwy certyfikatu, tworzona jest nowa wersja tego certyfikatu. Pobieranie certyfikatu według nazwy będzie zawsze zwracać najnowszą przypisaną wartość, chyba że do zapytania zostanie podana określona wersja.
  • Usuwanie nietrwałe umożliwia usłudze Key Vault obsługę usuwania i przeczyszczania jako dwóch oddzielnych kroków, więc usunięte certyfikaty nie zostaną natychmiast utracone. Dzieje się tak tylko wtedy, gdy Key Vault ma włączone usuwanie nietrwałe.
  • Kopię zapasową certyfikatu można wygenerować na podstawie dowolnego utworzonego certyfikatu. Te kopie zapasowe pochodzą jako dane binarne 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 to .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 korzystające z certyfikatów usługi Azure Key Vault. Scenariusze, które zostały omówione w tym miejscu, składają się z następujących elementów:

Tworzenie i ustawianie certyfikatu

beginCreateCertificateTworzy 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 z beginCreateCertificate tą samą nazwą spowoduje utworzenie nowej wersji tego samego certyfikatu, która będzie miała najnowsze podane atrybuty.

Ponieważ tworzenie 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

Otrzymany element poller umożliwi uzyskanie utworzonego certyfikatu przez wywołanie polecenia poller.getResult(). Możesz również poczekać na zakończenie usuwania, uruchamiając pojedyncze 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 Key Vault

Najprostszym sposobem odczytu certyfikatów z magazynu jest pobranie certyfikatu według nazwy. getCertificate program pobierze najnowszą wersję certyfikatu wraz z zasadami certyfikatu. Opcjonalnie możesz uzyskać inną wersję certyfikatu, wywołując polecenie 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();

Pobieranie pełnych informacji o certyfikacie

Projekt usługi Azure Key Vault sprawia, że 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 Key Vault:

Po utworzeniu certyfikatu Key Vault jest również tworzony klucz adresowy i wpis tajny o tej samej nazwie. Klucz Key Vault umożliwia wykonywanie operacji klucza, a klucz tajny Key Vault umożliwia pobieranie wartości certyfikatu jako wpisu tajnego. Certyfikat Key Vault zawiera również publiczne metadane certyfikatu x509. Źródło: kompozycja certyfikatu.

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

// 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 go pobrać w formacie PEM. Przed pokazaniem sposobu tworzenia certyfikatów PEM najpierw przyjrzyjmy się, jak pobrać klucz tajny PEM z certyfikatu PKCS 12.

Za pomocą polecenia 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 polecenia , 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żyliśmy do tej pory, nie określił hasła, więc możesz dołączyć -passin 'pass:' go 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 o utworzeniu certyfikatów i zarządzaniu nimi w formacie PEM, podając contentType właściwość w momencie tworzenia certyfikatów.

W poniższym przykładzie pokazano, jak utworzyć i pobrać publiczne i prywatne części certyfikatu w formacie PEM przy użyciu klientów 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

listPropertiesOfCertificatesprogram wyświetli listę wszystkich certyfikatów w 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 za pomocą updateCertificatepolecenia 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 za pomocą updateCertificatePolicypolecenia 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 dla Key Vault włączono usuwanie nietrwałe, ta operacja oznaczy certyfikat tylko jako usunięty certyfikat. 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 jest potrzebny pewien czas, beginDeleteCertificate zanim usunięty certyfikat będzie dostępny do odczytu, odzyskania lub przeczyszczania.

Iterowanie list certyfikatów

Za pomocą obiektu CertificateClient można pobrać i wykonać iterację wszystkich certyfikatów 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 program wyświetli listę wszystkich certyfikatów, które nie zostały usunięte według ich nazw, tylko w ich najnowszych wersjach.
  • listDeletedCertificates Program wyświetli listę wszystkich usuniętych certyfikatów według ich nazw, tylko w ich najnowszych wersjach.
  • listPropertiesOfCertificateVersions program wyświetli listę wszystkich wersji certyfikatu na podstawie nazwy certyfikatu.

Którego 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ą AZURE_LOG_LEVEL środowiskową na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel polecenie w pliku @azure/logger:

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

setLogLevel("info");

Zobacz nasz przewodnik rozwiązywania problemów , 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 pomocą następujących linków:

Współtworzenie

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

Wrażenia