Avvio rapido: Libreria client di chiavi di Azure Key Vault per JavaScript

Articolo
10/05/2024

Introduzione alla libreria client di chiavi di Azure Key Vault per JavaScript. Azure Key Vault è un servizio cloud che offre un archivio sicuro per le chiavi crittografiche. È possibile archiviare in modo sicuro chiavi, password, certificati e altri segreti. È possibile creare e gestire istanze di Azure Key Vault tramite il portale di Azure. Questa guida di avvio rapido descrive come creare, recuperare ed eliminare chiavi da Azure Key Vault usando la libreria client di chiavi per JavaScript.

Risorse per la libreria client di Key Vault:

Documentazione di riferimento sull'API | Codice sorgente della libreria | Pacchetto (npm)

Per altre informazioni su Key Vault e sulle chiavi, vedere:

Prerequisiti

Una sottoscrizione di Azure: creare un account gratuitamente.
Versione corrente di Node.js LTS.
Interfaccia della riga di comando di Azure
Insieme di credenziali delle chiavi esistente. È possibile crearne uno usando:

Una sottoscrizione di Azure: creare un account gratuitamente.
Versione corrente di Node.js LTS.
TypeScript 5+
Interfaccia della riga di comando di Azure.
Insieme di credenziali delle chiavi esistente. È possibile crearne uno usando:

Questa guida di avvio rapido presuppone che si usi l'interfaccia della riga di comando di Azure.

Eseguire il comando login.
```
az login
```
Se l'interfaccia della riga di comando può aprire il browser predefinito, eseguirà questa operazione e caricherà una pagina di accesso di Azure.

In caso contrario, aprire una pagina del browser all'indirizzo https://aka.ms/devicelogin e immettere il codice di autorizzazione visualizzato nel terminale.
Accedere con le credenziali dell'account nel browser.

Creare una nuova applicazione Node.js

Creare un'applicazione Node.js che usa l'insieme di credenziali delle chiavi.

In un terminale creare una cartella denominata key-vault-node-app e passare a tale cartella:
```
mkdir key-vault-node-app && cd key-vault-node-app
```
Inizializzare il progetto Node.js:
```
npm init -y
```

Installare i pacchetti di Key Vault

Usando il terminale, installare la libreria client dei segreti di Azure Key Vault, @azure/keyvault-keys, per Node.js.
```
npm install @azure/keyvault-keys
```
Installare il pacchetto @azure/identity della libreria client di identità di Azure per eseguire l'autenticazione in un'istanza di Key Vault.
```
npm install @azure/identity
```

Concedere l'accesso all'insieme di credenziali delle chiavi

Per ottenere le autorizzazioni per l’insieme di credenziali delle chiavi tramite il controllo degli accessi in base al ruolo (RBAC), assegnare un ruolo all’UPN (User Principal Name) usando il comando dell’interfaccia della riga di comando di Azure az role assignment create.

az role assignment create --role "Key Vault Crypto Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Sostituire <upn>, <subscription-id>, <resource-group-name> e <your-unique-keyvault-name> con i valori effettivi. L'UPN in genere sarà nel formato di un indirizzo e-mail (ad esempio, username@domain.com).

Impostare le variabili di ambiente

Questa applicazione usa l'endpoint dell'insieme di credenziali delle chiavi come variabile di ambiente denominata KEY_VAULT_URL.

set KEY_VAULT_URL=<your-key-vault-endpoint>

Windows PowerShell

$Env:KEY_VAULT_URL="<your-key-vault-endpoint>"

export KEY_VAULT_URL=<your-key-vault-endpoint>

Autenticare e creare un client

Le richieste dell'applicazione per la maggior parte dei servizi di Azure devono essere autorizzate. L'uso del metodo DefaultAzureCredential fornito dalla libreria client di Identità di Azure è l'approccio consigliato per l'implementazione di connessioni senza password ai servizi di Azure nel codice. DefaultAzureCredential supporta più metodi di autenticazione e determina il metodo da usare in fase di esecuzione. Questo approccio consente all'app di usare metodi di autenticazione diversi in ambienti diversi (locale e di produzione) senza implementare codice specifico dell'ambiente.

In questo avvio rapido, DefaultAzureCredential esegue l'autenticazione nell’insieme di credenziali delle chiavi usando le credenziali dell'utente di sviluppo locale connesso all'interfaccia della riga di comando di Azure. Quando l'applicazione viene distribuita in Azure, lo stesso codice DefaultAzureCredential può individuare e usare automaticamente un'identità gestita assegnata a un servizio app, a una macchina virtuale o ad altri servizi. Per altre informazioni, vedere Panoramica delle identità gestite.

In questo codice, l'endpoint dell'insieme di credenziali delle chiavi viene usato per creare il client. Il formato dell'endpoint è simile a https://<your-key-vault-name>.vault.azure.net, ma può cambiare per i cloud sovrani. Per altre informazioni sull'autenticazione nell'insieme di credenziali delle chiavi, vedere la Guida per sviluppatori.

