Azure Key Vault Secret client library for JavaScript - versione 4.11.1

Azure Key Vault è un servizio che permette di criptare chiavi di autenticazione, chiavi di account di archiviazione, chiavi di crittografia dati, file .pfx e password utilizzando chiavi protette. Se vuoi saperne di più su Azure Key Vault, potresti voler rivedere: Cos'è Azure Key Vault?

La gestione di Azure Key Vault Secrets ti permette di memorizzare e controllare in modo sicuro l'accesso a token, password, certificati, API key e altri segreti.

Usa la libreria client per Azure Key Vault Segreti nella tua Node.js applicazione per:

Ottenere, impostare ed eliminare segreti.
Aggiornare un segreto e gli attributi.
Eseguire il backup e il ripristino di un segreto.
Ottenere, eliminare o recuperare un segreto eliminato.
Ottenere tutte le versioni di un segreto.
Ottenere tutti i segreti.
Ottenere tutti i segreti 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:

Come iniziare

Ambienti attualmente supportati

Versioni LTS di Node.js

Prerequisiti

Un abbonamento Azure
Una risorsa Key Vault
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, puoi usare il interfaccia della riga di comando di Azure seguendo i passaggi in questo documento.

Installare il pacchetto

Installa la libreria client Azure Key Vault Secret usando npm:

npm install @azure/keyvault-secrets

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.

Concetti chiave

Il client Secret è l'interfaccia principale per interagire con i metodi API relativi ai segreti 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 segreti.
Una versione Segreta è una versione di un segreto nel Key Vault. Ogni volta che un utente assegna un valore a un nome segreto univoco, viene creata una nuova versione del segreto. Il recupero di un segreto 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 segreti eliminati non vengono persi immediatamente. Questo accade solo se il Key Vault ha attivato soft-delete.
Un backup segreto può essere generato da qualsiasi segreto creato. Questi backup vengono usati come dati binari e possono essere usati solo per rigenerare un segreto eliminato in precedenza.

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 SecretClient, 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 SecretClient. Una volta importati, possiamo connetterci al servizio Key Vault:

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

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 secrets client and connect to the service
const client = new SecretClient(url, credential);

Per gli ambienti del browser, usare il InteractiveBrowserCredential dal pacchetto di @azure/identity per l'autenticazione.

import { InteractiveBrowserCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new SecretClient(url, credential);

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 { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
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 SecretClient(url, credential, {
  serviceVersion: "7.0", // Or 7.1
});

Esempi

Le sezioni seguenti forniscono frammenti di codice che coprono alcuni dei compiti comuni che utilizzano Azure Key Vault Secrets. Gli scenari illustrati di seguito sono costituiti da:

Creazione e impostazione di un segreto.
Ottenere un segreto.
Creazione e aggiornamento di segreti con attributi.
Eliminazione di un segreto.
L'iterazione di elenchi di segreti.

Creazione e impostazione di un segreto

setSecret assegna un valore fornito al nome del segreto specificato. Se esiste già un segreto con lo stesso nome, viene creata una nuova versione del segreto.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const result = await client.setSecret(secretName, "MySecretValue");
console.log("result: ", result);

Ottenere un segreto

Il modo più semplice per leggere i segreti dall'insieme di credenziali consiste nel ottenere un segreto in base al nome. Verrà recuperata la versione più recente del segreto. Facoltativamente, è possibile ottenere una versione diversa della chiave se si specifica come parte dei parametri facoltativi.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const latestSecret = await client.getSecret(secretName);
console.log(`Latest version of the secret ${secretName}: `, latestSecret);

const specificSecret = await client.getSecret(secretName, {
  version: latestSecret.properties.version!,
});
console.log(
  `The secret ${secretName} at the version ${latestSecret.properties.version!}: `,
  specificSecret,
);

Creazione e aggiornamento di segreti con attributi

Un segreto può avere più informazioni rispetto al nome e al relativo valore. Possono includere anche gli attributi seguenti:

tags: qualsiasi set di valori chiave che può essere usato per cercare e filtrare i segreti.
contentType: qualsiasi stringa che può essere usata per aiutare il ricevitore del segreto a comprendere come usare il valore del segreto.
enabled: valore booleano che determina se il valore del segreto può essere letto o meno.
notBefore: data specificata dopo la quale è possibile recuperare il valore del segreto.
expiresOn: data specificata dopo la quale non è possibile recuperare il valore del segreto.

Un oggetto con questi attributi può essere inviato come terzo parametro di setSecret, subito dopo il nome e il valore del segreto, come indicato di seguito:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const result = await client.setSecret(secretName, "MySecretValue", {
  enabled: false,
});

Verrà creata una nuova versione dello stesso segreto, che avrà gli attributi forniti più recenti.

Gli attributi possono anche essere aggiornati a una versione privata esistente con updateSecretProperties, come indicato di seguito:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const result = await client.getSecret(secretName);
await client.updateSecretProperties(secretName, result.properties.version, { enabled: false });

Eliminazione di un segreto

Il metodo beginDeleteSecret avvia l'eliminazione di un segreto. Questo processo verrà eseguito in background non appena sono disponibili le risorse necessarie.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

await client.beginDeleteSecret(secretName);

Se soft-delete è abilitato per il Key Vault, questa operazione etichetta il segreto solo come segreto deleted. Non è possibile aggiornare un segreto eliminato. Possono essere letti, recuperati o eliminati solo.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const poller = await client.beginDeleteSecret(secretName);

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

// The secret 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 secret this way:
await client.getDeletedSecret(secretName);

// Deleted secrets can also be recovered or purged.

// recoverDeletedSecret returns a poller, just like beginDeleteSecret.
const recoverPoller = await client.beginRecoverDeletedSecret(secretName);
await recoverPoller.pollUntilDone();

// And then, to purge the deleted secret:
await client.purgeDeletedSecret(secretName);

Poiché i segreti richiedono del tempo per essere eliminati completamente, beginDeleteSecret restituisce un oggetto Poller che tiene traccia dell'operazione a esecuzione prolungata sottostante in base alle linee guida seguenti: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Il poller ricevuto consente di ottenere il segreto eliminato chiamando a poller.getResult(). È anche possibile attendere il completamento dell'eliminazione, eseguendo singole chiamate al servizio fino all'eliminazione del segreto o attendendo il completamento del processo:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const poller = await client.beginDeleteSecret(secretName);

// You can use the deleted secret immediately:
let deletedSecret = poller.getResult();

// Or you can wait until the secret finishes being deleted:
deletedSecret = await poller.pollUntilDone();
console.log(deletedSecret);

Un altro modo per attendere che il segreto venga eliminato completamente consiste nell'eseguire singole chiamate, come indicato di seguito:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

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

const poller = await client.beginDeleteSecret(secretName);
while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

console.log(`The secret ${secretName} is fully deleted`);

Iterazione di elenchi di segreti

Utilizzando il SecretClient, puoi recuperare e iterare attraverso tutti i segreti di un Key Vault, così come tutti i segreti cancellati e le versioni di un segreto specifico. Sono disponibili i metodi API seguenti:

listPropertiesOfSecrets elenca tutti i segreti non eliminati in base ai nomi, solo nelle versioni più recenti.
listDeletedSecrets elenca tutti i segreti eliminati in base ai nomi, solo nelle versioni più recenti.
listPropertiesOfSecretVersions elenca tutte le versioni di un segreto in base a un nome segreto.

Che può essere usato come segue:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

for await (const secretProperties of client.listPropertiesOfSecrets()) {
  console.log("Secret properties: ", secretProperties);
}

for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("Deleted secret: ", deletedSecret);
}

for await (const versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
  console.log("Version properties: ", versionProperties);
}

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 { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

for await (const page of client.listPropertiesOfSecrets().byPage()) {
  for (const secretProperties of page) {
    console.log("Secret properties: ", secretProperties);
  }
}
for await (const page of client.listDeletedSecrets().byPage()) {
  for (const deletedSecret of page) {
    console.log("Deleted secret: ", deletedSecret);
  }
}
for await (const page of client.listPropertiesOfSecretVersions(secretName).byPage()) {
  for (const versionProperties of page) {
    console.log("Version properties: ", versionProperties);
  }
}

Risoluzione dei problemi

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

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

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.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-04-09