Compartilhar via

Biblioteca de clientes secreta do Azure Key Vault para JavaScript – versão 4.10.0

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 que você armazene com segurança e controle rigidamente o acesso a tokens, senhas, certificados, chaves de API e outros segredos.

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

  • Obtenha, defina e exclua segredos.
  • Atualize um segredo e seus atributos.
  • Faça backup e restaure um segredo.
  • Obtenha, limpe ou recupere um segredo excluído.
  • Obtenha todas as versões de um segredo.
  • Obtenha todos os segredos.
  • Obtenha todos os segredos excluídos.

Observação: esse 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 de chave:

Como começar

Ambientes com suporte no momento

Pré-requisitos

Instalar o pacote

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

npm install @azure/keyvault-secrets

Instalar a biblioteca de identidades

Os clientes do Key Vault são autenticados usando a Biblioteca de Identidade do Azure. Instalá-lo também usando o npm

npm install @azure/identity

Configurar TypeScript

Os usuários do TypeScript precisam ter definições de tipo node 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 estará habilitado por padrão. Consulte o manual de opções do compilador do TypeScript para obter mais informações.

Conceitos principais

  • 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. Uma vez 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. Cada vez 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, para que os segredos excluídos não sejam perdidos imediatamente. Isso só acontecerá se o Key Vault tiver de 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 do Key Vault depende do Azure Active Directory para autenticar solicitações para suas APIs. O pacote @azure/identity fornece uma variedade de tipos de credencial que seu aplicativo pode usar para fazer isso. O README para @azure/identity fornece mais detalhes e exemplos para você começar.

Para interagir com o serviço do Azure Key Vault, você precisará criar uma instância da classe SecretClient, 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 do Azure Identity.

Aqui está um exemplo rápido. Primeiro, importe DefaultAzureCredential e SecretClient. Depois que eles forem importados, poderemos nos conectar ao serviço do Key Vault:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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 keys 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 do Azure Key Vault, 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:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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`;

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

Exemplos

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

Criando e definindo um segredo

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

const result = await client.setSecret(secretName, "MySecretValue");
console.log("result: ", result);

Obtendo um segredo

A maneira mais simples de ler segredos de volta do cofre é obter um segredo pelo 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.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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,
);

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 chaves-valor 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 secreto.
  • enabled: Um valor booleano que determina se o valor secreto pode ser lido ou não.
  • notBefore: Uma determinada data após a qual o valor secreto pode ser recuperado.
  • expiresOn: Uma determinada data após a qual o valor secreto não pode ser recuperado.

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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 de segredo existente com updateSecretProperties, da seguinte maneira:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

await client.beginDeleteSecret(secretName);

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.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

Como os 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 poller recebido permitirá que você obtenha o segredo excluído chamando .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:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const poller = await client.beginDeleteSecret(secretName);
while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

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

Iterando listas de segredos

Usando o SecretClient, você pode recuperar e iterar por 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 seus segredos não excluídos por seus nomes, apenas em suas versões mais recentes.
  • listDeletedSecrets listará todos os seus segredos excluídos por seus nomes, apenas em suas versões mais recentes.
  • listPropertiesOfSecretVersions listará todas as versões de um segredo com base em um nome de segredo.

Que pode ser usado da seguinte maneira:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

for await (const secretProperties of client.listPropertiesOfSecrets()) {
  console.log("Secret properties: ", secretProperties);
}

for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("Deleted secret: ", deletedSecret);
}

for await (const versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
  console.log("Version properties: ", versionProperties);
}

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

Resolução de problemas

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

Habilitar o registro em 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 registro em log pode ser habilitado em runtime chamando setLogLevel no @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:

Contribuindo

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

  • Last updated on