Esempio di codice

Gli esempi di codice riportati di seguito illustrano come creare un client e come impostare, recuperare ed eliminare un segreto.

Questo codice usa le classi e i metodi per i segreti di Key Vault seguenti:

Configurare il framework dell'app

Creare un nuovo file di testo e incollare il codice seguente nel file index.js.

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

async function main() {

    // DefaultAzureCredential expects the following three environment variables:
    // - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
    // - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
    // - AZURE_CLIENT_SECRET: The client secret for the registered application
    const credential = new DefaultAzureCredential();

    const keyVaultUrl = process.env["KEY_VAULT_URL"];
    if(!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

    const client = new KeyClient(keyVaultUrl, credential);

    const uniqueString = Date.now();
    const keyName = `sample-key-${uniqueString}`;
    const ecKeyName = `sample-ec-key-${uniqueString}`;
    const rsaKeyName = `sample-rsa-key-${uniqueString}`;

    // Create key using the general method
    const result = await client.createKey(keyName, "EC");
    console.log("key: ", result);

    // Create key using specialized key creation methods
    const ecResult = await client.createEcKey(ecKeyName, { curve: "P-256" });
    const rsaResult = await client.createRsaKey(rsaKeyName, { keySize: 2048 });
    console.log("Elliptic curve key: ", ecResult);
    console.log("RSA Key: ", rsaResult);

    // Get a specific key
    const key = await client.getKey(keyName);
    console.log("key: ", key);

    // Or list the keys we have
    for await (const keyProperties of client.listPropertiesOfKeys()) {
    const key = await client.getKey(keyProperties.name);
    console.log("key: ", key);
    }

    // Update the key
    const updatedKey = await client.updateKeyProperties(keyName, result.properties.version, {
    enabled: false
    });
    console.log("updated key: ", updatedKey);

    // Delete the key - the key is soft-deleted but not yet purged
    const deletePoller = await client.beginDeleteKey(keyName);
    await deletePoller.pollUntilDone();

    const deletedKey = await client.getDeletedKey(keyName);
    console.log("deleted key: ", deletedKey);

    // Purge the key - the key is permanently deleted
    // This operation could take some time to complete
    console.time("purge a single key");
    await client.purgeDeletedKey(keyName);
    console.timeEnd("purge a single key");
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Eseguire l'applicazione di esempio

Eseguire l'app:
```
node index.js
```

I metodi create e get restituiscono un oggetto JSON completo per la chiave:

"key":  {
  "key": {
    "kid": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
    "kty": "YOUR-KEY-TYPE",
    "keyOps": [ ARRAY-OF-VALID-OPERATIONS ],
    ... other properties based on key type
  },
  "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
  "name": "YOUR-KEY-NAME",
  "keyOperations": [ ARRAY-OF-VALID-OPERATIONS ],
  "keyType": "YOUR-KEY-TYPE",
  "properties": {
    "tags": undefined,
    "enabled": true,
    "notBefore": undefined,
    "expiresOn": undefined,
    "createdOn": 2021-11-29T18:29:11.000Z,
    "updatedOn": 2021-11-29T18:29:11.000Z,
    "recoverableDays": 90,
    "recoveryLevel": "Recoverable+Purgeable",
    "exportable": undefined,
    "releasePolicy": undefined,
    "vaultUrl": "https://YOUR-KEY-VAULT-ENDPOINT",
    "version": "YOUR-KEY-VERSION",
    "name": "YOUR-KEY-VAULT-NAME",
    "managed": undefined,
    "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION"
  }
}

Creare un nuovo file di testo e incollare il codice seguente nel file index.ts.

import {
  KeyClient,
  KeyVaultKey,
  KeyProperties,
  DeletedKey,
} from "@azure/keyvault-keys";
import { DefaultAzureCredential } from "@azure/identity";
import "dotenv/config";

const credential = new DefaultAzureCredential();

// Get Key Vault name from environment variables
// such as `https://${keyVaultName}.vault.azure.net`
const keyVaultUrl = process.env.KEY_VAULT_URL;
if (!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

function printKey(keyVaultKey: KeyVaultKey): void {
  const { name, key, id, keyType, keyOperations, properties } = keyVaultKey;
  console.log("Key: ", { name, key, id, keyType });

  const { vaultUrl, version, enabled, expiresOn }: KeyProperties = properties;
  console.log("Key Properties: ", { vaultUrl, version, enabled, expiresOn });

  console.log("Key Operations: ", keyOperations.join(", "));
}

async function main(): Promise<void> {
  // Create a new KeyClient
  const client = new KeyClient(keyVaultUrl, credential);

  // Create unique key names
  const uniqueString = Date.now().toString();
  const keyName = `sample-key-${uniqueString}`;
  const ecKeyName = `sample-ec-key-${uniqueString}`;
  const rsaKeyName = `sample-rsa-key-${uniqueString}`;

  // Create a EC key
  const ecKey = await client.createKey(keyName, "EC");
  printKey(ecKey);

  // Elliptic curve key
  const ec256Key = await client.createEcKey(ecKeyName, {
    curve: "P-256",
  });
  printKey(ec256Key);

  // RSA key
  const rsa2048Key = await client.createRsaKey(rsaKeyName, {
    keySize: 2048,
  });
  printKey(rsa2048Key);

  // Get a key
  const key = await client.getKey(keyName);
  printKey(key);

  // Get properties of all keys
  for await (const keyProperties of client.listPropertiesOfKeys()) {
    const iteratedKey = await client.getKey(keyProperties.name);
    printKey(iteratedKey);
  }

  // Update key properties - disable key
  const updatedKey = await client.updateKeyProperties(
    keyName,
    ecKey.properties.version,
    {
      enabled: false,
    }
  );
  printKey(updatedKey);

  // Delete key (without immediate purge)
  const deletePoller = await client.beginDeleteKey(keyName);
  await deletePoller.pollUntilDone();

  // Get a deleted key
  const deletedKey = await client.getDeletedKey(keyName);
  console.log("deleted key: ", deletedKey.name);

  // Purge a deleted key
  console.time("purge a single key");
  await client.purgeDeletedKey(keyName);
  console.timeEnd("purge a single key");
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Eseguire l'applicazione di esempio

Compilare l'app TypeScript:
```
tsc
```
Eseguire l'app:
```
node index.js
```

I metodi create e get restituiscono un oggetto JSON completo per la chiave:

"key":  {
  "key": {
    "kid": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
    "kty": "YOUR-KEY-TYPE",
    "keyOps": [ ARRAY-OF-VALID-OPERATIONS ],
    ... other properties based on key type
  },
  "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
  "name": "YOUR-KEY-NAME",
  "keyOperations": [ ARRAY-OF-VALID-OPERATIONS ],
  "keyType": "YOUR-KEY-TYPE",
  "properties": {
    "tags": undefined,
    "enabled": true,
    "notBefore": undefined,
    "expiresOn": undefined,
    "createdOn": 2021-11-29T18:29:11.000Z,
    "updatedOn": 2021-11-29T18:29:11.000Z,
    "recoverableDays": 90,
    "recoveryLevel": "Recoverable+Purgeable",
    "exportable": undefined,
    "releasePolicy": undefined,
    "vaultUrl": "https://YOUR-KEY-VAULT-ENDPOINT",
    "version": "YOUR-KEY-VERSION",
    "name": "YOUR-KEY-VAULT-NAME",
    "managed": undefined,
    "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION"
  }
}

Integrazione con Configurazione app

Azure SDK fornisce un metodo helper, parseKeyVaultKeyIdentifier, per analizzare l'ID chiave di Key Vault specificato. Questo è necessario se si usano riferimenti di Configurazione app a Key Vault. Configurazione app archivia l'ID chiave di Key Vault. È necessario il metodo parseKeyVaultKeyIdentifier per analizzare tale ID per ottenere il nome della chiave. Dopo aver ottenuto il nome della chiave, è possibile ottenere il valore della chiave corrente usando il codice di questo avvio rapido.

Passaggi successivi

In questo argomento di avvio rapido è stato creato un insieme di credenziali delle chiavi e quindi è stata archiviata e recuperata una chiave. Per altre informazioni sul servizio Key Vault e su come integrarlo nelle applicazioni, continuare con questi articoli.

Leggere una panoramica di Azure Key Vault
Leggere una panoramica delle chiavi di Azure Key Vault
Come Proteggere l'accesso a un insieme di credenziali delle chiavi
Vedere la Guida per gli sviluppatori per Azure Key Vault
Vedere Panoramica della sicurezza di Key Vault

Condividi tramite

Avvio rapido: Libreria client di chiavi di Azure Key Vault per JavaScript

Prerequisiti

Creare una nuova applicazione Node.js

Installare i pacchetti di Key Vault

Concedere l'accesso all'insieme di credenziali delle chiavi

Impostare le variabili di ambiente

Autenticare e creare un client

Esempio di codice

Configurare il framework dell'app

Eseguire l'applicazione di esempio

Eseguire l'applicazione di esempio

Integrazione con Configurazione app

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Avvio rapido: Libreria client di chiavi di Azure Key Vault per JavaScript

Prerequisiti

Accedere ad Azure

Creare una nuova applicazione Node.js

Installare i pacchetti di Key Vault

Concedere l'accesso all'insieme di credenziali delle chiavi

Impostare le variabili di ambiente

Autenticare e creare un client

Esempio di codice

Configurare il framework dell'app

Eseguire l'applicazione di esempio

Eseguire l'applicazione di esempio

Integrazione con Configurazione app

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive