Azure Key Vault Secret client library for JavaScript - versão 4.11.1

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 seguras. Se quiser saber mais sobre Azure Key Vault, talvez queira revisar: O que é Azure Key Vault?

O gerenciamento do Azure Key Vault Secrets permite armazenar e controlar de forma segura o acesso a tokens, senhas, certificados, chaves API e outros segredos.

Use a biblioteca cliente para Azure Key Vault Segredos na sua Node.js aplicação 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.

Nota: Este pacote não pode ser usado no navegador devido a limitações de Azure Key Vault serviço, consulte este documento para orientações.

Links de chave:

Código-fonte
Pacote (npm)
documentação de referência da API
documentação do produto
Samples

Como começar

Ambientes com suporte no momento

Versões LTS do Node.js

Pré-requisitos

Uma assinatura Azure
Um recurso Key Vault
Um Azure Key Vault existente. Se você precisar criar um cofre de chaves, pode fazer isso no portal do Azure seguindo os passos em este documento. Alternativamente, você pode usar o CLI do Azure seguindo os passos em este documento.

Instalar o pacote

Instale a biblioteca cliente Azure Key Vault Secret usando npm:

npm install @azure/keyvault-secrets

Instalar a biblioteca de identidades

Os clientes do Key Vault autenticam 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 da API relacionados a segredos na API Azure Key Vault de uma aplicação 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ó acontece se o Key Vault tiver soft-delete ativado.
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 Azure Active Directory

O serviço Key Vault depende do Azure Active Directory para autenticar requisições em 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 Azure Key Vault, você precisará criar uma instância da classe SecretClient, uma URL vault 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 formas de autenticação e seus respectivos tipos de credenciais na Azure Documentação de Identidade.

Aqui está um exemplo rápido. Primeiro, importe DefaultAzureCredential e SecretClient. Depois de importados, podemos nos conectar ao serviço 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 secrets client and connect to the service
const client = new SecretClient(url, credential);

Para ambientes de navegador, use o InteractiveBrowserCredential do pacote @azure/identity para autenticar.

import { InteractiveBrowserCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new SecretClient(url, credential);

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

Por padrão, este pacote usa a versão mais recente do serviço 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 trechos de código que cobrem algumas das tarefas comuns usando o Azure Key Vault Secrets. Os cenários abordados aqui consistem em:

Criando e definindo um segredo.
Obtendo um segredo.
Criação e atualização de segredos com atributos.
Excluindo um segredo.
Iterando listas de segredos.

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 soft-delete estiver ativado para o Key Vault, essa operação só rotulará o segredo como deleted secreto. 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 de um Key Vault, assim 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

Veja nosso guia solução de problemas para 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 para esta biblioteca, por favor leia o guia contribuição para saber mais sobre como construir e testar o código.

Comentários

Esta página foi útil?

Last updated on 2026-04-09