Libreria client dei certificati di Azure Key Vault per JavaScript - versione 4.9.0

Articolo
10/17/2024

Azure Key Vault è un servizio cloud che fornisce archiviazione sicura e gestione automatizzata dei certificati usati in un'applicazione cloud. È possibile conservare più certificati e più versioni dello stesso certificato in Azure Key Vault. A ogni certificato nell'insieme di credenziali è associato un criterio che controlla il rilascio e la durata del certificato, insieme alle azioni da eseguire come certificati prossimi alla scadenza.

Per altre informazioni su Azure Key Vault, è consigliabile esaminare: Che cos'è Azure Key Vault?

Usare la libreria client per i certificati di Azure Key Vault nell'applicazione Node.js per:

Ottenere, impostare ed eliminare un certificato.
Aggiornare un certificato, i relativi attributi, autorità emittente, criteri, operazioni e contatti.
Eseguire il backup e il ripristino di un certificato.
Ottenere, eliminare o recuperare un certificato eliminato.
Ottenere tutte le versioni di un certificato.
Ottenere tutti i certificati.
Ottenere tutti i certificati eliminati.

Nota: questo pacchetto non può essere usato nel browser a causa delle limitazioni del servizio Azure Key Vault. Per indicazioni, vedere questo documento.

Collegamenti chiave:

Introduttiva

Ambienti attualmente supportati

versioni LTS di Node.js

Prerequisiti

Una sottoscrizione di Azure
Un azure Key Vault esistente. Se è necessario creare un insieme di credenziali delle chiavi, è possibile farlo nel portale di Azure seguendo i passaggi descritti in questo documento. In alternativa, usare l'interfaccia della riga di comando di Azure seguendo questi passaggi.

Installare il pacchetto

Installare la libreria client dei certificati di Azure Key Vault usando npm

npm install @azure/keyvault-certificates

Installare la libreria delle identità

I client di Key Vault eseguono l'autenticazione tramite la libreria di identità di Azure. Installarlo anche usando npm

npm install @azure/identity

Configurare TypeScript

Gli utenti typeScript devono avere installate definizioni dei tipi di nodo:

npm install @types/node

È anche necessario abilitare compilerOptions.allowSyntheticDefaultImports nel tsconfig.json. Si noti che se è stato abilitato compilerOptions.esModuleInterop, allowSyntheticDefaultImports è abilitato per impostazione predefinita. Per altre informazioni, vedere manuale delle opzioni del compilatore di TypeScript di .

Autenticazione con Azure Active Directory

Il servizio Key Vault si basa su Azure Active Directory per autenticare le richieste alle API. Il pacchetto @azure/identity offre diversi tipi di credenziali che l'applicazione può usare per eseguire questa operazione. Il file LEGGIMI per @azure/identity fornisce altri dettagli ed esempi per iniziare.

Per interagire con il servizio Azure Key Vault, è necessario creare un'istanza della classe CertificateClient, un URL dell'insieme di credenziali e un oggetto credenziali. Gli esempi illustrati in questo documento usano un oggetto credenziali denominato DefaultAzureCredential, appropriato per la maggior parte degli scenari, inclusi gli ambienti di sviluppo e produzione locali. È anche consigliabile usare un di identità gestita per l'autenticazione negli ambienti di produzione.

Per altre informazioni sui diversi modi di autenticazione e sui relativi tipi di credenziali corrispondenti, vedere la documentazione relativa all'identità di Azure .

Ecco un rapido esempio. Prima di tutto, importare DefaultAzureCredential e CertificateClient:

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

Dopo l'importazione, è possibile connettersi al servizio Key Vault:

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

Concetti chiave

Il client certificati è l'interfaccia principale per interagire con i metodi API correlati ai certificati nell'API di Azure Key Vault da un'applicazione JavaScript. Dopo l'inizializzazione, fornisce un set di base di metodi che possono essere usati per creare, leggere, aggiornare ed eliminare i certificati.
Una versione del certificato è una versione di un certificato nell'insieme di credenziali delle chiavi. Ogni volta che un utente assegna un valore a un nome di certificato univoco, viene creata una nuova versione del certificato. Il recupero di un certificato in base a un nome restituirà sempre il valore più recente assegnato, a meno che non venga fornita una versione specifica alla query.
eliminazione temporanea consente agli insiemi di credenziali delle chiavi di supportare l'eliminazione e l'eliminazione come due passaggi separati, quindi i certificati eliminati non vengono persi immediatamente. Ciò si verifica solo se l'insieme di credenziali delle chiavi ha abilitata per l'eliminazione temporanea.
È possibile generare un di backup del certificato da qualsiasi certificato creato. Questi backup vengono usati come dati binari e possono essere usati solo per rigenerare un certificato eliminato in precedenza.

Specifica della versione dell'API del servizio Azure Key Vault

Per impostazione predefinita, questo pacchetto usa la versione più recente del servizio Azure Key Vault 7.1. L'unica versione supportata è 7.0. È possibile modificare la versione del servizio usata impostando l'opzione serviceVersion nel costruttore client, come illustrato di seguito:

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

Esempi

Le sezioni seguenti forniscono frammenti di codice che illustrano alcune delle attività comuni che usano i certificati di Azure Key Vault. Gli scenari illustrati di seguito sono costituiti da:

Creazione e impostazione di un certificato.
Ottenere un certificato di Key Vault.
Ottenere le informazioni complete di un certificato.
Certificati in formato PEM.
Elencare tutti i certificati.
Aggiornamento di un certificato.
Eliminazione di un certificato.
L'iterazione di elenchi di certificati.

Creazione e impostazione di un certificato

beginCreateCertificate crea un certificato da archiviare in Azure Key Vault. Se esiste già un certificato con lo stesso nome, viene creata una nuova versione del certificato.

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

Oltre al nome del certificato e dei criteri, è anche possibile passare le proprietà seguenti in un terzo argomento con valori facoltativi:

enabled: valore booleano che determina se il certificato può essere usato o meno.
tags: qualsiasi set di valori chiave che può essere usato per cercare e filtrare i certificati.

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

La chiamata a beginCreateCertificate con lo stesso nome creerà una nuova versione dello stesso certificato, che avrà gli attributi forniti più recenti.

Poiché i certificati richiedono del tempo per la creazione completa, beginCreateCertificate restituisce un oggetto poller che tiene traccia dell'operazione a esecuzione prolungata sottostante in base alle linee guida riportate di seguito: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Il poller ricevuto consentirà di ottenere il certificato creato chiamando per poller.getResult(). È anche possibile attendere il completamento dell'eliminazione, eseguendo singole chiamate al servizio fino alla creazione del certificato o attendendo il completamento del processo:

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

Un altro modo per attendere che il certificato sia firmato consiste nell'eseguire singole chiamate, come indicato di seguito:

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

Recupero di un certificato di Key Vault

Il modo più semplice per leggere i certificati dall'insieme di credenziali consiste nel ottenere un certificato in base al nome. getCertificate recupererà la versione più recente del certificato, insieme ai criteri del certificato. Facoltativamente, è possibile ottenere una versione diversa del certificato chiamando getCertificateVersion se si specifica la versione. getCertificateVersion non restituisce i criteri del certificato.

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

Ottenere le informazioni complete di un certificato

La progettazione di Azure Key Vault distingue in modo netto le chiavi, i segreti e i certificati. Le funzionalità dei certificati del servizio Key Vault sono state progettate usando le funzionalità chiavi e segreti. Si valuterà ora la composizione di un certificato dell'insieme di credenziali delle chiavi:

Quando viene creato un certificato di Key Vault, viene creata anche una chiave e un segreto indirizzabili con lo stesso nome. La chiave dell'insieme di credenziali delle chiavi consente operazioni chiave e il segreto dell'insieme di credenziali delle chiavi consente il recupero del valore del certificato come segreto. Un certificato di Key Vault contiene anche metadati del certificato x509 pubblici. origine : composizione di un certificato.

