Biblioteca de clientes do Azure Key Vault Secret para JavaScript – versão 4.8.0

  • Artigo

O Azure Key Vault é um serviço que permite criptografar chaves de autenticação, chaves de conta de armazenamento, chaves de criptografia de dados, arquivos .pfx e senhas usando chaves protegidas. Se você quiser saber mais sobre o Azure Key Vault, talvez queira examinar: O que é o Azure Key Vault?

O gerenciamento de Segredos do Azure Key Vault permite armazenar e controlar com segurança o acesso a tokens, senhas, certificados, chaves de API e outros segredos.

Use a biblioteca de clientes para segredos de Key Vault do Azure em seu aplicativo Node.js para:

  • Obter, definir e excluir segredos.
  • Atualize um segredo e seus atributos.
  • Faça backup e restaure um segredo.
  • Obter, limpar ou recuperar um segredo excluído.
  • Obtenha todas as versões de um segredo.
  • Obter todos os segredos.
  • Obter todos os segredos excluídos.

Observação: este pacote não pode ser usado no navegador devido a limitações de serviço do Azure Key Vault, consulte este documento para obter diretrizes.

Links principais:

Introdução

Ambientes com suporte no momento

Pré-requisitos

Instalar o pacote

Instale a biblioteca de clientes do Azure Key Vault Secret usando o npm:

npm install @azure/keyvault-secrets

Instalar a biblioteca de identidade

Key Vault clientes se autenticam usando a Biblioteca de Identidade do Azure. Instale-o também usando o npm

npm install @azure/identity

Configurar TypeScript

Os usuários do TypeScript precisam ter definições de tipo de nó instaladas:

npm install @types/node

Você também precisa habilitar compilerOptions.allowSyntheticDefaultImports em seu tsconfig.json. Observe que, se você tiver habilitado compilerOptions.esModuleInterop, allowSyntheticDefaultImports será habilitado por padrão. Consulte o manual de opções do compilador do TypeScript para obter mais informações.

Principais conceitos

  • O cliente Secret é a interface principal para interagir com os métodos de API relacionados a segredos na API do Azure Key Vault de um aplicativo JavaScript. Depois de inicializado, ele fornece um conjunto básico de métodos que podem ser usados para criar, ler, atualizar e excluir segredos.
  • Uma versão secreta é uma versão de um segredo no Key Vault. Sempre que um usuário atribui um valor a um nome de segredo exclusivo, uma nova versão desse segredo é criada. Recuperar um segredo por um nome sempre retornará o valor mais recente atribuído, a menos que uma versão específica seja fornecida à consulta.
  • A exclusão reversível permite que os Key Vaults ofereçam suporte à exclusão e à limpeza como duas etapas separadas, portanto, os segredos excluídos não são perdidos imediatamente. Isso só acontecerá se o Key Vault tiver a exclusão reversível habilitada.
  • Um backup secreto pode ser gerado a partir de qualquer segredo criado. Esses backups vêm como dados binários e só podem ser usados para regenerar um segredo excluído anteriormente.

Autenticação com o Azure Active Directory

O serviço Key Vault depende do Azure Active Directory para autenticar solicitações em suas APIs. O @azure/identity pacote fornece uma variedade de tipos de credenciais que seu aplicativo pode usar para fazer isso. O LEIAME para @azure/identity fornece mais detalhes e exemplos para começar.

Para interagir com o serviço de Key Vault do Azure, você precisará criar uma instância da SecretClient classe, uma URL do cofre e um objeto de credencial. Os exemplos mostrados neste documento usam um objeto de credencial chamado DefaultAzureCredential, que é apropriado para a maioria dos cenários, incluindo ambientes locais de desenvolvimento e produção. Além disso, recomendamos usar uma identidade gerenciada para autenticação em ambientes de produção.

Você pode encontrar mais informações sobre diferentes maneiras de autenticação e seus tipos de credencial correspondentes na documentação da Identidade do Azure.

Aqui está um exemplo rápido. Primeiro, importe DefaultAzureCredential e SecretClient:

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

Depois que eles forem importados, poderemos nos conectar ao serviço Key Vault:

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

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Lastly, create our secrets client and connect to the service
const client = new SecretClient(url, credential);

Especificando a versão da API de serviço do Azure Key Vault

Por padrão, esse pacote usa a versão mais recente do serviço Key Vault do Azure, que é 7.1. A única outra versão com suporte é 7.0. Você pode alterar a versão do serviço que está sendo usada definindo a opção serviceVersion no construtor do cliente, conforme mostrado abaixo:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Change the Azure Key Vault service API version being used via the `serviceVersion` option
const client = new SecretClient(url, credential, {
  serviceVersion: "7.0",
});

Exemplos

As seções a seguir fornecem snippets de código que abrangem algumas das tarefas comuns usando o Azure Key Vault Segredos. Os cenários abordados aqui consistem em:

Criando e definindo um segredo

setSecret atribui um valor fornecido ao nome do segredo especificado. Se já existir um segredo com o mesmo nome, uma nova versão do segredo será criada.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue");
  console.log("result: ", result);
}

main();

Obtendo um segredo

A maneira mais simples de ler segredos de volta do cofre é obter um segredo por nome. Isso recuperará a versão mais recente do segredo. Opcionalmente, você poderá obter uma versão diferente da chave se especifique-a como parte dos parâmetros opcionais.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const latestSecret = await client.getSecret(secretName);
  console.log(`Latest version of the secret ${secretName}: `, latestSecret);
  const specificSecret = await client.getSecret(secretName, { version: latestSecret.properties.version! });
  console.log(`The secret ${secretName} at the version ${latestSecret.properties.version!}: `, specificSecret);
}

