Guia de Início Rápido – Biblioteca de clientes da chave do Azure Key Vault para JavaScript

Artigo
10/05/2024

Introdução à biblioteca de clientes de chaves do Azure Key Vault para JavaScript. O Azure Key Vault é um serviço de nuvem que funciona como um repositório seguro de chaves de criptografia. Você pode armazenar chaves, senhas, certificados e outros segredos com segurança. Os cofres de chaves do Azure podem ser criados e gerenciados por meio do portal do Azure. Neste guia de início rápido, você aprenderá a criar, recuperar e excluir chaves de um cofre de chaves do Azure usando a biblioteca de clientes de chaves do JavaScript.

Recursos da biblioteca de clientes do Key Vault:

Documentação de referência da API | Código-fonte da biblioteca | Pacote (npm)

Para obter mais informações sobre o Key Vault e as chaves, confira:

Pré-requisitos

Uma assinatura do Azure – crie uma gratuitamente.
Atual LTS do Node.js.
CLI do Azure
Um Key Vault existente − é possível criar um usando:

Uma assinatura do Azure – crie uma gratuitamente.
Atual LTS do Node.js.
TypeScript 5+
CLI do Azure.
Um Key Vault existente − é possível criar um usando:

Este início rápido pressupõe que você esteja executando a CLI do Azure.

Execute o comando login.
```
az login
```
Se a CLI puder abrir o navegador padrão, ela o fará e carregará uma página de entrada do Azure.

Caso contrário, abra uma página de navegador em https://aka.ms/devicelogin e insira o código de autorização exibido no terminal.
Entre com suas credenciais de conta no navegador.

Criar um aplicativo Node.js

Crie um aplicativo Node.js que usa seu cofre de chaves.

Em um terminal, crie uma pasta nomeada key-vault-node-app e altere para essa pasta:
```
mkdir key-vault-node-app && cd key-vault-node-app
```
Inicializar o projeto Node.js:
```
npm init -y
```

Instalar pacotes do Key Vault

Usando o terminal, instale a biblioteca de clientes de segredos do Azure Key Vault, @azure/keyvault-keys para Node.js.
```
npm install @azure/keyvault-keys
```
Instale a biblioteca de clientes da Identidade do Azure, pacote @azure/identity para autenticar em um Key Vault.
```
npm install @azure/identity
```

Permitir acesso ao cofre de chaves

Para obter permissões para o cofre de chaves por meio do RBAC (controle de acesso baseado em função), atribua uma função ao seu UPN (nome principal do usuário) usando o comando da CLI do 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>"

Substitua <upn>, <subscription-id>, <resource-group-name> e <your-unique-keyvault-name> pelos valores reais. Seu UPN normalmente estará no formato de um endereço de email (por exemplo, username@domain.com).

Definir variáveis de ambiente

Este aplicativo está usando o ponto de extremidade do cofre de chaves como uma variável de ambiente chamada 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>

Autenticar e criar um cliente

As solicitações do aplicativo para a maioria dos serviços do Azure precisam ser autorizadas. O uso do método DefaultAzureCredential fornecido pela biblioteca de clientes da Identidade do Azure é a abordagem recomendada para implementar conexões sem senha com os serviços do Azure no código. DefaultAzureCredential dá suporte a vários métodos de autenticação e determina quais métodos devem ser usados no runtime. Essa abordagem permite que seu aplicativo use diferentes métodos de autenticação em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

Neste guia de início rápido, DefaultAzureCredential se autenticará no cofre de chaves usando as credenciais do usuário de desenvolvimento local conectado à CLI do Azure. Quando o aplicativo é implantado no Azure, o mesmo código DefaultAzureCredential pode descobrir e usar automaticamente uma identidade gerenciada atribuída a um Serviço de Aplicativo, máquina virtual ou outros serviços. Para obter mais informações, confira Visão geral da Identidade Gerenciada.

Nesse código, o ponto de extremidade do cofre de chaves é usado para criar o cliente do cofre de chaves. O formato do ponto de extremidade é semelhante a https://<your-key-vault-name>.vault.azure.net, mas pode ser alterado para nuvens soberanas. Para obter mais informações sobre como se autenticar no cofre de chaves, confira Guia do Desenvolvedor.

Exemplo de código

Os exemplos de código abaixo mostrarão como criar um cliente, definir, recuperar e excluir um segredo.

Esse código usa os seguintes métodos e classes secretos do Key Vault:

Configurar o framework de aplicativos

Crie um novo arquivo de texto e cole o código a seguir no arquivo 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);
});

Executar o aplicativo de exemplo

Executar o aplicativo:
```
node index.js
```

Os métodos create e get retornam um objeto JSON completo para a chave:

"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"
  }
}

Crie um arquivo de texto e cole o seguinte código no arquivo 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);
});

Executar o aplicativo de exemplo

Criar o aplicativo TypeScript:
```
tsc
```
Executar o aplicativo:
```
node index.js
```

Os métodos create e get retornam um objeto JSON completo para a chave:

"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"
  }
}

Integração com a Configuração de Aplicativos do Azure

O SDK do Azure fornece um método auxiliar, parseKeyVaultKeyIdentifier, para analisar a ID do Key Vault. Isso será necessário se você usar referências de Configuração de Aplicativos do Key Vault. A Configuração de Aplicativo armazena a ID do Key Vault. Você precisa do método parseKeyVaultKeyIdentifier para analisar essa ID para o nome da chave. Depois de ter o nome da chave, é possível obter o valor da chave atual usando o código deste início rápido.

Próximas etapas

Neste guia de início rápido, você criou um cofre de chaves, armazenou uma chave e a recuperou. Para saber mais sobre o Key Vault e como integrá-lo aos aplicativos, continue lendo estes artigos.

Leia uma Visão geral do Azure Key Vault
Leia uma Visão geral das chaves do Azure Key Vault
Como Proteger o acesso a um cofre de chaves
Confira o Guia do desenvolvedor do Azure Key Vault
Examine a Visão geral de segurança do Key Vault

Compartilhar via

Guia de Início Rápido – Biblioteca de clientes da chave do Azure Key Vault para JavaScript

Pré-requisitos

Criar um aplicativo Node.js

Instalar pacotes do Key Vault

Permitir acesso ao cofre de chaves

Definir variáveis de ambiente

Autenticar e criar um cliente

Exemplo de código

Configurar o framework de aplicativos

Executar o aplicativo de exemplo

Executar o aplicativo de exemplo

Integração com a Configuração de Aplicativos do Azure

Próximas etapas

Comentários

Recursos adicionais

Compartilhar via

Guia de Início Rápido – Biblioteca de clientes da chave do Azure Key Vault para JavaScript

Pré-requisitos

Entrar no Azure

Criar um aplicativo Node.js

Instalar pacotes do Key Vault

Permitir acesso ao cofre de chaves

Definir variáveis de ambiente

Autenticar e criar um cliente

Exemplo de código

Configurar o framework de aplicativos

Executar o aplicativo de exemplo

Executar o aplicativo de exemplo

Integração com a Configuração de Aplicativos do Azure

Próximas etapas

Comentários

Recursos adicionais