Guia de início rápido: biblioteca de clientes de segredo do Azure Key Vault para .NET

Introdução à biblioteca de clientes do segredo do Azure Key Vault para .NET. O Azure Key Vault é um serviço de nuvem que funciona como um repositório seguro de segredos. Você pode armazenar chaves, senhas, certificados e outros segredos com segurança. Os cofres de chaves do Azure podem ser criados e gerenciados por meio do portal do Azure. Neste guia de início rápido, você aprenderá a criar, recuperar e excluir segredos de um cofre de chaves do Azure usando a biblioteca de clientes do .NET

Recursos da biblioteca de clientes do Key Vault:

Documentação de referência da API | Código-fonte da biblioteca | Pacote (NuGet)

Para obter mais informações sobre o Key Vault e os segredos, confira:

• Visão Geral do Key Vault
• Visão Geral dos Segredos.

Pré-requisitos

• Uma assinatura do Azure – crie uma gratuitamente
• SDK do .NET 6 ou posterior
• CLI do Azure ou Azure PowerShell
• Um Key Vault – Crie-o um usando o portal do Azure, a CLI do Azure ou o Azure PowerShell

Este início rápido está usando dotnet e a CLI do Azure ou o Azure PowerShell.

Instalação

az role assignment create --role "Key Vault Secrets Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

az role assignment create --role "Key Vault Secrets User" --assignee "<app-id>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

New-AzRoleAssignment -ObjectId "<app-id>" -RoleDefinitionName "Key Vault Secrets User" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Criar um novo aplicativo de console do .NET

1. Em um shell de comando, execute o seguinte comando para criar um projeto chamado key-vault-console-app:

   dotnet new console --name key-vault-console-app
   

2. Altere para o diretório key-vault-console-app recém-criado e execute o seguinte comando para compilar o projeto:

   dotnet build
   

   A saída de compilação não deve conter nenhum aviso ou erro.

   Build succeeded.
    0 Warning(s)
    0 Error(s)
   

Instalar os pacotes

No shell de comando, instale a biblioteca de clientes do segredo do Azure Key Vault para .NET:

dotnet add package Azure.Security.KeyVault.Secrets

Para este guia de início rápido, você também precisará instalar a biblioteca de clientes de identidade do Azure:

dotnet add package Azure.Identity

Definir variáveis de ambiente

Este aplicativo usa o nome do cofre de chaves como uma variável de ambiente chamada KEY_VAULT_NAME.

Windows

set KEY_VAULT_NAME=<your-key-vault-name>

Windows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

macOS ou Linux

export KEY_VAULT_NAME=<your-key-vault-name>

Modelo de objeto

A biblioteca de clientes do segredo do Azure Key Vault para .NET permite que você gerencie segredos. A seção Exemplos de código mostra como criar um cliente, bem como definir, recuperar e excluir um segredo.

Exemplos de código

Adicionar diretivas

Adicione as seguintes diretivas à parte superior de Program.cs:

using System;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

Autenticar e criar um cliente

As solicitações do aplicativo para a maioria dos serviços do Azure precisam ser autorizadas. O uso da classe DefaultAzureCredential fornecida pela biblioteca de clientes da Identidade do Azure é a abordagem recomendada para implementar conexões sem senha com os serviços do Azure no código. DefaultAzureCredential dá suporte a vários métodos de autenticação e determina quais métodos devem ser usados no runtime. Essa abordagem permite que seu aplicativo use diferentes métodos de autenticação em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

Neste guia de início rápido, DefaultAzureCredential se autenticará no cofre de chaves usando as credenciais do usuário de desenvolvimento local conectado à CLI do Azure. Quando o aplicativo é implantado no Azure, o mesmo código DefaultAzureCredential pode descobrir e usar automaticamente uma identidade gerenciada atribuída a um Serviço de Aplicativo, máquina virtual ou outros serviços. Para obter mais informações, confira Visão geral da Identidade Gerenciada.

Neste exemplo, o nome do cofre de chaves é expandido para o URI do cofre de chaves, no formato https://<your-key-vault-name>.vault.azure.net. Para obter mais informações sobre como se autenticar no cofre de chaves, confira Guia do Desenvolvedor.

string keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = "https://" + keyVaultName + ".vault.azure.net";

