Azure Key Vault Certificates client library for JavaScript - version 4.10.3

Azure Key Vault to usługa chmurowa, która zapewnia bezpieczne przechowywanie i automatyczne zarządzanie certyfikatami używanymi w całej aplikacji chmurowej. W Azure Key Vault można przechowywać wiele certyfikatów oraz wiele wersji tego samego certyfikatu. 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 Azure Key Vault, możesz zapoznać się z napisem: Co to jest Azure Key Vault?

Użyj biblioteki klienta do Azure Key Vault certyfikatów 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: Ten pakiet nie może być używany w przeglądarce ze względu na ograniczenia Azure Key Vault usługi, prosimy o odwiedzenie ten dokument w celu uzyskania wskazówek.

Kluczowe linki:

Kod źródłowy
pakiet (npm)
Dokumentacja referencyjna interfejsu API
dokumentacja produktu
Samples

Wprowadzenie

Obecnie obsługiwane środowiska

wersje Node.js LTS

Warunki wstępne

Subskrypcja Azure
Istniejący Azure Key Vault. Jeśli musisz utworzyć sejf kluczy, możesz to zrobić w Azure Portal, wykonując kroki z ten dokument. Alternatywnie, skorzystaj z Azure CLI, stosując te kroki.

Instalowanie pakietu

Zainstaluj bibliotekę klienta Azure Key Vault Certificates za pomocą npm

npm install @azure/keyvault-certificates

Instalowanie biblioteki tożsamości

Klienci Key Vault uwierzytelniają się za pomocą biblioteki Azure Identity. 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 z Azure Active Directory

Usługa Key Vault polega na Azure Active Directory do uwierzytelniania żądań do swoich API. Pakiet @azure/identity udostępnia różne typy poświadczeń, których aplikacja może użyć do tego celu. README dla @azure/identity zawiera więcej szczegółów i przykładów, które pomogą Ci zacząć.

Aby wchodzić w interakcję z usługą Azure Key Vault, musisz utworzyć instancję klasy CertificateClient, adres URL vault oraz obiekt poświadczenia. 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 o różnych sposobach uwierzytelniania i ich typach poświadczeń znajdziesz w Azure Dokument tożsamości.

Oto szybki przykład. Najpierw zaimportuj DefaultAzureCredential i CertificateClient. Po zaimportowaniu tych elementów możemy nawiązać połączenie z usługą key vault:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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 jest głównym interfejsem do interakcji z metodami API związanymi z certyfikatami w API Azure Key Vault z 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 Certificate to wersja certyfikatu w 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 Key Vault ma włączone soft-delete włączone.
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.

Specifying the Azure Key Vault service API version

Domyślnie ten pakiet korzysta z 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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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.5",
});

Przykłady

Poniższe sekcje zawierają fragmenty kodu obejmujące niektóre z typowych zadań związanych z użyciem Azure Key Vault Certificates. Scenariusze, które zostały tutaj omówione, składają się z następujących elementów:

Tworzenie i ustawianie certyfikatu.
Zdobywanie certyfikatu 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 Azure Key Vault. Jeśli certyfikat o tej samej nazwie już istnieje, zostanie utworzona nowa wersja certyfikatu.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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.
await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
});

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.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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",
};

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

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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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",
};

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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",
};

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

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

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

Uzyskanie certyfikatu 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.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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 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,
);

Uzyskiwanie pełnych informacji o certyfikacie

Projekt Azure Key Vault wyraźnie rozróżnia klucze, sekrety i certyfikaty. Funkcje Certyfikatów usługi Key Vault zostały zaprojektowane z wykorzystaniem jej funkcji Kluczy i Sekretów. Przyjrzyjmy się składowi certyfikatu Key Vault:

Gdy tworzony jest certyfikat Key Vault, tworzone są także adresowalne klucze i sekret o tej samej nazwie. Klucz Key Vault umożliwia operacje z kluczem, a sekret Key Vault umożliwia odzyskanie wartości certyfikatu jako tajemnicy. Certyfikat Key Vault zawiera również metadane certyfikatu x509 publicznego. Źródło: skład certyfikatu.

Wiedząc, że klucz prywatny jest przechowywany w Key Vault Secret, z dołączonym certyfikatem publicznym, możemy go odzyskać, korzystając z klienta Key Vault Secrets.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { writeFileSync } from "node:fs";

const credential = new DefaultAzureCredential();

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

const secretClient = new SecretClient(keyVaultUrl, credential);

const certificateName = "MyCertificateName";

// 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:
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 polecić Azure Key Vault usłudze tworzenia i zarządzania certyfikatami w formacie PEM, podając właściwość contentType w momencie tworzenia certyfikatów.

Poniższy przykład pokazuje, jak tworzyć i pobierać publiczne i prywatne części certyfikatu w formacie PEM za pomocą klientów Key Vault dla certyfikatów i sekretów:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);
const secretClient = new SecretClient(keyVaultUrl, credential);
// 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.
});
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 wymieni wszystkie certyfikaty w Key Vault.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

Aktualizowanie certyfikatu

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

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 soft-delete jest włączone dla Key Vault, ta operacja oznaczy certyfikat jedynie jako deleted certificate. Nie można zaktualizować usuniętego certyfikatu. Mogą być tylko odczytywane, odzyskiwane lub czyszczone.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

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 trouble aby uzyskać szczegóły dotyczące 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:

Przyczyniając się

Jeśli chcesz przyczynić się do tej biblioteki, przeczytaj przewodnik wkład aby dowiedzieć się więcej o budowaniu i testowaniu kodu.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-04-09