Azure Key Vault Certificates client library for JavaScript - version 4.10.3

Azure Key Vault je cloudová služba, která poskytuje bezpečné ukládání a automatizovanou správu certifikátů používaných v rámci cloudové aplikace. V Azure Key Vault lze uchovávat více certifikátů a více verzí stejného certifikátu. Každý certifikát v trezoru má přidruženou zásadu, která řídí vystavování a životnost certifikátu spolu s akcemi, které se mají provést jako certifikáty blízko vypršení platnosti.

Pokud byste se chtěli o Azure Key Vault dozvědět více, možná byste měli přečíst: Co je Azure Key Vault?

Použijte klientskou knihovnu pro Azure Key Vault certifikátů ve vaší Node.js žádosti, abyste:

  • Získejte, nastavte a odstraňte certifikát.
  • Aktualizujte certifikát, jeho atributy, vystavitele, zásady, operace a kontakty.
  • Zálohujte a obnovte certifikát.
  • Získejte, vyprázdnění nebo obnovení odstraněného certifikátu.
  • Získejte všechny verze certifikátu.
  • Získejte všechny certifikáty.
  • Získejte všechny odstraněné certifikáty.

Poznámka: Tento balíček nelze v prohlížeči používat kvůli Azure Key Vault omezením služeb, pro doporučení se prosím podívejte na tento dokument pro doporučení.

Klíčové odkazy:

Začínáme

Aktuálně podporovaná prostředí

Požadavky

Instalace balíčku

Install the Azure Key Vault Certificates client library using npm

npm install @azure/keyvault-certificates

Instalace knihovny identit

Klienti Key Vault se autentizují pomocí Azure Identity Library. Nainstalujte ho i pomocí npm.

npm install @azure/identity

Konfigurace TypeScriptu

Uživatelé TypeScriptu musí mít nainstalované definice typu Node:

npm install @types/node

Musíte také povolit compilerOptions.allowSyntheticDefaultImports ve svém tsconfig.json. Všimněte si, že pokud jste povolili compilerOptions.esModuleInterop, allowSyntheticDefaultImports je ve výchozím nastavení povolená. Další informace najdete v příručce možnosti kompilátoru TypeScriptu.

Autentizace pomocí Azure Active Directory

Služba Key Vault spoléhá na Azure Active Directory k autentizaci požadavků na své API. Balíček @azure/identity poskytuje řadu typů přihlašovacích údajů, které může vaše aplikace použít k tomu. README pro @azure/identity poskytuje více podrobností a ukázky, které vám pomohou začít.

Pro interakci se službou Azure Key Vault budete muset vytvořit instanci třídy , URL vault a objekt s přihlašováním. Příklady uvedené v tomto dokumentu používají objekt přihlašovacích údajů s názvem DefaultAzureCredential, který je vhodný pro většinu scénářů, včetně místního vývojového a produkčního prostředí. Kromě toho doporučujeme použít spravovanou identitu pro ověřování v produkčních prostředích.

Více informací o různých způsobech ověřování a jejich odpovídajících typech přihlašovacích údajů najdete v Azure Identity documentation.

Tady je rychlý příklad. Nejprve importujte DefaultAzureCredential a CertificateClient. Po importu se můžeme připojit k službě trezoru klíčů:

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

Klíčové koncepty

  • Klient Certificates je primární rozhraní pro interakci s API metodami souvisejícími s certifikáty v Azure Key Vault API z JavaScriptové aplikace. Po inicializaci poskytuje základní sadu metod, které lze použít k vytváření, čtení, aktualizaci a odstraňování certifikátů.
  • Verze Certificate je verze certifikátu v Key Vault. Pokaždé, když uživatel přiřadí hodnotu jedinečnému názvu certifikátu, vytvoří se nová verze tohoto certifikátu. Načtení certifikátu podle názvu vždy vrátí nejnovější přiřazenou hodnotu, pokud není pro dotaz zadána konkrétní verze.
  • obnovitelné odstranění umožňuje službě Key Vault podporovat odstranění a vyprázdnění jako dva samostatné kroky, takže odstraněné certifikáty se okamžitě neztratí. To se děje jen tehdy, pokud má Key Vault zapnuté soft-delete.
  • zálohování certifikátů je možné vygenerovat z libovolného vytvořeného certifikátu. Tyto zálohy pocházejí jako binární data a lze je použít pouze k opětovnému vygenerování dříve odstraněného certifikátu.

Specificifying the Azure Key Vault service API version

Ve výchozím nastavení tento balíček používá nejnovější verzi služby Azure Key Vault, která je 7.1. Jediná podporovaná verze je 7.0. Verzi služby, kterou používáte, můžete změnit nastavením možnosti serviceVersion v konstruktoru klienta, jak je znázorněno níže:

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

Příklady

Následující sekce poskytují úryvky kódu, které pokrývají některé běžné úkoly využívající Azure Key Vault Certificates. Zde popsané scénáře se skládají z:

Vytvoření a nastavení certifikátu

beginCreateCertificate vytváří certifikát, který je uložen v Azure Key Vault. Pokud už certifikát se stejným názvem existuje, vytvoří se nová verze certifikátu.

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

Kromě názvu certifikátu a zásady můžete také předat následující vlastnosti ve třetím argumentu s volitelnými hodnotami:

  • enabled: Logická hodnota, která určuje, zda lze certifikát použít, nebo ne.
  • tags: Libovolná sada hodnot klíčů, které lze použít k vyhledávání a filtrování certifikátů.
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,
});

Volání na beginCreateCertificate se stejným názvem vytvoří novou verzi stejného certifikátu, která bude obsahovat nejnovější zadané atributy.