Sapendo che la chiave privata viene archiviata in un segreto dell'insieme di credenziali delle chiavi, con il certificato pubblico incluso, è possibile recuperarla usando il client dei segreti dell'insieme di credenziali delle chiavi.

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

Si noti che, per impostazione predefinita, il tipo di contenuto dei certificati è PKCS 12. Specificando il tipo di contenuto del certificato, sarà possibile recuperarlo in formato PEM. Prima di mostrare come creare certificati PEM, si esaminerà prima di tutto come recuperare una chiave privata PEM da un certificato PKCS 12.

Usando openssl, è possibile recuperare il certificato pubblico in formato PEM usando il comando seguente:

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

È anche possibile usare openssl per recuperare la chiave privata, come indicato di seguito:

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

Si noti che in entrambi i casi, openssl richiederà la password usata per creare il certificato. Il codice di esempio usato finora non ha specificato una password, quindi è possibile aggiungere -passin 'pass:' alla fine di ogni comando.

Certificati in formato PEM

Per usare i certificati in formato PEM, è possibile indicare al servizio Key Vault di Azure di creare e gestire i certificati in formato PEM fornendo la proprietà contentType al momento della creazione dei certificati.

L'esempio seguente illustra come creare e recuperare le parti pubbliche e private di un certificato con formattazione PEM usando i client di Key Vault per Certificati e segreti:

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

Tenere presente che il certificato pubblico si troverà nello stesso BLOB di contenuto della chiave privata. È possibile usare le intestazioni PEM per estrarle di conseguenza.

Elencare tutti i certificati

listPropertiesOfCertificates elenca tutti i certificati nell'insieme di credenziali delle chiavi.

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

Aggiornamento di un certificato

Gli attributi del certificato possono essere aggiornati a una versione del certificato esistente con updateCertificate, come indicato di seguito:

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

I criteri del certificato possono anche essere aggiornati singolarmente con updateCertificatePolicy, come indicato di seguito:

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

Eliminazione di un certificato

Il metodo beginDeleteCertificate imposta un certificato per l'eliminazione. Questo processo verrà eseguito in background non appena sono disponibili le risorse necessarie.

Se di eliminazione temporanea è abilitato per l'insieme di credenziali delle chiavi, questa operazione etichetta solo il certificato come certificato eliminato. Non è possibile aggiornare un certificato eliminato. Possono essere letti, recuperati o eliminati solo.

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

Poiché l'eliminazione di un certificato non viene eseguita immediatamente, è necessario tempo dopo che il metodo beginDeleteCertificate viene chiamato prima che il certificato eliminato sia disponibile per essere letto, recuperato o eliminato.

Iterazione di elenchi di certificati

Usando CertificateClient, è possibile recuperare e scorrere tutti i certificati in un insieme di credenziali dei certificati, nonché tramite tutti i certificati eliminati e le versioni di un certificato specifico. Sono disponibili i metodi API seguenti:

listPropertiesOfCertificates elenca tutti i certificati non eliminati in base ai nomi, solo nelle versioni più recenti.
listDeletedCertificates elenca tutti i certificati eliminati in base ai nomi, solo nelle versioni più recenti.
listPropertiesOfCertificateVersions elenca tutte le versioni di un certificato in base a un nome di certificato.

Che può essere usato come segue:

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

Tutti questi metodi restituiranno tutti i risultati disponibili contemporaneamente. Per recuperarli in base alle pagine, aggiungere .byPage() subito dopo aver richiamato il metodo API da usare, come indicato di seguito:

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

Risoluzione dei problemi

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel nel @azure/logger:

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

setLogLevel("info");

Per informazioni dettagliate su come diagnosticare vari scenari di errore, vedere la guida alla risoluzione dei problemi .

Passaggi successivi

Per altri esempi di codice, vedere i collegamenti seguenti:

esempi di certificati dell'insieme di credenziali delle chiavi (JavaScript)
di esempi di certificati dell'insieme di credenziali delle chiavi (TypeScript)
test case di certificati dell'insieme di credenziali delle chiavi

Contribuire

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

impressioni

Condividi tramite