Klientbibliotek för Azure Key Vault-certifikat för JavaScript – version 4.8.0

Artikel
02/16/2024

Azure Key Vault är en molntjänst som tillhandahåller säker lagring och automatiserad hantering av certifikat som används i ett molnprogram. Flera certifikat och flera versioner av samma certifikat kan lagras i Azure Key Vault. Varje certifikat i valvet har en associerad princip som styr certifikatets utfärdande och livslängd, tillsammans med åtgärder som ska vidtas som certifikat som snart upphör att gälla.

Om du vill veta mer om Azure Key Vault kanske du vill granska: Vad är Azure Key Vault?

Använd klientbiblioteket för Azure Key Vault-certifikat i ditt Node.js-program för att:

Hämta, ange och ta bort ett certifikat.
Uppdatera ett certifikat, dess attribut, utfärdare, princip, åtgärd och kontakter.
Säkerhetskopiera och återställa ett certifikat.
Hämta, rensa eller återställa ett borttaget certifikat.
Hämta alla versioner av ett certifikat.
Hämta alla certifikat.
Hämta alla borttagna certifikat.

Obs! Det här paketet kan inte användas i webbläsaren på grund av begränsningar i Azure Key Vault-tjänsten. Mer information finns i det här dokumentet.

Nyckellänkar:

Komma igång

Miljöer som stöds för närvarande

LTS-versioner av Node.js

Förutsättningar

En Azure-prenumeration
En befintlig Azure-Key Vault. Om du behöver skapa ett nyckelvalv kan du göra det i Azure-portalen genom att följa stegen i det här dokumentet. Du kan också använda Azure CLI genom att följa dessa steg.

Installera paketet

Installera Klientbiblioteket för Azure Key Vault-certifikat med npm

npm install @azure/keyvault-certificates

Installera identitetsbiblioteket

Key Vault klienter autentiserar med hjälp av Azure Identity Library. Installera den också med npm

npm install @azure/identity

Konfigurera TypeScript

TypeScript-användare måste ha nodtypsdefinitioner installerade:

npm install @types/node

Du måste också aktivera compilerOptions.allowSyntheticDefaultImports i din tsconfig.json. Observera att om du har aktiverat compilerOptions.esModuleInteropallowSyntheticDefaultImports är aktiverad som standard. Mer information finns i Handbook för kompilatoralternativ i TypeScript .

Autentisera med Azure Active Directory

Key Vault-tjänsten förlitar sig på Azure Active Directory för att autentisera begäranden till dess API:er. Paketet @azure/identity innehåller en mängd olika typer av autentiseringsuppgifter som ditt program kan använda för att göra detta. README för @azure/identity innehåller mer information och exempel för att komma igång.

För att interagera med Tjänsten Azure Key Vault måste du skapa en instans av CertificateClient klassen, en valv-URL och ett autentiseringsobjekt. Exemplen som visas i det här dokumentet använder ett autentiseringsuppgiftsobjekt med namnet DefaultAzureCredential, vilket är lämpligt för de flesta scenarier, inklusive lokala utvecklings- och produktionsmiljöer. Dessutom rekommenderar vi att du använder en hanterad identitet för autentisering i produktionsmiljöer.

Du hittar mer information om olika sätt att autentisera och deras motsvarande typer av autentiseringsuppgifter i Azure Identity-dokumentationen.

Här är ett snabbt exempel. Importera först DefaultAzureCredential och CertificateClient:

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

När dessa har importerats kan vi ansluta till key vault-tjänsten:

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

Viktiga begrepp

Certifikatklienten är det primära gränssnittet för att interagera med API-metoderna relaterade till certifikat i Azure Key Vault-API:et från ett JavaScript-program. När den har initierats innehåller den en grundläggande uppsättning metoder som kan användas för att skapa, läsa, uppdatera och ta bort certifikat.
En certifikatversion är en version av ett certifikat i Key Vault. Varje gång en användare tilldelar ett värde till ett unikt certifikatnamn skapas en ny version av certifikatet. Om du hämtar ett certifikat med ett namn returneras alltid det senaste tilldelade värdet, såvida inte en viss version anges för frågan.
Mjuk borttagning gör att Key Vaults stöder borttagning och rensning som två separata steg, så borttagna certifikat går inte omedelbart förlorade. Detta inträffar bara om Key Vault har mjuk borttagning aktiverat.
En certifikatsäkerhetskopia kan genereras från alla skapade certifikat. Dessa säkerhetskopior kommer som binära data och kan bara användas för att återskapa ett tidigare borttaget certifikat.

Ange API-versionen för Azure Key Vault-tjänsten

Som standard använder det här paketet den senaste versionen av Azure Key Vault-tjänsten, som är 7.1. Den enda andra versionen som stöds är 7.0. Du kan ändra den tjänstversion som används genom att ange alternativet serviceVersion i klientkonstruktorn enligt nedan:

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

Exempel

Följande avsnitt innehåller kodfragment som beskriver några av de vanliga uppgifterna med hjälp av Azure Key Vault-certifikat. De scenarier som beskrivs här består av:

Skapa och ange ett certifikat.
Hämta ett Key Vault certifikat.
Hämta fullständig information om ett certifikat.
Certifikat i PEM-format.
Visa en lista över alla certifikat.
Uppdaterar ett certifikat.
Ta bort ett certifikat.
Iterera listor över certifikat.

Skapa och ange ett certifikat

beginCreateCertificateskapar ett certifikat som ska lagras i Azure Key Vault. Om det redan finns ett certifikat med samma namn skapas en ny version av certifikatet.

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

Förutom namnet på certifikatet och principen kan du även skicka följande egenskaper i ett tredje argument med valfria värden:

