Libreria client di amministrazione di Azure Key Vault per JavaScript - versione 4.5.0

  • Articolo

Il modulo di protezione hardware gestito di Azure Key Vault è un servizio cloud completamente gestito, a disponibilità elevata, a tenant singolo e conforme agli standard che consente di proteggere le chiavi crittografiche per le applicazioni cloud usando moduli di protezione hardware convalidati FIPS 140-2 livello 3. Per altre informazioni su HSM gestito di Azure Key Vault, è possibile esaminare: Che cos'è il modulo di protezione hardware gestito di Azure Key Vault?

Il pacchetto @azure/keyvault-admin fornisce il supporto per attività amministrative Key Vault, ad esempio backup completo/ripristino e controllo degli accessi in base al ruolo a livello di chiave.

Nota: la libreria di amministrazione funziona solo con Il modulo di protezione hardware gestito di Azure Key Vault: le funzioni destinate a un Key Vault avranno esito negativo.

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

Installare il pacchetto

Installare la libreria client di amministrazione di Azure Key Vault per JavaScript e TypeScript con NPM:

npm install @azure/keyvault-admin

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 .

Ambienti attualmente supportati

Prerequisiti

Autenticare il client

Per interagire con il servizio Azure Key Vault, è necessario creare un'istanza della classe o della KeyVaultAccessControlClientKeyVaultBackupClient classe , nonché un URL dell'insieme di credenziali (che può essere visualizzato come "Nome DNS" nel portale di Azure) 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.

Creare KeyVaultAccessControlClient

Dopo aver eseguito l'autenticazione con il metodo di autenticazione più adatto alle proprie esigenze, è possibile creare un oggetto KeyVaultAccessControlClient come indicato di seguito, sostituendo l'URL del modulo di protezione hardware gestito nel costruttore:

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

const credentials = new DefaultAzureCredential();

const client = new KeyVaultAccessControlClient(`<your Managed HSM URL>`, credentials);

Creare KeyVaultBackupClient

Dopo aver eseguito l'autenticazione con il metodo di autenticazione più adatto alle proprie esigenze, è possibile creare un oggetto KeyVaultBackupClient come indicato di seguito, sostituendo l'URL del modulo di protezione hardware gestito nel costruttore:

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

const credentials = new DefaultAzureCredential();

const client = new KeyVaultBackupClient(`<your Managed HSM URL>`, credentials);

Concetti chiave

KeyVaultRoleDefinition

Una definizione di ruolo è una raccolta di autorizzazioni. Una definizione di ruolo definisce le operazioni che è possibile eseguire, ad esempio lettura, scrittura ed eliminazione. Può anche definire le operazioni escluse dalle operazioni consentite.

Le definizioni di ruolo possono essere elencate e specificate come parte di un oggetto KeyVaultRoleAssignment.

KeyVaultRoleAssignment

Un'assegnazione di ruolo è l'associazione di una definizione di ruolo a un'entità servizio. Possono essere creati, elencati, recuperati singolarmente ed eliminati.

KeyVaultAccessControlClient

Fornisce KeyVaultAccessControlClient operazioni che consentono la gestione delle definizioni dei ruoli (istanze di KeyVaultRoleDefinition) e delle assegnazioni di ruolo (istanze di KeyVaultRoleAssignment).

KeyVaultBackupClient

Fornisce KeyVaultBackupClient operazioni per l'esecuzione di backup completi delle chiavi, ripristini di chiavi complete e ripristini selettivi delle chiavi.

Operazioni a esecuzione prolungata

Le operazioni eseguite da KeyVaultBackupClient possono richiedere il tempo necessario per le risorse di Azure, richiedendo a un livello client di tenere traccia, serializzare e riprendere le operazioni nel ciclo di vita dei programmi che attendono il completamento. Questa operazione viene eseguita tramite un'astrazione comune tramite il pacchetto @azure/core-lro.

Offre KeyVaultBackupClient tre metodi che eseguono operazioni a esecuzione prolungata:

  • beginBackup, avvia la generazione di un backup di un modulo di protezione hardware gestito di Azure Key Vault nell'account BLOB di archiviazione specificato.
  • beginRestore, avvia il ripristino di tutti i materiali chiave usando il token di firma di accesso condiviso che punta a una cartella di backup dell'archiviazione BLOB di Azure archiviata in precedenza.
  • beginSelectiveRestore, avvia il ripristino di tutte le versioni chiave di una determinata chiave usando il token di firma di accesso condiviso fornito dall'utente che punta a una cartella di backup dell'archiviazione BLOB di Azure archiviata in precedenza.

I metodi che iniziano operazioni a esecuzione prolungata restituiscono un poller che consente di attendere a tempo indeterminato fino al completamento dell'operazione. Altre informazioni sono disponibili negli esempi seguenti.

Esempio

Sono disponibili esempi sia in JavaScript che in TypeScript che mostrano le funzionalità di controllo di accesso e backup/ripristino in questo pacchetto. Seguire i leggimi corrispondenti per i passaggi dettagliati per eseguire gli esempi.

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:

const { setLogLevel } = require("@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