Condividi tramite

Azure Key Vault Certificates client library for JavaScript - versione 4.10.3

Azure Key Vault è un servizio cloud che fornisce archiviazione sicura e gestione automatizzata dei certificati utilizzati in tutta un'applicazione cloud. Più certificati, e più versioni dello stesso certificato, possono essere conservati 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.

Se vuoi saperne di più su Azure Key Vault, potresti voler rivedere: Cos'è Azure Key Vault?

Usa la libreria client per Azure Key Vault certificati nella tua domanda 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 utilizzato nel browser a causa di Azure Key Vault limitazioni del servizio, si prega di consultare questo documento per indicazioni.

Collegamenti chiave:

Introduttiva

Ambienti attualmente supportati

Prerequisiti

  • Un abbonamento Azure
  • Un Azure Key Vault esistente. Se devi creare un caveau delle chiavi, puoi farlo nel portale di Azure seguendo i passaggi in questo documento. In alternativa, usa il interfaccia della riga di comando di Azure seguendo questi passaggi.

Installare il pacchetto

Installa la libreria client Azure Key Vault Certificates usando npm

npm install @azure/keyvault-certificates

Installare la libreria delle identità

I client Key Vault si autenticano utilizzando la libreria Azure Identity. 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 sue API. Il pacchetto @azure/identity offre diversi tipi di credenziali che l'applicazione può usare per eseguire questa operazione. Il README per @azure/identity fornisce ulteriori dettagli e esempi per iniziare.

Per interagire con il servizio Azure Key Vault, dovrai creare un'istanza della classe CertificateClient, un URL vault 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.

Puoi trovare maggiori informazioni sui diversi modi di autenticazione e sui relativi tipi di credenziali nel Azure Documentazione dell'identità.

Ecco un rapido esempio. Prima di tutto, importare DefaultAzureCredential e CertificateClient. Dopo l'importazione, è possibile connettersi al servizio Key Vault:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Lastly, create our certificates client and connect to the service
const client = new CertificateClient(url, credential);

Concetti chiave

  • Il client Certificates è l'interfaccia principale per interagire con i metodi API relativi ai certificati nell'API Azure Key Vault provenienti 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 Certificate è 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.
  • 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. Questo accade solo se il Key Vault ha attivato soft-delete.
  • È 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.

Specificare la versione API del servizio Azure Key Vault

Di default, questo pacchetto utilizza l'ultima versione del servizio Azure Key Vault, ovvero 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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Change the Azure Key Vault service API version being used via the `serviceVersion` option
const client = new CertificateClient(url, credential, {
  serviceVersion: "7.5",
});

Esempi

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

Creazione e impostazione di un certificato

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
});

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.
import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};
const enabled = true;
const tags = {
  myCustomTag: "myCustomTagsValue",
};

await client.beginCreateCertificate(certificateName, certificatePolicy, {
  enabled,
  tags,
});

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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

// You can use the pending certificate immediately:
const pendingCertificate = poller.getResult();

// Or you can wait until the certificate finishes being signed:
const keyVaultCertificate = await poller.pollUntilDone();
console.log(keyVaultCertificate);

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

console.log(`The certificate ${certificateName} is fully created`);

Ottenere un certificato 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.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

const latestCertificate = await client.getCertificate(certificateName);
console.log(`Latest version of the certificate ${certificateName}: `, latestCertificate);
const specificCertificate = await client.getCertificateVersion(
  certificateName,
  latestCertificate.properties.version,
);
console.log(
  `The certificate ${certificateName} at the version ${latestCertificate.properties.version}: `,
  specificCertificate,
);

Ottenere le informazioni complete di un certificato

Il design di Azure Key Vault fa distinzioni nette tra Chiavi, Segreti e Certificati. Le funzionalità Certificati del servizio Key Vault sono state progettate sfruttando le sue funzionalità Chiavi e Segreti. Valutiamo la composizione di un certificato Key Vault:

Quando viene creato un certificato Key Vault, vengono creati anche una chiave indirizzabile e un segreto con lo stesso nome. La chiave Key Vault consente operazioni con la chiave e il Key Vault secret consente il recupero del valore del certificato come segreto. Un certificato Key Vault contiene anche i metadati pubblici del certificato x509. origine : composizione di un certificato.

Sapendo che la chiave privata è memorizzata in un Key Vault Secret, con il certificato pubblico incluso, possiamo recuperarla utilizzando il client Key Vault Secrets.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { writeFileSync } from "node:fs";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const secretClient = new SecretClient(keyVaultUrl, credential);

