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

O Azure Key Vault é um serviço que permite encriptar chaves de autenticação, chaves de conta de armazenamento, chaves de encriptação de dados, ficheiros .pfx e palavras-passe usando chaves seguras. Se quiser saber mais sobre Azure Key Vault, pode querer rever: O que é Azure Key Vault?

A gestão do Azure Key Vault Secrets permite-lhe armazenar e controlar de forma segura o acesso a tokens, palavras-passe, certificados, chaves API e outros segredos.

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

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

Ligações principais:

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

Como Começar

Ambientes atualmente suportados

Versões LTS do Node.js

Pré-requisitos

Uma subscrição Azure
Um recurso Key Vault
Um Azure Key Vault existente. Se precisares de criar um cofre de chaves, podes fazê-lo no portal do Azure seguindo os passos em este documento. Em alternativa, pode usar o CLI do Azure seguindo os passos em este documento.

Instale o pacote

Instale a biblioteca cliente Azure Key Vault Secret usando npm:

npm install @azure/keyvault-secrets

Instalar a biblioteca de identidades

Os clientes Key Vault autenticam-se usando a Azure Identity Library. 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 cliente Secret é a interface principal para interagir com os métodos API relacionados com 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 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. Isto só acontece se o Key Vault tiver soft-delete ativado.
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 Azure Active Directory

O serviço Key Vault depende do Azure Active Directory para autenticar pedidos nas 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 o ajudar a começar.

Para interagir com o serviço Azure Key Vault, terá de 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 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.

Pode encontrar mais informações sobre diferentes formas de autenticação e os respetivos tipos de credenciais na documentação Azure Identidade.

Aqui está um exemplo rápido. Primeiro, importe DefaultAzureCredential e SecretClient. Depois de importados, podemos ligar-nos 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);

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

Por defeito, este pacote utiliza 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 secções seguintes fornecem excertos de código que cobrem algumas das tarefas comuns que utilizam o Azure Key Vault Secrets. 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 o soft-delete estiver ativado para o Key Vault, esta operação só irá rotular o segredo como deleted. 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, pode recuperar e iterar por todos os segredos de um Key Vault, bem como por todos os segredos apagados 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 o nosso guia resoluçã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 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 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