var client = new SecretClient(new Uri(kvUri), new DefaultAzureCredential());

Salvar um segredo

Agora que o aplicativo de console foi autenticado, adicione um segredo ao cofre de chaves. Para essa tarefa, use o método SetSecretAsync.

O primeiro parâmetro do método aceita um nome para o segredo. Nesta amostra, a variável secretName armazena a cadeia de caracteres “mySecret”.

O segundo parâmetro do método aceita um valor para o segredo. Nesta amostra, o segredo é inserido pelo usuário por meio da linha de comando e armazenado na variável secretValue.

await client.SetSecretAsync(secretName, secretValue);

Recuperar um segredo

Agora, você pode recuperar o valor definido anteriormente com o método GetSecretAsync.

var secret = await client.GetSecretAsync(secretName);

Agora, seu segredo está salvo como secret.Value.

Excluir um segredo

Por fim, vamos excluir o segredo do cofre de chaves com os métodos StartDeleteSecretAsync e PurgeDeletedSecretAsync.

var operation = await client.StartDeleteSecretAsync(secretName);
// You only need to wait for completion if you want to purge or recover the key.
await operation.WaitForCompletionAsync();

await client.PurgeDeletedSecretAsync(secretName);

Código de exemplo

Modifique o aplicativo de console .NET Core para interagir com o Key Vault concluindo as seguintes etapas:

1. Substitua o código em Program.cs pelo código a seguir:

   using System;
   using System.Threading.Tasks;
   using Azure.Identity;
   using Azure.Security.KeyVault.Secrets;
   
   namespace key_vault_console_app
   {
       class Program
       {
           static async Task Main(string[] args)
           {
               const string secretName = "mySecret";
               var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
               var kvUri = $"https://{keyVaultName}.vault.azure.net";
   
               var client = new SecretClient(new Uri(kvUri), new DefaultAzureCredential());
   
               Console.Write("Input the value of your secret > ");
               var secretValue = Console.ReadLine();
   
               Console.Write($"Creating a secret in {keyVaultName} called '{secretName}' with the value '{secretValue}' ...");
               await client.SetSecretAsync(secretName, secretValue);
               Console.WriteLine(" done.");
   
               Console.WriteLine("Forgetting your secret.");
               secretValue = string.Empty;
               Console.WriteLine($"Your secret is '{secretValue}'.");
   
               Console.WriteLine($"Retrieving your secret from {keyVaultName}.");
               var secret = await client.GetSecretAsync(secretName);
               Console.WriteLine($"Your secret is '{secret.Value.Value}'.");
   
               Console.Write($"Deleting your secret from {keyVaultName} ...");
               DeleteSecretOperation operation = await client.StartDeleteSecretAsync(secretName);
               // You only need to wait for completion if you want to purge or recover the secret.
               await operation.WaitForCompletionAsync();
               Console.WriteLine(" done.");
   
               Console.Write($"Purging your secret from {keyVaultName} ...");
               await client.PurgeDeletedSecretAsync(secretName);
               Console.WriteLine(" done.");
           }
       }
   }
   

Testar e verificar

1. Execute o comando a seguir para executar o aplicativo.

   dotnet run
   

2. Quando solicitado, insira um valor secreto. Por exemplo, mySecretPassword.

Uma variação do seguinte resultado é exibida:

Input the value of your secret > mySecretPassword
Creating a secret in <your-unique-keyvault-name> called 'mySecret' with the value 'mySecretPassword' ... done.
Forgetting your secret.
Your secret is ''.
Retrieving your secret from <your-unique-keyvault-name>.
Your secret is 'mySecretPassword'.
Deleting your secret from <your-unique-keyvault-name> ... done.    
Purging your secret from <your-unique-keyvault-name> ... done.

Próximas etapas

Para saber mais sobre o Key Vault e como integrá-lo aos seus aplicativos, confira os seguintes artigos:

• Leia uma Visão geral do Azure Key Vault
• Confira um Tutorial – Acessar o Key Vault no aplicativo do Serviço de Aplicativo
• Confira um Tutorial – Acessar o Key Vault na máquina virtual
• Confira o Guia do desenvolvedor do Azure Key Vault
• Examine a Visão geral de segurança do Key Vault