Biblioteka klienta certyfikatów usługi Azure Key Vault dla języka JavaScript — wersja 4.8.0
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
- Subskrypcja platformy Azure
- Istniejąca usługa Azure Key Vault. Jeśli musisz utworzyć magazyn kluczy, możesz to zrobić w witrynie Azure Portal, wykonując kroki opisane w tym dokumencie. Możesz też użyć interfejsu wiersza polecenia platformy Azure, wykonując następujące kroki.
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.esModuleInterop
usł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.
- Uzyskiwanie certyfikatu Key Vault.
- Uzyskiwanie pełnych informacji o certyfikacie.
- Certyfikaty w formacie PEM.
- Wyświetl listę wszystkich certyfikatów.
- Aktualizowanie certyfikatu.
- Usuwanie certyfikatu.
- Iterowanie 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 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 openssl
moż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
listPropertiesOfCertificates
program 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ą updateCertificate
polecenia 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ą updateCertificatePolicy
polecenia 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:
- przykłady certyfikatów Key Vault (JavaScript)
- przykłady certyfikatów Key Vault (TypeScript)
- przypadki testowe certyfikatów Key Vault
Współtworzenie
Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.
Azure SDK for JavaScript
Opinia
https://aka.ms/ContentUserFeedback.
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź:Prześlij i wyświetl opinię dla