main();

Criando e atualizando segredos com atributos

Um segredo pode ter mais informações do que seu nome e seu valor. Eles também podem incluir os seguintes atributos:

  • tags: qualquer conjunto de chave-valores que pode ser usado para pesquisar e filtrar segredos.
  • contentType: qualquer cadeia de caracteres que possa ser usada para ajudar o receptor do segredo a entender como usar o valor do segredo.
  • enabled: um valor booliano que determina se o valor do segredo pode ser lido ou não.
  • notBefore: uma determinada data após a qual o valor do segredo pode ser recuperado.
  • expiresOn: uma determinada data após a qual o valor do segredo não pode ser recuperado.

Um objeto com esses atributos pode ser enviado como o terceiro parâmetro de setSecret, logo após o nome e o valor do segredo, da seguinte maneira:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue", {
    enabled: false,
  });
}

main();

Isso criará uma nova versão do mesmo segredo, que terá os atributos fornecidos mais recentes.

Os atributos também podem ser atualizados para uma versão secreta existente com updateSecretProperties, da seguinte maneira:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.getSecret(secretName);
  await client.updateSecretProperties(secretName, result.properties.version, { enabled: false });
}

main();

Excluir um segredo

O beginDeleteSecret método inicia a exclusão de um Segredo. Esse processo ocorrerá em segundo plano assim que os recursos necessários estiverem disponíveis.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  await client.beginDeleteSecret(secretName);
}

main();

Se a exclusão reversível estiver habilitada para o Key Vault, essa operação rotulará apenas o segredo como um segredo excluído. Um segredo excluído não pode ser atualizado. Eles só podem ser lidos, recuperados ou limpos.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  const deletedSecret = poller.getResult();

  // The secret is being deleted. Only wait for it if you want to restore it or purge it.
  await poller.pollUntilDone();

  // You can also get the deleted secret this way:
  await client.getDeletedSecret(secretName);

  // Deleted secrets can also be recovered or purged.

  // recoverDeletedSecret returns a poller, just like beginDeleteSecret.
  const recoverPoller = await client.beginRecoverDeletedSecret(secretName);
  await recoverPoller.pollUntilDone();

  // And then, to purge the deleted secret:
  await client.purgeDeletedSecret(secretName);
}

main();

Como Segredos levam algum tempo para serem totalmente excluídos, beginDeleteSecret retorna um objeto Poller que controla a Operação de Execução Longa subjacente de acordo com nossas diretrizes: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

O sondador recebido permitirá que você obtenha o segredo excluído chamando para poller.getResult(). Você também pode aguardar até que a exclusão seja concluída executando chamadas de serviço individuais até que o segredo seja excluído ou aguardando até que o processo seja concluído:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  let deletedSecret = poller.getResult();

  // Or you can wait until the secret finishes being deleted:
  deletedSecret = await poller.pollUntilDone();
  console.log(deletedSecret);
}

main();

Outra maneira de aguardar até que o segredo seja totalmente excluído é fazer chamadas individuais, da seguinte maneira:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");
const { delay } = require("@azure/core-util");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  while (!poller.isDone()) {
    await poller.poll();
    await delay(5000);
  }

  console.log(`The secret ${secretName} is fully deleted`);
}

main();

Iterando listas de segredos

Usando o SecretClient, você pode recuperar e iterar todos os segredos em um Key Vault, bem como por todos os segredos excluídos e as versões de um segredo específico. Os seguintes métodos de API estão disponíveis:

  • listPropertiesOfSecrets listará todos os segredos não excluídos por seus nomes, somente em suas versões mais recentes.
  • listDeletedSecrets listará todos os segredos excluídos por seus nomes, somente em suas versões mais recentes.
  • listPropertiesOfSecretVersions listará todas as versões de um segredo com base em um nome secreto.

Que pode ser usado da seguinte maneira:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let secretProperties of client.listPropertiesOfSecrets()) {
    console.log("Secret properties: ", secretProperties);
  }
  for await (let deletedSecret of client.listDeletedSecrets()) {
    console.log("Deleted secret: ", deletedSecret);
  }
  for await (let versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
    console.log("Version properties: ", versionProperties);
  }
}

main();

Todos esses métodos retornarão todos os resultados disponíveis de uma só vez. Para recuperá-los por páginas, adicione .byPage() logo após invocar o método de API que você deseja usar, da seguinte maneira:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let page of client.listPropertiesOfSecrets().byPage()) {
    for (let secretProperties of page) {
      console.log("Secret properties: ", secretProperties);
    }
  }
  for await (let page of client.listDeletedSecrets().byPage()) {
    for (let deletedSecret of page) {
      console.log("Deleted secret: ", deletedSecret);
    }
  }
  for await (let page of client.listPropertiesOfSecretVersions(secretName).byPage()) {
    for (let versionProperties of page) {
      console.log("Version properties: ", versionProperties);
    }
  }
}

main();

Solução de problemas

Consulte nosso guia de solução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

A habilitação do log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o log pode ser habilitado no runtime chamando setLogLevel em @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Próximas etapas

Você pode encontrar mais exemplos de código por meio dos seguintes links:

Contribuição

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber como criar e testar o código.

Impressões