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

Artikel
10/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 behållas 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 nästan 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 Portal genom att följa stegen i det här dokumentet. Du kan också använda Azure CLI genom att följa de här stegen.

Installera paketet

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

npm install @azure/keyvault-certificates

Installera identitetsbiblioteket

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

npm install @azure/identity

Konfigurera TypeScript

TypeScript-användare måste ha definitioner av nodtyp installerade:

npm install @types/node

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

Autentisera med Azure Active Directory

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

För att kunna interagera med Azure Key Vault-tjänsten måste du skapa en instans av klassen CertificateClient, en url för valv och ett autentiseringsobjekt. Exemplen som visas i det här dokumentet använder ett autentiseringsobjekt 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 dokumentationen Azure Identity.

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

Klienten Certifikat är det primära gränssnittet för att interagera med API-metoderna som är 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 tillhandahålls till frågan.
Mjuk borttagning tillåter att Key Vaults stöder borttagning och rensning som två separata steg, så borttagna certifikat går inte omedelbart förlorade. Detta händer bara om Key Vault har mjuk borttagning aktiverat.
En certifikatsäkerhetskopiering 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 Azure Key Vault-tjänstens API-version

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.
Lista alla certifikat.
Uppdatera ett certifikat.
ta bort ett certifikat.
Itererande listor över certifikat.

Skapa och ange ett certifikat

beginCreateCertificate skapar 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 med 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 det tar lite tid att skapa certifikat 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 är signerat ä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 med 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 Vaults design gör skarpa distinktioner 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 även en adresserbar nyckel och hemlighet med samma namn. Key Vault-nyckeln tillåter nyckelåtgärder och 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ättning av ett certifikat.

Med vetskapen om 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 hjälp av opensslkan du 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 enligt följande:

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

Observera att i båda fallen ber openssl dig om lösenordet som används för att skapa certifikatet. Exempelkoden som vi har använt hittills har inte angett något lösenord, så du kan lägga till -passin 'pass:' 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 tillhandahålla egenskapen contentType 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 key vault-klienterna 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-huvudena för att extrahera dem i enlighet med detta.

Visa en lista över alla certifikat

listPropertiesOfCertificates visar 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 updateCertificateenligt 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 updateCertificatePolicyenligt 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 ställer in 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 aktiverad för Nyckelvalvet 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 krävs en viss tid efter att metoden beginDeleteCertificate anropas innan det borttagna certifikatet kan läsas, återställas eller rensas.

Itererande 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 versionerna av ett visst certifikat. Följande API-metoder är tillgängliga:

listPropertiesOfCertificates visar alla dina icke-borttagna certifikat efter deras namn, endast i de senaste versionerna.
listDeletedCertificates listar 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 via 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 med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Mer information om hur du diagnostiserar olika felscenarier finns i felsökningsguiden för .

Nästa steg

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

Bidragande

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.

visningar

Dela via