const certificateName = "MyCertificateName";

// Assuming you've already created a Key Vault certificate,
// and that certificateName contains the name of your certificate
const certificateSecret = await secretClient.getSecret(certificateName);

// Here we can find both the private key and the public certificate, in PKCS 12 format:
const PKCS12Certificate = certificateSecret.value!;

// You can write this into a file:
writeFileSync("myCertificate.p12", PKCS12Certificate);

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

Se vuoi lavorare con i certificati in formato PEM, puoi chiedere al servizio Key Vault di Azure di creare e gestire i tuoi certificati in formato PEM fornendo la proprietà contentType al momento della creazione dei certificati.

Il seguente esempio mostra come creare e recuperare le parti pubbliche e private di un certificato formattato PEM utilizzando i client Key Vault per Certificati e Segreti:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);
const secretClient = new SecretClient(keyVaultUrl, credential);
// Creating the certificate
const certificateName = "MyCertificate";
const createPoller = await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
  contentType: "application/x-pem-file", // Here you specify you want to work with PEM certificates.
});
await createPoller.pollUntilDone();

// Getting the PEM formatted private key and public certificate:
const certificateSecret = await secretClient.getSecret(certificateName);
const PEMPair = certificateSecret.value!;

console.log(PEMPair);

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 elencherà tutti i certificati nel Key Vault.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const certificateProperties of client.listPropertiesOfCertificates()) {
  console.log("Certificate properties: ", certificateProperties);
}
for await (const deletedCertificate of client.listDeletedCertificates()) {
  console.log("Deleted certificate: ", deletedCertificate);
}
for await (const certificateProperties of client.listPropertiesOfCertificateVersions(
  certificateName,
)) {
  console.log("Certificate properties: ", certificateProperties);
}

Aggiornamento di un certificato

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

const result = await client.getCertificate(certificateName);
await client.updateCertificateProperties(certificateName, result.properties.version, {
  enabled: false,
  tags: {
    myCustomTag: "myCustomTagsValue",
  },
});

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

const result = client.getCertificate(certificateName);
// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
await client.updateCertificatePolicy(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
});

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 soft-delete è abilitato per il Key Vault, questa operazione etichettarà il certificato solo come certificato deleted. Non è possibile aggiornare un certificato eliminato. Possono essere letti, recuperati o eliminati solo.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

const poller = await client.beginDeleteCertificate(certificateName);

// You can use the deleted certificate immediately:
const deletedCertificate = poller.getResult();

// The certificate is being deleted. Only wait for it if you want to restore it or purge it.
await poller.pollUntilDone();

// You can also get the deleted certificate this way:
await client.getDeletedCertificate(certificateName);

// Deleted certificates can also be recovered or purged.

// recoverDeletedCertificate returns a poller, just like beginDeleteCertificate.
// const recoverPoller = await client.beginRecoverDeletedCertificate(certificateName);
// await recoverPoller.pollUntilDone();

// If a certificate is done and the Key Vault has soft-delete enabled, the certificate can be purged with:
await client.purgeDeletedCertificate(certificateName);

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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const certificateProperties of client.listPropertiesOfCertificates()) {
  console.log("Certificate properties: ", certificateProperties);
}
for await (const deletedCertificate of client.listDeletedCertificates()) {
  console.log("Deleted certificate: ", deletedCertificate);
}
for await (const certificateProperties of client.listPropertiesOfCertificateVersions(
  certificateName,
)) {
  console.log("Certificate properties: ", certificateProperties);
}

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:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const keyVaultUrl = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

for await (const page of client.listPropertiesOfCertificates().byPage()) {
  for (const certificateProperties of page) {
    console.log("Certificate properties: ", certificateProperties);
  }
}
for await (const page of client.listDeletedCertificates().byPage()) {
  for (const deletedCertificate of page) {
    console.log("Deleted certificate: ", deletedCertificate);
  }
}
for await (const page of client.listPropertiesOfCertificateVersions(certificateName).byPage()) {
  for (const certificateProperties of page) {
    console.log("Properties of certificate: ", certificateProperties);
  }
}

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

Consulta la nostra guida risoluzione dei problemi per dettagli su come diagnosticare vari scenari di guasto.

Passaggi successivi

Per altri esempi di codice, vedere i collegamenti seguenti:

Contribuire

Se desideri contribuire a questa libreria, leggi la guida contributi per saperne di più su come costruire e testare il codice.

  • Last updated on