Biblioteca de cliente do Azure Key Vault Secret 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 seguras. Se quiser saber mais sobre o Azure Key Vault, consulte: O que é o Azure Key Vault?

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

Use a biblioteca de cliente para Segredos do Cofre de Chaves 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.
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: este pacote não pode ser usado no navegador devido a limitações do serviço Azure Key Vault, consulte este documento para obter orientação.

Ligações principais:

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

Como Começar

Ambientes atualmente suportados

Versões LTS do Node.js

Pré-requisitos

Uma assinatura do Azure
Um recurso Key Vault
Um existente do Azure Key Vault. Se precisar de criar um cofre de chaves, pode fazê-lo no Portal do Azure seguindo os passos indicados em este documento. Como alternativa, você pode usar a CLI do Azure seguindo as etapas em este documento.

Instale o pacote

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

npm install @azure/keyvault-secrets

Instalar a biblioteca de identidades

Os clientes do Cofre da Chave são autenticados usando a Biblioteca de Identidades do Azure. Instale-o também usando npm

npm install @azure/identity

Configurar o TypeScript

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

npm install @types/node

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

Conceitos-chave

O de 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 Secret é uma versão de um segredo no Cofre da Chave. Cada vez que um usuário atribui um valor a um nome secreto 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.
de exclusão suave permite que os Cofres de Chaves suportem a exclusão e a limpeza como duas etapas separadas, para que os segredos excluídos não sejam imediatamente perdidos. Isso só acontece se o Cofre da Chave tiver de exclusão suave habilitada.
Um de backup Secret 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 Ative Directory

O serviço Cofre da Chave depende do Azure Ative Directory para autenticar solicitações para suas APIs. O pacote @azure/identity fornece uma variedade de tipos de credenciais 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, um de 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 de desenvolvimento local e produção. Além disso, recomendamos o uso de um de identidade gerenciado para autenticação em ambientes de produção.

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

Aqui está um exemplo rápido. Primeiro, importe DefaultAzureCredential e SecretClient. Depois que eles forem importados, podemos nos conectar em seguida ao serviço Cofre de Chaves:

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 do serviço Azure Key Vault

Por padrão, esse pacote usa a versão mais recente do serviço Azure Key Vault, que é 7.1. A única outra versão suportada é 7.0. Você pode alterar a versão de 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 abrangem algumas das tarefas comuns usando os Segredos do Cofre da Chave do Azure. Os cenários aqui abordados consistem em:

Criando e definindo um segredo.
Obter um segredo.
Criação e atualização de segredos com atributos.
Eliminar um segredo.
Iteração de listas de segredos.

Criar e definir um segredo

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

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

Obter 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ê pode obter uma versão diferente da chave se especificá-la 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,
);

Criação e atualização de segredos com atributos

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

tags: Qualquer conjunto de valores-chave que podem ser usados para pesquisar e filtrar segredos.
contentType: Qualquer string que possa ser usada para ajudar o recetor 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 setSecret, logo após o nome e o valor do segredo, da seguinte forma:

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

Eliminar um segredo

O método beginDeleteSecret inicia a exclusão de um segredo. Este processo acontecerá 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 de exclusão suave estiver habilitada para o Cofre da Chave, essa operação rotulará apenas o segredo como um segredo de excluído. Um segredo excluído não pode ser atualizado. Eles só podem ser lidos, recuperados ou expurgados.

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 Longa Execução 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 ligando para poller.getResult(). Você também pode esperar até que a exclusão termine, 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 esperar 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`);

Iteração de listas de segredos

Usando o SecretClient, você pode recuperar e iterar através de todos os segredos em um Cofre de Chaves, bem como através de 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 secreto.

Que pode ser usado da seguinte forma:

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

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

Soluçã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 tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Próximos passos

Você pode encontrar mais exemplos de código através dos seguintes links:

Contribuir

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

Feedback

Esta página foi útil?

Last updated on 2025-06-12