Partilhar via

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

  • Artigo

Introdução à biblioteca de cliente secreta do Azure Key Vault para JavaScript. O Azure Key Vault é um serviço de nuvem que fornece um armazenamento seguro para segredos. 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 guia de início rápido, você aprenderá a criar, recuperar e excluir segredos de um cofre de chaves do Azure usando a biblioteca de cliente 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 Key Vault e segredos, consulte:

Pré-requisitos

Pré-requisitos

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

Iniciar sessão no Azure

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

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

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

  2. Inicialize o projeto Node.js:

    npm init -y

Instalar pacotes Key Vault

  1. Usando o terminal, instale a biblioteca de cliente de segredos do Azure Key Vault, @azure/keyvault-secrets para Node.js.

    npm install @azure/keyvault-secrets

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

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 { 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);
});

Executar o exemplo de aplicação

  1. Execute a aplicação:

    node index.js

  2. Os métodos create e get retornam um objeto JSON completo para o segredo:

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

    O método update retorna os pares nome/valores das propriedades :

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

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

Executar o exemplo de aplicação

  1. Crie o aplicativo TypeScript:

    tsc

  2. Execute a aplicação:

    node index.js

  3. Os métodos create e get retornam um objeto JSON completo para o segredo:

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

    O método update retorna os pares nome/valores das propriedades :

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

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

O SDK do Azure fornece um método auxiliar, parseKeyVaultSecretIdentifier, para analisar a ID Secreta do Cofre de Chaves 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 Secreto do Cofre da Chave. Você precisa do método parseKeyVaultSecretIdentifier para analisar essa ID para obter o nome secreto. Depois de ter o nome secreto, você pode obter o valor secreto 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 um segredo e recuperou esse segredo. Para saber mais sobre o Key Vault e como integrá-lo com seus aplicativos, continue nos artigos abaixo.