Delen via

Clientbibliotheek voor Azure Key Vault-certificaten voor JavaScript - versie 4.9.0

  • Artikel

Azure Key Vault is een cloudservice die beveiligde opslag en geautomatiseerd beheer van certificaten biedt die worden gebruikt in een cloudtoepassing. Meerdere certificaten en meerdere versies van hetzelfde certificaat kunnen worden bewaard in 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 u meer wilt weten over Azure Key Vault, kunt u het volgende bekijken: Wat is Azure Key Vault?

Gebruik de clientbibliotheek voor Azure Key Vault-certificaten in uw Node.js-toepassing 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 worden gebruikt in de browser vanwege servicebeperkingen van Azure Key Vault. Raadpleeg dit document voor hulp.

Sleutelkoppelingen:

Slag

Momenteel ondersteunde omgevingen

Voorwaarden

Het pakket installeren

De Clientbibliotheek azure Key Vault-certificaten installeren met behulp van npm

npm install @azure/keyvault-certificates

De identiteitsbibliotheek installeren

Key Vault-clients verifiëren 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.

Verifiëren met Azure Active Directory

De Key Vault-service is afhankelijk van Azure Active Directory voor het verifiëren van aanvragen voor de BIJBEHORENDE API's. Het @azure/identity-pakket biedt verschillende referentietypen die uw toepassing hiervoor kan gebruiken. De LEESMIJ voor @azure/identity biedt meer informatie en voorbeelden om u op weg te helpen.

Als u wilt communiceren met de Azure Key Vault-service, moet u een exemplaar van de klasse CertificateClient maken, een kluis-URL en een referentieobject. 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 om te verifiëren en de bijbehorende referentietypen vindt u in de Azure Identity-documentatie.

Hier volgt een snel voorbeeld. Importeer eerst DefaultAzureCredential en CertificateClient:

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

Zodra deze zijn geïmporteerd, kunnen we verbinding maken met de sleutelkluisservice:

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

Sleutelbegrippen

  • De Certificates-client is de primaire interface voor interactie met de API-methoden met betrekking tot certificaten in de Azure Key Vault-API vanuit een JavaScript-toepassing. 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 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 key vault voorlopig verwijderen is 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.

De API-versie van de Azure Key Vault-service opgeven

Dit pakket maakt standaard gebruik van de nieuwste versie van de Azure Key Vault-service die 7.1is. 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:

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

Voorbeelden

De volgende secties bevatten codefragmenten die betrekking hebben op enkele algemene taken met behulp van Azure Key Vault-certificaten. De scenario's die hier worden behandeld, bestaan uit:

Een certificaat maken en instellen

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

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

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

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:

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

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

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

Een Key Vault-certificaat ophalen

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.

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

De volledige informatie van een certificaat ophalen

Het ontwerp van Azure Key Vault maakt scherp onderscheid tussen sleutels, geheimen en certificaten. De certificatenfuncties van de Key Vault-service zijn ontworpen om gebruik te maken van de mogelijkheden sleutels en geheimen. Laten we de samenstelling van een Key Vault-certificaat evalueren:

Wanneer een Key Vault-certificaat wordt gemaakt, worden er ook een adresseerbare sleutel en geheim gemaakt met dezelfde naam. Met de Key Vault-sleutel kunnen sleutelbewerkingen worden uitgevoerd en met het Key Vault-geheim kan de certificaatwaarde als geheim worden opgehaald. Een Key Vault-certificaat bevat ook metagegevens van openbare x509-certificaten. bron: samenstelling van een certificaat.

Wetende dat de persoonlijke sleutel is opgeslagen in een Key Vault-geheim, waarbij het openbare certificaat is opgenomen, kunnen we deze ophalen met behulp van de Key Vault Secrets-client.

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

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 u wilt werken met certificaten in PEM-indeling, kunt u de Key Vault-service van Azure laten weten dat u uw certificaten in PEM-indeling wilt maken en beheren door de eigenschap contentType op te geven op het moment van het maken van de certificaten.

In het volgende voorbeeld ziet u hoe u de openbare en persoonlijke onderdelen van een met PEM opgemaakt certificaat maakt en ophaalt met behulp van de Key Vault-clients voor certificaten en geheimen:

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

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 geeft alle certificaten in key vault weer.

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

Een certificaat bijwerken

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

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

Het certificaatbeleid kan als volgt afzonderlijk worden bijgewerkt met updateCertificatePolicy:

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

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 voorlopig verwijderen is ingeschakeld voor de Sleutelkluis, labelt deze bewerking alleen het certificaat als een verwijderd certificaat. Een verwijderd certificaat kan niet worden bijgewerkt. Ze kunnen alleen worden gelezen, hersteld of verwijderd.

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

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:

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

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:

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

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

Raadpleeg onze gids voor probleemoplossing voor meer informatie over het vaststellen van verschillende foutscenario's.

Volgende stappen

U vindt meer codevoorbeelden via de volgende koppelingen:

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

indrukken