Klientská knihovna certifikátů služby Azure Key Vault pro JavaScript – verze 4.9.0

Článek
10/17/2024

Azure Key Vault je cloudová služba, která poskytuje zabezpečené úložiště a automatizovanou správu certifikátů používaných v rámci cloudové aplikace. Ve službě Azure Key Vault je možné 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 se chcete dozvědět více o službě Azure Key Vault, můžete si projít: Co je Azure Key Vault?

Použijte klientskou knihovnu pro certifikáty služby Azure Key Vault ve vaší Node.js aplikaci k:

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 se nedá použít v prohlížeči kvůli omezením služby Azure Key Vault. Pokyny najdete v tomto dokumentu.

Klíčové odkazy:

zdrojového kódu
balíčku (npm)
Referenční dokumentace k rozhraní API
dokumentace k produktu
ukázky

Začínáme

Aktuálně podporovaná prostředí

LTS verze Node.js

Požadavky

Předplatné Azure
Existující azure Key Vault. Pokud potřebujete vytvořit trezor klíčů, můžete to udělat na webu Azure Portal pomocí kroků v tomto dokumentu. Případně použijte Azure CLI podle těchto kroků.

Instalace balíčku

Instalace klientské knihovny certifikátů služby Azure Key Vault pomocí npm

npm install @azure/keyvault-certificates

Instalace knihovny identit

Klienti služby Key Vault se ověřují pomocí knihovny identit Azure. 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.

Ověřování pomocí Azure Active Directory

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

Pokud chcete pracovat se službou Azure Key Vault, budete muset vytvořit instanci třídy CertificateClient, adresu URL trezoru a objekt přihlašovacích údajů. 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.

Další informace o různých způsobech ověřování a jejich odpovídajících typech přihlašovacích údajů najdete v dokumentaci k dokumentaci k identitě Azure.

Tady je rychlý příklad. Nejprve importujte DefaultAzureCredential a CertificateClient:

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

Po importu se můžeme připojit k službě trezoru klíčů:

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

Klíčové koncepty

Klient Certifikáty je primární rozhraní pro interakci s metodami rozhraní API souvisejícími s certifikáty v rozhraní API služby Azure Key Vault 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 certifikátu je verze certifikátu ve službě 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í. K tomu dochází jenom v případě, že služba Key Vault obnovitelné odstranění povolená.
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.

Určení verze rozhraní API služby Azure Key Vault

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:

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

Příklady

Následující části obsahují fragmenty kódu, které pokrývají některé běžné úlohy pomocí certifikátů služby Azure Key Vault. Zde popsané scénáře se skládají z:

Vytvoření a nastavenícertifikátu .
získání certifikátu služby Key Vault.
Získání úplných informací ocertifikátu .
Certifikáty ve formátu PEM.
Zobrazit seznam všech certifikátů.
Aktualizace certifikátu.
Odstranění certifikátu.
iterace seznamů certifikátů.

Vytvoření a nastavení certifikátu

beginCreateCertificate vytvoří certifikát, který se uloží ve službě Azure Key Vault. Pokud už certifikát se stejným názvem existuje, vytvoří se nová verze certifikátu.

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

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ů.

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

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:

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

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

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

Získání certifikátu služby 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.

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

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

Návrh služby Azure Key Vault výrazně rozlišuje klíče, tajné kódy a certifikáty. Funkce certifikátů služby Key Vault byly navrženy tak, aby využívaly možnosti klíčů a tajných kódů. Pojďme vyhodnotit složení certifikátu služby Key Vault:

Když se vytvoří certifikát služby Key Vault, vytvoří se také adresovatelný klíč a tajný klíč se stejným názvem. Klíč služby Key Vault umožňuje operace s klíči a tajný klíč služby Key Vault umožňuje načtení hodnoty certifikátu jako tajného klíče. Certifikát služby Key Vault obsahuje také veřejná metadata certifikátu x509. Zdroj: Složenícertifikátu .

Když víme, že privátní klíč je uložený v tajném klíči služby Key Vault s zahrnutým veřejným certifikátem, můžeme ho načíst pomocí klienta tajných klíčů služby Key Vault.

// Using the same credential object we used before,
// and the same keyVaultUrl,
// let's create a SecretClient
import { SecretClient } from "@azure/keyvault-secrets";

const secretClient = new SecretClient(keyVaultUrl, credential);

// Assuming you've already created a Key Vault certificate,
// and that certificateName contains the name of your certificate
const certificateSecret = await secretClient.getSecret(certificateName);

// Here we can find both the private key and the public certificate, in PKCS 12 format:
const PKCS12Certificate = certificateSecret.value!;

// You can write this into a file:
fs.writeFileSync("myCertificate.p12", PKCS12Certificate);

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 službě Azure Key Vault sdělit, že má vytvářet a spravovat certifikáty ve formátu PEM tím, že v okamžiku vytvoření certifikátů poskytnete vlastnost contentType.

Následující příklad ukazuje, jak vytvořit a načíst veřejné a soukromé části certifikátu ve formátu PEM pomocí klientů služby Key Vault pro certifikáty a tajné kódy:

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

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 zobrazí seznam všech certifikátů ve službě 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();

Aktualizace certifikátu

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

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

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

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

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 službu Key Vault povolená obnovitelné odstranění, bude tato operace certifikát označovat pouze jako odstraněný certifikát. Odstraněný certifikát nejde aktualizovat. Dají se buď číst, obnovit nebo vyprázdnit.

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

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:

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

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:

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

Ř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ářů selhání najdete v našem průvodci odstraňováním potíží .

Další kroky

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

Ukázky certifikátů služby Key Vault (JavaScript)
Ukázky certifikátů služby Key Vault (TypeScript)
testovací případy certifikátů služby Key Vault

Přispívající

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.

imprese

Sdílet prostřednictvím