Avvio rapido: Libreria client dei segreti di Azure Key Vault per JavaScript

  • Articolo

Introduzione alla libreria client dei segreti di Azure Key Vault per JavaScript. Azure Key Vault è un servizio cloud che offre un archivio sicuro per i segreti. È 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. Questo avvio rapido descrive come creare, recuperare ed eliminare segreti da Azure Key Vault usando la libreria client 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 sui segreti, vedere:

Prerequisiti

Prerequisiti

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

Accedere ad Azure

  1. 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.

  2. Accedere con le credenziali dell'account nel browser.

Creare un gruppo di risorse e un insieme di credenziali delle chiavi

  1. Usare il comando az group create per creare un gruppo di risorse:

    az group create --name myResourceGroup --location eastus

    È possibile sostituire "eastus" con una località più vicina, se si preferisce.

  2. Usare az keyvault create per creare l'insieme di credenziali delle chiavi:

    az keyvault create --name <your-unique-keyvault-name> --resource-group myResourceGroup

    Sostituire <your-unique-keyvault-name> con un nome univoco in tutto Azure. In genere si usa il nome personale o dell'azienda insieme ad altri numeri e identificatori.

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 Secrets 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).

Creare una nuova applicazione Node.js

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

  1. 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

  2. Inizializzare il progetto Node.js:

    npm init -y

Installare i pacchetti di Key Vault

  1. Usando il terminale, installare la libreria client dei segreti di Azure Key Vault, @azure/keyvault-secrets, per Node.js.

    npm install @azure/keyvault-secrets

  2. 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 Secrets 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>

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

async function main() {
  // If you're using MSI, DefaultAzureCredential should "just work".
  // Otherwise, 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 SecretClient(keyVaultUrl, credential);

  // Create a secret
  // The secret can be a string of any kind. For example,
  // a multiline text block such as an RSA private key with newline characters,
  // or a stringified JSON object, like `JSON.stringify({ mySecret: 'MySecretValue'})`.
  const uniqueString = new Date().getTime();
  const secretName = `secret${uniqueString}`;
  const result = await client.setSecret(secretName, "MySecretValue");
  console.log("result: ", result);

  // Read the secret we created
  const secret = await client.getSecret(secretName);
  console.log("secret: ", secret);

  // Update the secret with different attributes
  const updatedSecret = await client.updateSecretProperties(secretName, result.properties.version, {
    enabled: false
  });
  console.log("updated secret: ", updatedSecret);

  // Delete the secret immediately without ability to restore or purge.
  await client.beginDeleteSecret(secretName);
}

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

Eseguire l'applicazione di esempio

  1. Eseguire l'app:

    node index.js

  2. I metodi create e get restituiscono un oggetto JSON completo per il segreto:

    {
    "value": "MySecretValue",
    "name": "secret1637692472606",
    "properties": {
        "createdOn": "2021-11-23T18:34:33.000Z",
        "updatedOn": "2021-11-23T18:34:33.000Z",
        "enabled": true,
        "recoverableDays": 90,
        "recoveryLevel": "Recoverable+Purgeable",
        "id": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.net/secrets/secret1637692472606/YOUR-VERSION",
        "vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.net",
        "version": "YOUR-VERSION",
        "name": "secret1637692472606"
    }
}

    Il metodo update restituisce le coppie nome/valore delle proprietà:

    "createdOn": "2021-11-23T18:34:33.000Z",
"updatedOn": "2021-11-23T18:34:33.000Z",
"enabled": true,
"recoverableDays": 90,
"recoveryLevel": "Recoverable+Purgeable",
"id": "https: //YOUR-KEYVAULT-ENDPOINT/secrets/secret1637692472606/YOUR-VERSION",
"vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT",
"version": "YOUR-VERSION",
"name": "secret1637692472606"

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

    import {
  SecretClient,
  KeyVaultSecret,
  SecretProperties,
} from "@azure/keyvault-secrets";
import { DefaultAzureCredential } from "@azure/identity";
import "dotenv/config";

// Passwordless credential
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 printSecret(secret: KeyVaultSecret): void {
  const { name, value, properties } = secret;
  const { enabled, expiresOn, createdOn } = properties;
  console.log("Secret: ", { name, value, enabled, expiresOn, createdOn });
}
function printSecretProperties(secret: SecretProperties): void {
  const { name, enabled, expiresOn, createdOn } = secret;
  console.log("Secret: ", { name, enabled, expiresOn, createdOn });
}

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

  // Create a unique secret name
  const uniqueString = new Date().getTime().toString();
  const secretName = `secret${uniqueString}`;

  // Create a secret
  const createSecretResult = await client.setSecret(
    secretName,
    "MySecretValue"
  );
  printSecret(createSecretResult);

  // Get the secret by name
  const getSecretResult = await client.getSecret(secretName);
  printSecret(getSecretResult);

  // Update properties
  const updatedSecret = await client.updateSecretProperties(
    secretName,
    getSecretResult.properties.version,
    {
      enabled: false,
    }
  );
  printSecretProperties(updatedSecret);

  // Delete secret (without immediate purge)
  const deletePoller = await client.beginDeleteSecret(secretName);
  await deletePoller.pollUntilDone();
}

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

Eseguire l'applicazione di esempio

  1. Compilare l'app TypeScript:

    tsc

  2. Eseguire l'app:

    node index.js

  3. I metodi create e get restituiscono un oggetto JSON completo per il segreto:

    {
    "value": "MySecretValue",
    "name": "secret1637692472606",
    "properties": {
        "createdOn": "2021-11-23T18:34:33.000Z",
        "updatedOn": "2021-11-23T18:34:33.000Z",
        "enabled": true,
        "recoverableDays": 90,
        "recoveryLevel": "Recoverable+Purgeable",
        "id": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.net/secrets/secret1637692472606/YOUR-VERSION",
        "vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.net",
        "version": "YOUR-VERSION",
        "name": "secret1637692472606"
    }
}

    Il metodo update restituisce le coppie nome/valore delle proprietà:

    "createdOn": "2021-11-23T18:34:33.000Z",
"updatedOn": "2021-11-23T18:34:33.000Z",
"enabled": true,
"recoverableDays": 90,
"recoveryLevel": "Recoverable+Purgeable",
"id": "https: //YOUR-KEYVAULT-ENDPOINT/secrets/secret1637692472606/YOUR-VERSION",
"vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT",
"version": "YOUR-VERSION",
"name": "secret1637692472606"

Integrazione con Configurazione app

Azure SDK fornisce un metodo helper, parseKeyVaultSecretIdentifier, per analizzare l'ID segreto di Key Vault specificato. Questo è necessario se si usano riferimenti di Configurazione app a Key Vault. Configurazione app archivia l'ID segreto di Key Vault. Per analizzare tale ID per ottenere il nome del segreto è necessario il metodo parseKeyVaultSecretIdentifier. Dopo aver ottenuto il nome del segreto, è possibile ottenere il valore del segreto corrente usando il codice di questa guida introduttiva.

Passaggi successivi

In questo argomento di avvio rapido è stato creato un insieme di credenziali delle chiavi e quindi è stato archiviato e recuperato un segreto. Per altre informazioni sul servizio Key Vault e su come integrarlo nelle applicazioni, continuare con gli articoli seguenti.