Azure Key Vault Certificates clientbibliotheek voor JavaScript - versie 4.10.3

Azure Key Vault is een clouddienst die veilige opslag en geautomatiseerd beheer biedt van certificaten die in een cloudapplicatie worden gebruikt. Meerdere certificaten en meerdere versies van hetzelfde certificaat kunnen worden bewaard in de Azure Key Vault. Aan elk certificaat in de kluis is een beleid gekoppeld waarmee de uitgifte en levensduur van het certificaat worden beheerd, samen met acties die moeten worden uitgevoerd als certificaten bijna verlopen.

Als je meer over Azure Key Vault wilt weten, kun je het volgende bekijken: Wat is Azure Key Vault?

Gebruik de clientbibliotheek voor Azure Key Vault certificaten in je Node.js applicatie om:

  • Een certificaat ophalen, instellen en verwijderen.
  • Werk een certificaat, de bijbehorende kenmerken, verlener, beleid, bewerking en contactpersonen bij.
  • Een back-up maken en een certificaat herstellen.
  • Een verwijderd certificaat ophalen, opschonen of herstellen.
  • Haal alle versies van een certificaat op.
  • Haal alle certificaten op.
  • Haal alle verwijderde certificaten op.

Opmerking: Dit pakket kan niet in de browser worden gebruikt vanwege Azure Key Vault servicebeperkingen, raadpleeg dit document voor richtlijnen.

Sleutelkoppelingen:

Slag

Momenteel ondersteunde omgevingen

Voorwaarden

Het pakket installeren

Installeer de Azure Key Vault Certificates clientbibliotheek met npm

npm install @azure/keyvault-certificates

De identiteitsbibliotheek installeren

Key Vault-clients authenticeren zich met behulp van de Azure Identity Library. Installeer het ook met npm

npm install @azure/identity

TypeScript configureren

TypeScript-gebruikers moeten knooppunttypedefinities hebben geïnstalleerd:

npm install @types/node

U moet ook compilerOptions.allowSyntheticDefaultImports inschakelen in uw tsconfig.json. Houd er rekening mee dat als u compilerOptions.esModuleInterophebt ingeschakeld, allowSyntheticDefaultImports standaard is ingeschakeld. Zie het handboek voor compileropties van TypeScript voor meer informatie.

Authenticatie met Azure Active Directory

De Key Vault-service is afhankelijk van Azure Active Directory om verzoeken aan zijn API's te authenticeren. Het @azure/identity-pakket biedt verschillende referentietypen die uw toepassing hiervoor kan gebruiken. De README voor @azure/identity geeft meer details en voorbeelden om je op weg te helpen.

Om met de Azure Key Vault-service te kunnen interageren, moet je een instantie van de klasse CertificateClient aanmaken, een vault url en een credential-object. In de voorbeelden in dit document wordt een referentieobject met de naam DefaultAzureCredentialgebruikt. Dit is geschikt voor de meeste scenario's, waaronder lokale ontwikkel- en productieomgevingen. Daarnaast raden we u aan een beheerde identiteit te gebruiken voor verificatie in productieomgevingen.

Meer informatie over verschillende manieren van authenticatie en hun bijbehorende credentialtypes vindt u in de Azure Identiteitsdocumentatie.

Hier volgt een snel voorbeeld. Importeer eerst DefaultAzureCredential en CertificateClient. Zodra deze zijn geïmporteerd, kunnen we verbinding maken met de sleutelkluisservice:

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

Sleutelbegrippen

  • De is de primaire interface om te communiceren met de API>-methoden die verband houden met certificaten in de Azure Key Vault API vanuit een JavaScript-applicatie. Zodra deze is geïnitialiseerd, biedt het een basisset methoden die kunnen worden gebruikt voor het maken, lezen, bijwerken en verwijderen van certificaten.
  • Een certificaatversie is een versie van een certificaat in de Key Vault. Telkens wanneer een gebruiker een waarde toewijst aan een unieke certificaatnaam, wordt er een nieuwe versie van dat certificaat gemaakt. Het ophalen van een certificaat op basis van een naam retourneert altijd de meest recente waarde die is toegewezen, tenzij er een specifieke versie aan de query wordt verstrekt.
  • voorlopig verwijderen kan Key Vaults ondersteuning bieden voor verwijdering en opschonen als twee afzonderlijke stappen, zodat verwijderde certificaten niet onmiddellijk verloren gaan. Dit gebeurt alleen als de Key Vault soft-delete heeft ingeschakeld.
  • Een certificaatback-up kan worden gegenereerd op basis van elk gemaakt certificaat. Deze back-ups worden geleverd als binaire gegevens en kunnen alleen worden gebruikt om een eerder verwijderd certificaat opnieuw te genereren.

Het specificeren van de Azure Key Vault service API-versie

Standaard gebruikt dit pakket de nieuwste Azure Key Vault service-versie, namelijk 7.1. De enige andere versie die wordt ondersteund, is 7.0. U kunt de serviceversie wijzigen die wordt gebruikt door de optie in te stellen serviceVersion in de clientconstructor, zoals hieronder wordt weergegeven:

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

Voorbeelden

De volgende secties bevatten codefragmenten die enkele van de veelvoorkomende taken behandelen met Azure Key Vault-certificaten. De scenario's die hier worden behandeld, bestaan uit:

Een certificaat maken en instellen

beginCreateCertificate maakt een certificaat aan dat in de Azure Key Vault wordt opgeslagen. Als er al een certificaat met dezelfde naam bestaat, wordt er een nieuwe versie van het certificaat gemaakt.

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

Naast de naam van het certificaat en het beleid kunt u ook de volgende eigenschappen doorgeven in een derde argument met optionele waarden:

  • enabled: een Booleaanse waarde die bepaalt of het certificaat al dan niet kan worden gebruikt.
  • tags: elke set sleutelwaarden die kunnen worden gebruikt voor het zoeken en filteren van certificaten.
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,
});

Als u aanroept naar beginCreateCertificate met dezelfde naam, wordt een nieuwe versie van hetzelfde certificaat gemaakt, die de meest recente kenmerken bevat.

Omdat het enige tijd duurt voordat certificaten volledig zijn gemaakt, retourneert beginCreateCertificate een poller-object dat de onderliggende langdurige bewerking bijhoudt volgens onze richtlijnen: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Met de ontvangen poller kunt u het gemaakte certificaat ophalen door naar poller.getResult()aan te roepen. U kunt ook wachten totdat het verwijderen is voltooid, door afzonderlijke service-aanroepen uit te voeren totdat het certificaat is gemaakt of door te wachten totdat het proces is voltooid:

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

Een andere manier om te wachten totdat het certificaat is ondertekend, is als volgt afzonderlijke aanroepen uit te voeren:

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

Een Key Vault-certificaat verkrijgen

De eenvoudigste manier om certificaten terug te lezen uit de kluis, is door een certificaat op naam op te halen. getCertificate haalt de meest recente versie van het certificaat op, samen met het beleid van het certificaat. U kunt desgewenst een andere versie van het certificaat verkrijgen door getCertificateVersion aan te roepen als u de versie opgeeft. getCertificateVersion retourneert het beleid van het certificaat niet.

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

De volledige informatie van een certificaat ophalen

Het ontwerp van Azure Key Vault maakt scherpe onderscheidingen tussen sleutels, geheimen en certificaten. De Certificaten-functies van de Key Vault-dienst zijn ontworpen met gebruik van de Keys and Secrets-mogelijkheden. Laten we de samenstelling van een Key Vault-certificaat evalueren:

Wanneer een Key Vault-certificaat wordt aangemaakt, worden ook een adresseerbare sleutel en geheim met dezelfde naam aangemaakt. De Key Vault-sleutel maakt sleuteloperaties mogelijk en het Key Vault geheim maakt het mogelijk om de certificaatwaarde als geheim op te halen. Een Key Vault-certificaat bevat ook publieke x509-certificaatmetadata. bron: samenstelling van een certificaat.

Wetende dat de privésleutel wordt opgeslagen in een Key Vault Secret, inclusief het publieke certificaat, kunnen we deze ophalen via de Key Vault Secrets-client.

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

Het inhoudstype van de certificaten is standaard PKCS 12. Door het inhoudstype van uw certificaat op te geven, kunt u het ophalen in PEM-indeling. Voordat u laat zien hoe u PEM-certificaten maakt, gaan we eerst kijken hoe u eerst een PEM-geheime sleutel ophaalt uit een PKCS 12-certificaat.

Met opensslkunt u het openbare certificaat in PEM-indeling ophalen met behulp van de volgende opdracht:

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

U kunt ook openssl gebruiken om de persoonlijke sleutel op te halen, als volgt:

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

In beide gevallen vraagt openssl u om het wachtwoord dat wordt gebruikt om het certificaat te maken. De voorbeeldcode die we tot nu toe hebben gebruikt, heeft geen wachtwoord opgegeven, dus u kunt -passin 'pass:' toevoegen aan het einde van elke opdracht.

Certificaten in PEM-indeling

Als je met certificaten in PEM-formaat wilt werken, kun je Azure's Key Vault service vertellen om je certificaten in PEM-formaat te maken en beheren door de contentType eigenschap op het moment van het aanmaken van de certificaten aan te geven.

Het volgende voorbeeld laat zien hoe je de publieke en private delen van een PEM-geformatteerd certificaat kunt aanmaken en ophalen met behulp van de Key Vault-clients voor Certificaten en Geheimen:

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

Houd er rekening mee dat uw openbare certificaat zich in dezelfde blob met inhoud bevindt als uw persoonlijke sleutel. U kunt de PEM-headers gebruiken om ze dienovereenkomstig te extraheren.

Alle certificaten weergeven

listPropertiesOfCertificates vermeldt alle certificaten in de 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);
}

Een certificaat bijwerken

De certificaatkenmerken kunnen als volgt worden bijgewerkt naar een bestaande certificaatversie met updateCertificate:

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

Het certificaatbeleid kan als volgt afzonderlijk worden bijgewerkt met updateCertificatePolicy:

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

Een certificaat verwijderen

Met de methode beginDeleteCertificate wordt een certificaat ingesteld voor verwijdering. Dit proces vindt plaats op de achtergrond zodra de benodigde resources beschikbaar zijn.

Als soft-delete is ingeschakeld voor de Key Vault, zal deze operatie het certificaat alleen labelen als een deleted certificaat. Een verwijderd certificaat kan niet worden bijgewerkt. Ze kunnen alleen worden gelezen, hersteld of verwijderd.

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

Omdat het verwijderen van een certificaat niet onmiddellijk plaatsvindt, is enige tijd nodig nadat de methode beginDeleteCertificate wordt aangeroepen voordat het verwijderde certificaat beschikbaar is om te worden gelezen, hersteld of verwijderd.

Lijsten met certificaten herhalen

Met behulp van CertificateClient kunt u alle certificaten in een certificaatkluis ophalen en herhalen, evenals via alle verwijderde certificaten en de versies van een specifiek certificaat. De volgende API-methoden zijn beschikbaar:

  • listPropertiesOfCertificates vermeldt al uw niet-verwijderde certificaten op hun naam, alleen in de nieuwste versies.
  • listDeletedCertificates vermeldt alle verwijderde certificaten op hun naam, alleen in de nieuwste versies.
  • listPropertiesOfCertificateVersions worden alle versies van een certificaat weergegeven op basis van een certificaatnaam.

Dit kan als volgt worden gebruikt:

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

Al deze methoden retourneren alle beschikbare resultaten tegelijk. Als u ze op pagina's wilt ophalen, voegt u .byPage() toe nadat u de API-methode hebt aangeroepen die u wilt gebruiken, als volgt:

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

Probleemoplossing

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

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

setLogLevel("info");

Zie onze probleemoplossingsgids voor details over hoe je verschillende storingsscenario's kunt diagnosticeren.

Volgende stappen

U vindt meer codevoorbeelden via de volgende koppelingen:

Bijdragen

Als je wilt bijdragen aan deze bibliotheek, lees dan de bijdragende gids om meer te weten te komen over hoe je de code bouwt en test.

  • Last updated on