Sdílet prostřednictvím

Klientská knihovna certifikátů Azure Key Vault pro JavaScript – verze 4.8.0

  • Článek

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. V Azure Key Vault je možné uchovávat více certifikátů a více verzí stejného certifikátu. Ke každému certifikátu v trezoru jsou přidružené zásady, 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 o Azure Key Vault dozvědět více, můžete si projít téma Co je Azure Key Vault?

Pomocí klientské knihovny pro certifikáty Azure Key Vault v aplikaci Node.js můžete:

  • Získání, nastavení a odstranění certifikátu
  • Aktualizujte certifikát, jeho atributy, vystavitele, zásady, operace a kontakty.
  • Zálohujte a obnovte certifikát.
  • Získání, vymazá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 použít v prohlížeči kvůli omezením služby Azure Key Vault. Pokyny najdete v tomto dokumentu.

Klíčové odkazy:

Začínáme

Aktuálně podporovaná prostředí

Požadavky

Instalace balíčku

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

npm install @azure/keyvault-certificates

Instalace knihovny identit

Key Vault klienti se ověřují pomocí knihovny identit Azure. Nainstalujte ho také pomocí npm.

npm install @azure/identity

Konfigurace TypeScriptu

Uživatelé TypeScriptu musí mít nainstalované definice typů uzlů:

npm install @types/node

Musíte také povolit compilerOptions.allowSyntheticDefaultImports v 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 k možnostem kompilátoru TypeScriptu .

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

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

Abyste mohli pracovat se službou Azure Key Vault, budete muset vytvořit instanci CertificateClient třídy, 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ích vývojových a produkčních 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 Identitě Azure.

Tady je stručný příklad. Nejprve import DefaultAzureCredential a CertificateClient:

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

Po importu se můžeme dále připojit ke 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ím rozhraním pro interakci s metodami rozhraní API souvisejícími s certifikáty v rozhraní API 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 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 k dotazu není zadána konkrétní verze.
  • Obnovitelné odstranění umožňuje službě Key Vault podporovat odstranění a vymazání ve dvou samostatných krocích, takže odstraněné certifikáty se okamžitě neztratí. K tomu dochází pouze v případě, že má Key Vault povolené obnovitelné odstranění.
  • Zálohu certifikátu je možné vygenerovat z libovolného vytvořeného certifikátu. Tyto zálohy přicházejí jako binární data a dají se 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á další podporovaná verze je 7.0. Verzi používané služby 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 s využitím certifikátů Azure Key Vault. Scénáře, které jsou zde popsané, se skládají z těchto:

Vytvoření a nastavení certifikátu

beginCreateCertificatevytvoří certifikát, který se uloží do azure Key Vault. Pokud již existuje certifikát se stejným názvem, 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 do třetího argumentu s volitelnými hodnotami předat také následující vlastnosti:

  • enabled: Logická hodnota, která určuje, jestli je možné certifikát použít, nebo ne.
  • tags: Libovolná sada hodnot klíč-hodnota, která se dá 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ím na beginCreateCertificate adresu se stejným názvem se vytvoří nová verze stejného certifikátu, která bude mít nejnovější zadané atributy.

Vzhledem k tomu, že úplné vytvoření certifikátů nějakou dobu trvá, beginCreateCertificate vrátí objekt poller, který sleduje podkladovou dlouhotrvají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 na dokončení odstranění, 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, jak počkat 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 Key Vault

Nejjednodušší způsob, jak číst certifikáty 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 Azure Key Vault výrazně rozlišuje klíče, tajné kódy a certifikáty. Funkce Certifikáty služby Key Vault byly navrženy s využitím jejích funkcí Klíče a tajné kódy. Pojďme vyhodnotit složení certifikátu Key Vault:

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

S vědomím, že privátní klíč je uložený v tajném klíči Key Vault s veřejným certifikátem, můžeme ho načíst pomocí klienta Key Vault Secret.

// 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, pojďme nejprve prozkoumat, jak nejprve načíst tajný klíč PEM z certifikátu PKCS 12.

Pomocí opensslpříkazu můžete načíst veřejný certifikát 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 také načíst 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 požádá o heslo použité k vytvoření certifikátu. Vzorový kód, který jsme zatím použili, nezadá heslo, takže můžete připojit -passin 'pass:' na konec každého příkazu.

Certifikáty ve formátu PEM

Pokud chcete pracovat s certifikáty ve formátu PEM, můžete Key Vault službě Azure sdělit, aby vaše certifikáty vytvářela a spravoval ve formátu PEM tím, že při vytváření certifikátů zadáte contentType vlastnost.

Následující příklad ukazuje, jak vytvořit a načíst veřejné a privátní části certifikátu ve formátu PEM pomocí Key Vault klientů 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);

Nezapomeňte, ž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ů

listPropertiesOfCertificateszobrazí seznam všech certifikátů v 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 je možné aktualizovat na existující verzi certifikátu pomocí updateCertificatepříkazu , 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 = await client.getCertificate(certificateName);
  await client.updateCertificateProperties(certificateName, result.properties.version, {
    enabled: false,
    tags: {
      myCustomTag: "myCustomTagsValue",
    },
  });
}

main();

Zásady certifikátu je také možné aktualizovat jednotlivě pomocí updateCertificatePolicypříkazu , 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í. Tento proces bude probíhat na pozadí, jakmile budou k dispozici potřebné prostředky.

Pokud je pro Key Vault povolené obnovitelné odstranění, označí tato operace certifikát pouze jako odstraněný certifikát. Odstraněný certifikát nejde aktualizovat. Dají se jenom číst, obnovit nebo vymazat.

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 k odstranění certifikátu nedojde okamžitě, je po zavolání metody potřeba beginDeleteCertificate nějakou dobu, 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ů, stejně jako 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 neodstraněných certifikátů podle jejich názvů, pouze v jejich nejnovějších verzích.
  • listDeletedCertificates zobrazí seznam všech odstraněných certifikátů podle jejich názvů, pouze v jejich 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 po stránkách, 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();

Poradce při potížích

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

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

setLogLevel("info");

Podrobnosti o tom, jak diagnostikovat různé scénáře 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:

Přispívání

Pokud chcete přispívat 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 sestavit a otestovat kód.

Imprese