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

  • Articolo

Azure Key Vault è un servizio cloud che offre archiviazione sicura e gestione automatizzata dei certificati usati in un'applicazione cloud. È possibile conservare più certificati e più versioni dello stesso certificato nel Key Vault di Azure. 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, è possibile consultare: 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à di certificazione, criteri, operazioni e contatti.
  • Eseguire il backup e il ripristino di un certificato.
  • Ottenere, ripulire 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 di Azure Key Vault. Per indicazioni, fare riferimento a questo documento.

Collegamenti principali:

Introduzione

Ambienti attualmente supportati

Prerequisiti

Installare il pacchetto

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

npm install @azure/keyvault-certificates

Installare la libreria di identità

Key Vault client 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 le definizioni dei tipi di nodo installate:

npm install @types/node

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

Autenticazione con Azure Active Directory

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

Per interagire con il servizio azure Key Vault, è necessario creare un'istanza della CertificateClient classe, un URL dell'insieme di credenziali e un oggetto credenziale. 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. È inoltre consigliabile usare un'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 di Identità di Azure.

Ecco un esempio rapido. Per prima cosa, 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 Certificates è 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 certificati.
  • Una versione del certificato è una versione di un certificato nel Key Vault. 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.
  • L'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 il Key Vault ha abilitato l'eliminazione temporanea.
  • È possibile generare un backup del certificato da qualsiasi certificato creato. Questi backup sono 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, ovvero 7.1. L'unica altra 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",
});

Esempio

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

Creazione e impostazione di un certificato

beginCreateCertificatecrea un certificato da archiviare nel Key Vault di Azure. 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 utilizzato 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é la creazione completa dei certificati richiede tempo, beginCreateCertificate restituisce un oggetto poller che tiene traccia dell'operazione long running sottostante in base alle linee guida: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Il poller ricevuto consentirà di ottenere il certificato creato chiamando a 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 venga 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();

Ottenere 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 chiavi, segreti e certificati. Le funzionalità dei certificati del servizio Key Vault sono state progettate sfruttando le funzionalità Chiavi e segreti. Si valuterà ora la composizione di un certificato Key Vault:

Quando viene creato un certificato Key Vault, vengono creati anche una chiave e un segreto indirizzabili con lo stesso nome. La chiave Key Vault consente operazioni di chiave e il segreto Key Vault consente il recupero del valore del certificato come segreto. Un certificato Key Vault contiene inoltre metadati del certificato x509 pubblico. Origine: composizione di un certificato.

Sapendo che la chiave privata viene archiviata in un segreto Key Vault, con il certificato pubblico incluso, è possibile recuperarla usando il client dei segreti Key Vault.

// 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 specificando la contentType proprietà al momento della creazione dei certificati.

Nell'esempio seguente viene illustrato come creare e recuperare le parti pubbliche e private di un certificato con formattazione PEM usando i client 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

listPropertiesOfCertificatesverranno elencati tutti i certificati nel 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();

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 beginDeleteCertificate metodo imposta un certificato per l'eliminazione. Questo processo verrà eseguito in background non appena saranno disponibili le risorse necessarie.

Se l'eliminazione temporanea è abilitata per il Key Vault, questa operazione contrassegnerà 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 beginDeleteCertificate metodo viene chiamato prima che il certificato eliminato sia disponibile per la lettura, il ripristino o l'eliminazione.

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 verranno elencati 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 verranno elencate 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 che si vuole 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 consente di 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 in @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:

Contributo

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

Impression