Guia de início rápido: biblioteca de cliente de chaves do Azure Key Vault para JavaScript

Artigo
08/07/2024

Introdução à biblioteca de cliente de chaves do Azure Key Vault para JavaScript. O Azure Key Vault é um serviço de nuvem que fornece um armazenamento seguro para chaves criptográficas. Pode armazenar chaves, palavras-passe, certificados e outros segredos em segurança. Os cofres de chaves do Azure podem ser criados e geridos através do portal do Azure. Neste início rápido, você aprenderá a criar, recuperar e excluir chaves de um cofre de chaves do Azure usando a biblioteca de cliente de chaves JavaScript.

Recursos da biblioteca do cliente Key Vault:

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

Para obter mais informações sobre o Cofre da Chave e as chaves, consulte:

Descrição geral do Cofre de Chaves
Visão geral das chaves.

Pré-requisitos

Uma assinatura do Azure - crie uma gratuitamente.
Atual Node.js LTS.
CLI do Azure
Um Cofre de Chaves existente - você pode criar um usando:

Uma assinatura do Azure - crie uma gratuitamente.
Atual Node.js LTS.
TypeScript 5+
CLI do Azure.
Um Cofre de Chaves existente - você pode 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 seu navegador padrão, ela fará isso e carregará uma página de entrada do Azure.

Caso contrário, abra uma página do navegador e https://aka.ms/devicelogin insira o código de autorização exibido no seu terminal.
Inicie sessão com as credenciais da sua conta no browser.

Criar novo aplicativo Node.js

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

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

Instalar pacotes Key Vault

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

Conceder acesso ao seu cofre de chaves

Para obter permissões para seu cofre de chaves por meio do RBAC (Controle de Acesso Baseado em Função), atribua uma função ao seu "Nome Principal do Usuário" (UPN) usando o comando az role assignment create da CLI do Azure.

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 seus valores reais. Seu UPN normalmente estará no formato de um endereço de e-mail (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 de aplicativo para a maioria dos serviços do Azure devem ser autorizadas. Usar o método DefaultAzureCredential fornecido pela biblioteca de cliente do Azure Identity é a abordagem recomendada para implementar conexões sem senha aos serviços do Azure em seu código. DefaultAzureCredential suporta vários métodos de autenticação e determina qual método deve ser usado em tempo de execução. Essa abordagem permite que seu aplicativo use métodos de autenticação diferentes em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

Neste início rápido, DefaultAzureCredential autentica-se 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 DefaultAzureCredential código 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, consulte Visão geral da identidade gerenciada.

Neste código, o ponto de extremidade do seu cofre de chaves é usado para criar o cliente do cofre de chaves. O formato do ponto final parece, https://<your-key-vault-name>.vault.azure.net mas pode mudar para nuvens soberanas. Para obter mais informações sobre como autenticar no cofre de chaves, consulte o Guia do desenvolvedor.

Exemplo de código

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

Esse código usa as seguintes classes e métodos do Key Vault Secret:

Configurar a estrutura do aplicativo

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 exemplo de aplicação

Execute a aplicação:
```
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 novo arquivo de texto e cole o código a seguir 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 exemplo de aplicação

Crie o aplicativo TypeScript:
```
tsc
```
Execute a aplicação:
```
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 do aplicativo

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

Próximos passos

Neste início rápido, você criou um cofre de chaves, armazenou uma chave e recuperou essa chave. Para saber mais sobre o Key Vault e como integrá-lo com seus aplicativos, continue nestes 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
Consulte o guia do desenvolvedor do Azure Key Vault
Revise a visão geral de segurança do Cofre de Chaves

Partilhar via

Guia de início rápido: biblioteca de cliente de chaves do Azure Key Vault para JavaScript

Pré-requisitos

Criar novo aplicativo Node.js

Instalar pacotes Key Vault

Conceder acesso ao seu cofre de chaves

Definir variáveis de ambiente

Autenticar e criar um cliente

Exemplo de código

Configurar a estrutura do aplicativo

Executar o exemplo de aplicação

Executar o exemplo de aplicação

Integração com a configuração do aplicativo

Próximos passos

Comentários

Recursos adicionais

Partilhar via

Guia de início rápido: biblioteca de cliente de chaves do Azure Key Vault para JavaScript

Pré-requisitos

Iniciar sessão no Azure

Criar novo aplicativo Node.js

Instalar pacotes Key Vault

Conceder acesso ao seu cofre de chaves

Definir variáveis de ambiente

Autenticar e criar um cliente

Exemplo de código

Configurar a estrutura do aplicativo

Executar o exemplo de aplicação

Executar o exemplo de aplicação

Integração com a configuração do aplicativo

Próximos passos

Comentários

Recursos adicionais