Libreria client di Azure Key Vault segreto per JavaScript - versione 4.8.0

  • Articolo

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 sull'Key Vault di Azure, è possibile esaminare: Che cos'è Azure Key Vault?

La gestione dei segreti di Azure Key Vault consente di archiviare e controllare in modo sicuro l'accesso ai token, alle password, ai certificati, alle chiavi API e ad 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 ed è 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 di Azure Key Vault, vedere questo documento per indicazioni.

Collegamenti principali:

Introduzione

Ambienti attualmente supportati

Prerequisiti

Installare il pacchetto

Installare la libreria client di Azure Key Vault segreto usando npm:

npm install @azure/keyvault-secrets

Installare la libreria di identità

Key Vault client autenticarsi usando Azure Identity Library. Installarlo anche usando npm

npm install @azure/identity

Configurare TypeScript

Gli utenti TypeScript devono avere installate definizioni di tipo Node:

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 .

Concetti chiave

  • Il client Segreto è l'interfaccia primaria per interagire con i metodi API correlati ai segreti nell'API di Key Vault di Azure da un'applicazione JavaScript. Dopo l'inizializzazione, fornisce un set di metodi di base che possono essere usati per creare, leggere, aggiornare ed eliminare segreti.
  • Una versione segreto è una versione di un segreto nella 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.
  • L'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 immediatamente persi. Ciò accade solo se il Key Vault ha abilitato 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 relative 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 e esempi per iniziare.

Per interagire con il servizio azure Key Vault, è necessario creare un'istanza della classe, un URL dell'insieme SecretClient di credenziali e un oggetto credenziale. Gli esempi illustrati in questo documento usano un oggetto credenziale denominato DefaultAzureCredential, che è appropriato per la maggior parte degli scenari, tra cui lo sviluppo locale e gli ambienti di produzione. È inoltre consigliabile usare un'identità gestita per l'autenticazione negli ambienti di produzione.

È possibile trovare altre informazioni su diversi modi di autenticazione e sui relativi tipi di credenziali corrispondenti nella documentazione di Identità di Azure.

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

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

Dopo aver importato questi elementi, è possibile connettersi successivamente al servizio Key Vault:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@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);

Specifica della versione dell'API del servizio Key Vault di Azure

Per impostazione predefinita, questo pacchetto usa la versione più recente del servizio di Azure Key Vault che è 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 { SecretClient } = require("@azure/keyvault-secrets");

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 SecretClient(url, credential, {
  serviceVersion: "7.0",
});

Esempio

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

Creazione e impostazione di un segreto

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

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@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";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue");
  console.log("result: ", result);
}

main();

Ottenere un segreto

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

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@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";

async function main() {
  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);
}

main();

Creazione e aggiornamento di segreti con attributi

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

  • tags: qualsiasi set di valori chiave che possono essere usati 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 segreto.
  • enabled: valore booleano che determina se il valore segreto può essere letto o meno.
  • notBefore: data specificata dopo la quale è possibile recuperare il valore segreto.
  • expiresOn: data specificata dopo la quale non è possibile recuperare il valore 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:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@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";

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

main();

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

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

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@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";

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

main();

Eliminazione di un segreto

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

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@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";

async function main() {
  await client.beginDeleteSecret(secretName);
}

main();

Se l'eliminazione temporanea è abilitata per il Key Vault, questa operazione etichetta solo il segreto come segreto eliminato. Non è possibile aggiornare un segreto eliminato. Possono essere letti, recuperati o eliminati.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@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";

async function main() {
  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);
}

main();

Poiché i segreti richiedono tempo per l'eliminazione completa, beginDeleteSecret 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 consente di ottenere il segreto eliminato chiamando a poller.getResult(). È anche possibile attendere il completamento dell'eliminazione, eseguendo singole chiamate di servizio fino all'eliminazione del segreto o aspettando fino al termine del processo:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@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";

async function main() {
  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);
}

main();

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

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");
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 SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

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

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

main();

Iterazione di elenchi di segreti

Usando SecretClient, è possibile recuperare e scorrere tutti i segreti in un Key Vault, 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 verranno elencate tutte le versioni di un segreto in base a un nome segreto.

Che può essere usato come segue:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@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";

async function main() {
  for await (let secretProperties of client.listPropertiesOfSecrets()) {
    console.log("Secret properties: ", secretProperties);
  }
  for await (let deletedSecret of client.listDeletedSecrets()) {
    console.log("Deleted secret: ", deletedSecret);
  }
  for await (let versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
    console.log("Version properties: ", versionProperties);
  }
}

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 { SecretClient } = require("@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";

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

main();

Risoluzione dei problemi

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

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