Vzhledem k tomu, že úplné vytvoření certifikátů nějakou dobu trvá, beginCreateCertificate vrátí objekt vrtu, který sleduje základní dlouho běžící operaci podle našich pokynů: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Přijatá poller vám umožní získat vytvořený certifikát voláním na poller.getResult(). Můžete také počkat, až se odstranění dokončí, a to buď spuštěním jednotlivých volání služby, dokud se certifikát nevytvořil, nebo čekáním na dokončení 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);

Dalším způsobem čekání na podepsání certifikátu je provést jednotlivá volání následujícím způsobem:

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

Získání certifikátu Key Vault

Nejjednodušším způsobem, jak číst certifikáty zpět z trezoru, je získat certifikát podle názvu. getCertificate načte nejnovější verzi certifikátu spolu se zásadami certifikátu. Volitelně můžete získat jinou verzi certifikátu voláním getCertificateVersion, pokud zadáte verzi. getCertificateVersion nevrací zásady certifikátu.

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

Získání úplných informací o certifikátu

Design Azure Key Vault jasně rozlišuje mezi klíči, tajemstvími a certifikáty. Funkce Certifikáty služby Key Vault byly navrženy s využitím jejích funkcí Klíče a Tajemství. Pojďme zhodnotit složení certifikátu Key Vault:

Když je vytvořen certifikát Key Vault, vytvoří se také adresovatelný klíč a tajemství se stejným názvům. Klíč Key Vault umožňuje operace s klíčem a tajemství Key Vault umožňuje získat hodnotu certifikátu jako tajemství. Certifikát Key Vault také obsahuje metadata veřejných x509 certifikátů. Zdroj: Složenícertifikátu .

S vědomím, že soukromý klíč je uložen v Key Vault Secret, včetně veřejného certifikátu, jej můžeme získat pomocí 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);

Všimněte si, že ve výchozím nastavení je typ obsahu certifikátů PKCS 12. Zadáním typu obsahu certifikátu ho budete moct načíst ve formátu PEM. Než si ukážeme, jak vytvořit certifikáty PEM, nejprve se podíváme, jak nejdřív načíst tajný klíč PEM z certifikátu PKCS 12.

Pomocí opensslmůžete veřejný certifikát načíst ve formátu PEM pomocí následujícího příkazu:

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

Privátní klíč můžete načíst také pomocí openssl následujícím způsobem:

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

Všimněte si, že v obou případech vás openssl vyzve k zadání hesla použitého k vytvoření certifikátu. Vzorový kód, který jsme zatím použili, nezadával heslo, takže můžete k konci každého příkazu připojit -passin 'pass:'.

Certifikáty ve formátu PEM

Pokud chcete pracovat s certifikáty ve formátu PEM, můžete Azure Key Vault službu požádat, aby vaše certifikáty vytvářela a spravovala ve formátu PEM tím, že v okamžiku jejich vytvoření poskytne vlastnost contentType.

Následující příklad ukazuje, jak vytvořit a získat veřejné a soukromé části certifikátu formátovaného PEM pomocí klientů Key Vault pro certifikáty a tajemství:

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

Mějte na paměti, že váš veřejný certifikát bude ve stejném objektu blob obsahu jako váš privátní klíč. Pomocí hlaviček PEM je můžete odpovídajícím způsobem extrahovat.

Výpis všech certifikátů

listPropertiesOfCertificates uvede všechny certifikáty v 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);
}

Aktualizace certifikátu

Atributy certifikátu lze aktualizovat na existující verzi certifikátu pomocí updateCertificatenásledujícím způsobem:

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

Zásady certifikátu je možné aktualizovat také jednotlivě pomocí updateCertificatePolicy, a to následujícím způsobem:

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

Odstranění certifikátu

Metoda beginDeleteCertificate nastaví certifikát pro odstranění. K tomuto procesu dojde na pozadí, jakmile budou k dispozici potřebné prostředky.

Pokud je pro Key Vault povoleno soft-delete, tato operace označí certifikát pouze jako deleted certifikát. Odstraněný certifikát nejde aktualizovat. Dají se buď číst, obnovit nebo vyprázdnit.

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

Vzhledem k tomu, že odstranění certifikátu nebude probíhat okamžitě, je čas potřebný po zavolání metody beginDeleteCertificate, než bude odstraněný certifikát k dispozici ke čtení, obnovení nebo vymazání.

Iterace seznamů certifikátů

Pomocí CertificateClient můžete načíst a iterovat všechny certifikáty v trezoru certifikátů a také všechny odstraněné certifikáty a verze konkrétního certifikátu. K dispozici jsou následující metody rozhraní API:

  • listPropertiesOfCertificates zobrazí seznam všech nesmazatých certifikátů podle jejich názvů, pouze v nejnovějších verzích.
  • listDeletedCertificates zobrazí seznam všech odstraněných certifikátů podle jejich názvů, pouze v nejnovějších verzích.
  • listPropertiesOfCertificateVersions zobrazí seznam všech verzí certifikátu na základě názvu certifikátu.

Který lze použít následujícím způsobem:

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

Všechny tyto metody vrátí všechny dostupné výsledky najednou. Pokud je chcete načíst podle stránek, přidejte .byPage() hned po vyvolání metody rozhraní API, kterou chcete použít, následujícím způsobem:

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

Řešení problémů

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete protokolování povolit za běhu voláním setLogLevel v @azure/logger:

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

setLogLevel("info");

Podrobnosti o diagnostice různých scénářů poruch najdete v našem trouble guide pro podrobnosti.

Další kroky

Další ukázky kódu najdete na následujících odkazech:

Přispívající

Pokud byste chtěli přispět do této knihovny, přečtěte si prosím průvodce přispívání kde se dozvíte více o tom, jak kód sestavit a testovat.

  • Last updated on