Delen via

Azure Key Vault Certificaten-clientbibliotheek voor JavaScript - versie 4.8.0

  • Artikel

Azure Key Vault is een cloudservice die veilige opslag en geautomatiseerd beheer van certificaten biedt die in een cloudtoepassing 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 dat de uitgifte en levensduur van het certificaat bepaalt, samen met acties die moeten worden uitgevoerd als certificaten bijna verlopen.

Als u meer wilt weten over Azure Key Vault, kunt u het volgende lezen: 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.
  • Een certificaat, de bijbehorende kenmerken, de uitgever, het beleid, de bewerking en de contactpersonen bijwerken.
  • Een back-up maken van een certificaat en deze herstellen.
  • Een verwijderd certificaat ophalen, opschonen of herstellen.
  • Alle versies van een certificaat ophalen.
  • Alle certificaten ophalen.
  • Alle verwijderde certificaten ophalen.

Opmerking: dit pakket kan niet worden gebruikt in de browser vanwege azure Key Vault servicebeperkingen. Raadpleeg dit document voor hulp.

Belangrijke koppelingen:

Aan de slag

Momenteel ondersteunde omgevingen

Vereisten

Het pakket installeren

De clientbibliotheek voor Azure Key Vault Certificates installeren met 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 behulp van npm

npm install @azure/identity

TypeScript configureren

TypeScript-gebruikers moeten knooppunttypedefinities hebben geïnstalleerd:

npm install @types/node

U moet ook inschakelen compilerOptions.allowSyntheticDefaultImports in uw tsconfig.json. Houd er rekening mee dat als u hebt ingeschakeld compilerOptions.esModuleInterop, 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 om aanvragen voor de API's te verifiëren. Het @azure/identity pakket biedt verschillende referentietypen die uw toepassing kan gebruiken om dit te doen. Leesmij voor @azure/identity biedt meer details en voorbeelden om u op weg te helpen.

Als u wilt communiceren met de Azure Key Vault-service, moet u een exemplaar van de CertificateClient klasse, een kluis-URL en een referentieobject maken. De voorbeelden in dit document gebruiken een referentieobject met de naam DefaultAzureCredential, dat geschikt is 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 Documentatie voor Azure Identity.

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

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

Zodra deze zijn geïmporteerd, kunnen we vervolgens 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);

Belangrijkste concepten

  • De certificatenclient is de primaire interface voor interactie met de API-methoden die zijn gerelateerd aan certificaten in de Azure Key Vault API vanuit een JavaScript-toepassing. Zodra het is geïnitialiseerd, biedt het een basisset met methoden die kunnen worden gebruikt om certificaten te maken, te lezen, bij te werken en te verwijderen.
  • 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. Als u een certificaat op basis van een naam opvraagt, wordt altijd de meest recente waarde geretourneerd die is toegewezen, tenzij een specifieke versie wordt opgegeven voor de query.
  • Met voorlopig verwijderen kunnen Key Vaults verwijdering en opschonen ondersteunen als twee afzonderlijke stappen, zodat verwijderde certificaten niet onmiddellijk verloren gaan. Dit gebeurt alleen als voor de 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, namelijk 7.1. De enige andere versie die wordt ondersteund, is 7.0. U kunt de gebruikte serviceversie wijzigen door de optie serviceVersion in de clientconstructor in te stellen, 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

beginCreateCertificatemaakt een certificaat dat moet worden opgeslagen in de 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 kan worden gebruikt of niet.
  • tags: elke set sleutelwaarden die kan worden gebruikt om certificaten te zoeken en te filteren.
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 met beginCreateCertificate dezelfde naam aanroept, wordt een nieuwe versie van hetzelfde certificaat gemaakt, die de meest recente kenmerken heeft.

Omdat het even duurt voordat certificaten volledig zijn gemaakt, beginCreateCertificate retourneert een poller-object dat de onderliggende langlopende 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 aan te roepen naar poller.getResult(). 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 door 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 ophalen door aan te roepen getCertificateVersion als u de versie opgeeft. getCertificateVersion retourneert niet het beleid van het certificaat.

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 een scherp onderscheid tussen sleutels, geheimen en certificaten. De functies voor certificaten van de Key Vault-service zijn ontworpen met behulp van de mogelijkheden voor sleutels en geheimen. Laten we de samenstelling van een Key Vault-certificaat evalueren:

Wanneer er een Key Vault-certificaat wordt gemaakt, worden er ook een adresseerbare sleutel en een 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 openbare metagegevens voor x509-certificaten. Bron: Samenstelling van een certificaat.

Wetende dat de persoonlijke sleutel is opgeslagen in een Key Vault Geheim, met het openbare certificaat inbegrepen, 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);

Houd er rekening mee dat het inhoudstype van de certificaten standaard PKCS 12 is. 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 een geheime PEM-sleutel kunt ophalen uit een PKCS 12-certificaat.

Met behulp van 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 als volgt gebruiken openssl om de persoonlijke sleutel op te halen:

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

Houd er rekening mee dat in beide gevallen openssl u vraagt om het wachtwoord dat is gebruikt om het certificaat te maken. De voorbeeldcode die we tot nu toe hebben gebruikt, heeft geen wachtwoord opgegeven, dus u kunt toevoegen -passin 'pass:' 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 uw certificaten in PEM-indeling moeten worden gemaakt en beheerd door de contentType eigenschap op te geven op het moment dat de certificaten worden gemaakt.

In het volgende voorbeeld ziet u hoe u de openbare en persoonlijke onderdelen van een certificaat met PEM-indeling 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

listPropertiesOfCertificatesbevat alle certificaten in de 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();

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 beleid van het certificaat kan ook afzonderlijk worden bijgewerkt met updateCertificatePolicy, 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() {
  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 beginDeleteCertificate methode 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 Key Vault, labelt deze bewerking het certificaat alleen als een verwijderd certificaat. Een verwijderd certificaat kan niet worden bijgewerkt. Ze kunnen alleen worden gelezen, hersteld of opgeschoond.

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 direct plaatsvindt, duurt het enige tijd nadat de beginDeleteCertificate methode is aangeroepen voordat het verwijderde certificaat kan worden gelezen, hersteld of opgeschoond.

Lijsten met certificaten herhalen

Met behulp van de CertificateClient kunt u alle certificaten in een certificaatkluis ophalen en herhalen, evenals door 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 hun nieuwste versies.
  • listDeletedCertificates geeft alle verwijderde certificaten weer op hun naam, alleen in de nieuwste versies.
  • listPropertiesOfCertificateVersions geeft alle versies van een certificaat weer op basis van een certificaatnaam.

Deze 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 per pagina wilt ophalen, voegt u deze als volgt toe .byPage() nadat u de API-methode hebt aangeroepen die u wilt gebruiken:

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

Problemen oplossen

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

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

setLogLevel("info");

Zie onze gids voor probleemoplossing voor meer informatie over het diagnosticeren van verschillende foutscenario's.

Volgende stappen

Meer codevoorbeelden vindt u via de volgende koppelingen:

Bijdragen

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

Weergaven