Condividi tramite

Libreria client segreta di Azure Key Vault per JavaScript - versione 4.10.0

Azure Key Vault è un servizio che consente di crittografare chiavi di autenticazione, chiavi dell'account di archiviazione, chiavi di crittografia dei dati, file pfx e password usando chiavi protette. Per altre informazioni su Azure Key Vault, è consigliabile esaminare: Che cos'è Azure Key Vault?

La gestione dei segreti di Azure Key Vault consente di archiviare e controllare in modo sicuro l'accesso a token, password, certificati, chiavi API e altri segreti.

Usare la libreria client per i segreti di Azure Key Vault nell'applicazione Node.js 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 usato nel browser a causa delle limitazioni del servizio Azure Key Vault. Per indicazioni, vedere questo documento.

Collegamenti chiave:

Come iniziare

Ambienti attualmente supportati

Prerequisiti

Installare il pacchetto

Installare la libreria client dei segreti di Azure Key Vault usando npm:

npm install @azure/keyvault-secrets

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.

Concetti chiave

  • Il client Segreto è l'interfaccia principale per interagire con i metodi API correlati ai segreti 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 segreti.
  • Una versione segreto è una versione di un segreto nell'insieme di credenziali delle chiavi. 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. Ciò si verifica solo se l'insieme di credenziali delle chiavi ha abilitata per l'eliminazione temporanea.
  • 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 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 SecretClient, 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 SecretClient. Dopo l'importazione, è possibile connettersi 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 keys client and connect to the service
const client = new SecretClient(url, credential);

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:

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 illustrano alcune delle attività comuni che usano i segreti di Azure Key Vault. Gli scenari illustrati di seguito sono costituiti da:

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 di eliminazione temporanea è abilitata per l'insieme di credenziali delle chiavi, questa operazione etichetta solo il segreto come segreto eliminato. 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

Usando SecretClient, è possibile recuperare e scorrere tutti i segreti in un insieme di credenziali delle chiavi, nonché tramite tutti i segreti eliminati 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

Per informazioni dettagliate su come diagnosticare vari scenari di errore, vedere la guida alla 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");

Passaggi successivi

Per altri esempi di codice, vedere i collegamenti seguenti:

Contribuire

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