Partilhar via

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

  • Artigo

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

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

Utilize a biblioteca de cliente dos Segredos do Azure Key Vault na sua aplicação de Node.js para:

  • Obter, definir e eliminar segredos.
  • Atualize um segredo e os seus atributos.
  • Faça uma cópia de segurança e restaure um segredo.
  • Obter, remover ou recuperar um segredo eliminado.
  • Obtenha todas as versões de um segredo.
  • Obtenha todos os segredos.
  • Obter todos os segredos eliminados.

Nota: este pacote não pode ser utilizado no browser devido às limitações do serviço Key Vault do Azure. Veja este documento para obter orientações.

Ligações principais:

Introdução

Ambientes atualmente suportados

Pré-requisitos

Instalar o pacote

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

npm install @azure/keyvault-secrets

Instalar a biblioteca de identidades

Key Vault os clientes autenticam-se com a Biblioteca de Identidades do Azure. Instale-o também com o npm

npm install @azure/identity

Configurar TypeScript

Os utilizadores do TypeScript precisam de ter definições de tipo de Nó instaladas:

npm install @types/node

Também tem de ativar compilerOptions.allowSyntheticDefaultImports no seu tsconfig.json. Tenha em atenção que, se tiver ativado compilerOptions.esModuleInterop, allowSyntheticDefaultImports está ativado por predefinição. Veja o 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 da API relacionados com segredos na API de Key Vault do Azure a partir de uma aplicação JavaScript. Uma vez inicializado, fornece um conjunto básico de métodos que podem ser utilizados para criar, ler, atualizar e eliminar segredos.
  • Uma versão secreta é uma versão de um segredo no Key Vault. Sempre que um utilizador atribui um valor a um nome de segredo exclusivo, é criada uma nova versão desse segredo. A obtenção de um segredo por um nome devolverá sempre o valor mais recente atribuído, a menos que seja fornecida uma versão específica à consulta.
  • A eliminação recuperável permite que os Key Vaults suportem a eliminação e remoção como dois passos separados, pelo que os segredos eliminados não são imediatamente perdidos. Isto só acontece se o Key Vault tiver a eliminação recuperável ativada.
  • Uma cópia de segurança secreta pode ser gerada a partir de qualquer segredo criado. Estas cópias de segurança são provenientes de dados binários e só podem ser utilizadas para regenerar um segredo eliminado anteriormente.

Autenticar com o Azure Active Directory

O serviço Key Vault depende do Azure Active Directory para autenticar pedidos para as respetivas APIs. O @azure/identity pacote fornece uma variedade de tipos de credenciais que a sua aplicação pode utilizar para o fazer. O README para @azure/identity fornece mais detalhes e exemplos para começar.

Para interagir com o serviço Key Vault do Azure, terá de criar uma instância da classe, um URL do SecretClient cofre e um objeto de credencial. Os exemplos apresentados neste documento utilizam um objeto de credencial com o nome DefaultAzureCredential, que é adequado para a maioria dos cenários, incluindo ambientes de desenvolvimento e produção locais. Além disso, recomendamos a utilização de uma identidade gerida para autenticação em ambientes de produção.

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

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

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

Depois de estes serem importados, podemos ligar-nos 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);

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

Por predefinição, este pacote utiliza a versão mais recente do serviço do Azure Key Vault, que é 7.1. A única outra versão suportada é 7.0. Pode alterar a versão do serviço que está a ser utilizada ao definir a opção serviceVersion no construtor 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 secções seguintes fornecem fragmentos de código que abrangem algumas das tarefas comuns com o Azure Key Vault Secrets. Os cenários abordados aqui consistem em:

Criar e definir um segredo

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

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

Obter um segredo

A forma mais simples de ler segredos do cofre é obter um segredo pelo nome. Esta ação irá obter a versão mais recente do segredo. Opcionalmente, pode obter uma versão diferente da chave se a especificar 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();

Criar e atualizar segredos com atributos

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

  • tags: qualquer conjunto de valores-chave que pode ser utilizado para procurar e filtrar segredos.
  • contentType: qualquer cadeia que possa ser utilizada para ajudar o recetor do segredo a compreender como utilizar o valor do segredo.
  • enabled: um valor booleano 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 obtido.
  • expiresOn: uma determinada data após a qual não é possível obter o valor do segredo.

Um objeto com estes atributos pode ser enviado como o terceiro parâmetro de setSecret, imediatamente a seguir ao nome e valor do segredo, da seguinte forma:

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

Esta ação irá criar uma nova versão do mesmo segredo, que terá os atributos mais recentes fornecidos.

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

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

Eliminar um segredo

O beginDeleteSecret método inicia a eliminação de um Segredo. Este 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 eliminação recuperável estiver ativada para o Key Vault, esta operação só irá etiquetar o segredo como um segredo eliminado. Não é possível atualizar um segredo eliminado. Só podem ser lidas, recuperadas ou removidas.

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

Uma vez que os Segredos demoram algum tempo a ser totalmente eliminados, beginDeleteSecret devolve um objeto Poller que controla a Operação de Execução Prolongada subjacente de acordo com as nossas diretrizes: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

O poller recebido irá permitir-lhe obter o segredo eliminado ao chamar para poller.getResult(). Também pode aguardar até que a eliminação seja concluída, ao executar chamadas de serviço individuais até que o segredo seja eliminado ou ao aguardar 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 forma de aguardar até que o segredo seja totalmente eliminado é efetuar chamadas individuais, da seguinte forma:

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

Listas iterating de segredos

Com o SecretClient, pode obter e iterar todos os segredos num Key Vault, bem como através de todos os segredos eliminados e das versões de um segredo específico. Estão disponíveis os seguintes métodos de API:

  • listPropertiesOfSecrets irá listar todos os seus segredos não eliminados pelos respetivos nomes, apenas nas versões mais recentes.
  • listDeletedSecrets irá listar todos os segredos eliminados pelos respetivos nomes, apenas nas respetivas versões mais recentes.
  • listPropertiesOfSecretVersions irá listar todas as versões de um segredo com base num nome secreto.

O que pode ser utilizado da seguinte forma:

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 estes métodos devolverão todos os resultados disponíveis de uma só vez. Para os obter por páginas, adicione .byPage() logo após invocar o método de API que pretende utilizar, da seguinte forma:

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

Resolução de problemas

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

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos HTTP e respostas, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

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

setLogLevel("info");

Passos seguintes

Pode encontrar mais exemplos de código através das seguintes ligações:

Contribuir

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

Impressões