enabled: Ett booleskt värde som avgör om certifikatet kan användas eller inte.
tags: Alla uppsättningar nyckelvärden som kan användas för att söka efter och filtrera certifikat.

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

Om du anropar till beginCreateCertificate med samma namn skapas en ny version av samma certifikat, som har de senaste angivna attributen.

Eftersom certifikat tar lite tid att skapa helt returnerar beginCreateCertificate ett pollerobjekt som håller reda på den underliggande långvariga åtgärden enligt våra riktlinjer: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Med den mottagna pollern kan du hämta det skapade certifikatet genom att anropa till poller.getResult(). Du kan också vänta tills borttagningen är klar, antingen genom att köra enskilda tjänstanrop tills certifikatet har skapats eller genom att vänta tills processen är klar:

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

Ett annat sätt att vänta tills certifikatet har signerats är att göra enskilda anrop på följande sätt:

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

Hämta ett Key Vault-certifikat

Det enklaste sättet att läsa tillbaka certifikat från valvet är att hämta ett certifikat efter namn. getCertificate hämtar den senaste versionen av certifikatet tillsammans med certifikatets princip. Du kan också hämta en annan version av certifikatet genom att anropa getCertificateVersion om du anger versionen. getCertificateVersion returnerar inte certifikatets princip.

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

Hämta fullständig information om ett certifikat

Azure Key Vault design gör skarpa åtskillnader mellan nycklar, hemligheter och certifikat. Key Vault-tjänstens certifikatfunktioner har utformats för att använda funktionerna nycklar och hemligheter. Nu ska vi utvärdera sammansättningen av ett Key Vault-certifikat:

När ett Key Vault certifikat skapas skapas också en adresserbar nyckel och hemlighet med samma namn. Den Key Vault nyckeln tillåter nyckelåtgärder och den Key Vault hemligheten tillåter hämtning av certifikatvärdet som en hemlighet. Ett Key Vault certifikat innehåller även offentliga x509-certifikatmetadata. Källa: Sammansättningen av ett certifikat.

Om vi vet att den privata nyckeln lagras i en Key Vault Hemlighet, med det offentliga certifikatet inkluderat, kan vi hämta den med hjälp av Key Vault Secrets-klienten.

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

Observera att innehållstypen för certifikaten som standard är PKCS 12. Genom att ange innehållstypen för certifikatet kan du hämta det i PEM-format. Innan vi visar hur du skapar PEM-certifikat ska vi först utforska hur du hämtar en PEM-hemlig nyckel från ett PKCS 12-certifikat först.

Med kan openssldu hämta det offentliga certifikatet i PEM-format med hjälp av följande kommando:

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

Du kan också använda openssl för att hämta den privata nyckeln på följande sätt:

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

Observera att openssl i båda fallen ber dig om lösenordet som användes för att skapa certifikatet. Exempelkoden som vi har använt hittills har inte angett något lösenord, så du kan lägga -passin 'pass:' till i slutet av varje kommando.

Certifikat i PEM-format

Om du vill arbeta med certifikat i PEM-format kan du be Azures Key Vault-tjänst att skapa och hantera dina certifikat i PEM-format genom att ange contentType egenskapen när certifikaten skapas.

I följande exempel visas hur du skapar och hämtar offentliga och privata delar av ett PEM-formaterat certifikat med hjälp av Key Vault klienter för certifikat och hemligheter:

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

Tänk på att ditt offentliga certifikat finns i samma blob med innehåll som din privata nyckel. Du kan använda PEM-huvuden för att extrahera dem i enlighet med detta.

Visa en lista över alla certifikat

listPropertiesOfCertificatesvisar en lista över alla certifikat i 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();

Uppdatera ett certifikat

Certifikatattributen kan uppdateras till en befintlig certifikatversion med updateCertificate, enligt följande:

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

Certifikatets princip kan också uppdateras individuellt med updateCertificatePolicy, enligt följande:

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

Ta bort ett certifikat

Metoden beginDeleteCertificate konfigurerar ett certifikat för borttagning. Den här processen sker i bakgrunden så snart de nödvändiga resurserna är tillgängliga.

Om mjuk borttagning är aktiverat för Key Vault märker den här åtgärden endast certifikatet som ett borttaget certifikat. Det går inte att uppdatera ett borttaget certifikat. De kan bara läsas, återställas eller rensas.

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

Eftersom borttagningen av ett certifikat inte sker omedelbart behövs en tid efter beginDeleteCertificate att metoden anropas innan det borttagna certifikatet kan läsas, återställas eller rensas.

Iterera listor över certifikat

Med Hjälp av CertificateClient kan du hämta och iterera genom alla certifikat i ett certifikatvalv, samt genom alla borttagna certifikat och versioner av ett visst certifikat. Följande API-metoder är tillgängliga:

listPropertiesOfCertificates visar en lista över alla icke-borttagna certifikat efter deras namn, endast i de senaste versionerna.
listDeletedCertificates visar en lista över alla borttagna certifikat efter deras namn, endast i de senaste versionerna.
listPropertiesOfCertificateVersions visar en lista över alla versioner av ett certifikat baserat på ett certifikatnamn.

Som kan användas på följande sätt:

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

Alla dessa metoder returnerar alla tillgängliga resultat samtidigt. Om du vill hämta dem efter sidor lägger du till .byPage() direkt efter att du har anropat den API-metod som du vill använda, enligt följande:

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

Felsökning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg över HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Loggning kan också aktiveras vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Se vår felsökningsguide för information om hur du diagnostiserar olika felscenarier.

Nästa steg

Du hittar fler kodexempel via följande länkar:

Bidra

Om du vill bidra till det här biblioteket kan du läsa bidragsguiden om du vill veta mer om hur du skapar och testar koden.

Visningar

Dela via