Guia de início rápido: biblioteca de cliente de chaves do Azure Key Vault para .NET
Introdução à biblioteca de cliente de chaves do Azure Key Vault para .NET. O Azure Key Vault é um serviço de nuvem que fornece um armazenamento seguro para chaves criptográficas. Você pode armazenar com segurança chaves criptográficas, senhas, certificados e outros segredos. Os cofres de chaves do Azure podem ser criados e geridos através do portal do Azure. Neste guia de início rápido, você aprenderá a criar, recuperar e excluir chaves de um cofre de chaves do Azure usando a biblioteca de cliente de chaves .NET
Recursos da biblioteca do cliente de chaves do Key Vault:
Documentação | de referência da API Pacote de código-fonte | da biblioteca (NuGet)
Para obter mais informações sobre o Cofre da Chave e as chaves, consulte:
- Descrição geral do Cofre de Chaves
- Visão geral das chaves.
Pré-requisitos
- Uma subscrição do Azure - crie uma gratuitamente
- SDK do .NET 6 ou posterior
- CLI do Azure
- Um Cofre de Chaves - você pode criar um usando o portal do Azure, a CLI do Azure ou o Azure PowerShell.
Este guia de início rápido está usando dotnet
e a CLI do Azure
Configurar
Este guia de início rápido está usando a biblioteca de Identidade do Azure com a CLI do Azure para autenticar o usuário nos Serviços do Azure. Os desenvolvedores também podem usar o Visual Studio ou o Visual Studio Code para autenticar suas chamadas, para obter mais informações, consulte Autenticar o cliente com a biblioteca de cliente do Azure Identity.
Iniciar sessão no Azure
Execute o comando
login
.az login
Se a CLI puder abrir seu navegador padrão, ela fará isso e carregará uma página de entrada do Azure.
Caso contrário, abra uma página do navegador e https://aka.ms/devicelogin insira o código de autorização exibido no seu terminal.
Inicie sessão com as credenciais da sua conta no browser.
Conceder acesso ao seu cofre de chaves
Para obter permissões para seu cofre de chaves por meio do RBAC (Controle de Acesso Baseado em Função), atribua uma função ao seu "Nome Principal do Usuário" (UPN) usando o comando az role assignment create da CLI do Azure.
az role assignment create --role "Key Vault Crypto Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"
Substitua <upn>, <subscription-id>, <resource-group-name> e <your-unique-keyvault-name> pelos seus valores reais. Seu UPN normalmente estará no formato de um endereço de e-mail (por exemplo, username@domain.com).
Criar novo aplicativo de console .NET
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
Mude para o diretório key-vault-console-app recém-criado e execute o seguinte comando para criar o projeto:
dotnet build
A saída da compilação não deve conter avisos ou erros.
Build succeeded. 0 Warning(s) 0 Error(s)
Instalar os pacotes
A partir do shell de comando, instale a biblioteca de cliente de chaves do Azure Key Vault para .NET:
dotnet add package Azure.Security.KeyVault.Keys
Para este início rápido, você também precisará instalar a biblioteca de cliente do Azure Identity:
dotnet add package Azure.Identity
Definir variáveis de ambiente
Este aplicativo está usando 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 cliente de chaves do Azure Key Vault para .NET permite gerenciar chaves. A seção Exemplos de código mostra como criar um cliente, definir uma chave, recuperar uma chave e excluir uma chave.
Exemplos de código
Adicionar diretivas
Adicione as seguintes diretivas ao topo da Program.cs:
using System;
using Azure.Identity;
using Azure.Security.KeyVault.Keys;
Autenticar e criar um cliente
As solicitações de aplicativo para a maioria dos serviços do Azure devem ser autorizadas. Usar a classe DefaultAzureCredential fornecida pela biblioteca de cliente do Azure Identity é a abordagem recomendada para implementar conexões sem senha aos serviços do Azure em seu código. DefaultAzureCredential
suporta vários métodos de autenticação e determina qual método deve ser usado em tempo de execução. Essa abordagem permite que seu aplicativo use métodos de autenticação diferentes em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.
Neste início rápido, DefaultAzureCredential
autentica-se 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 DefaultAzureCredential
código 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, consulte 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 autenticar no cofre de chaves, consulte o Guia do desenvolvedor.
var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = $"https://{keyVaultName}.vault.azure.net";
var client = new KeyClient(new Uri(kvUri), new DefaultAzureCredential());
Guardar uma chave
Para esta tarefa, use o método CreateKeyAsync . Os parâmetros do método aceitam um nome de chave e o tipo de chave.
var key = await client.CreateKeyAsync("myKey", KeyType.Rsa);
Nota
Se o nome da chave existir, esse código criará uma nova versão dessa chave.
Recuperar uma chave
Agora você pode recuperar a chave criada anteriormente com o método GetKeyAsync .
var key = await client.GetKeyAsync("myKey");
Eliminar uma chave
Finalmente, vamos excluir e limpar a chave do cofre de chaves com os métodos StartDeleteKeyAsync e PurgeDeletedKeyAsync .
var operation = await client.StartDeleteKeyAsync("myKey");
// You only need to wait for completion if you want to purge or recover the key.
await operation.WaitForCompletionAsync();
var key = operation.Value;
await client.PurgeDeletedKeyAsync("myKey");
Código de exemplo
Modifique o aplicativo de console .NET para interagir com o Cofre da Chave concluindo as seguintes etapas:
Substitua o código no Program.cs pelo seguinte código:
using System; using System.Threading.Tasks; using Azure.Identity; using Azure.Security.KeyVault.Keys; namespace key_vault_console_app { class Program { static async Task Main(string[] args) { const string keyName = "myKey"; var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME"); var kvUri = $"https://{keyVaultName}.vault.azure.net"; var client = new KeyClient(new Uri(kvUri), new DefaultAzureCredential()); Console.Write($"Creating a key in {keyVaultName} called '{keyName}' ..."); var createdKey = await client.CreateKeyAsync(keyName, KeyType.Rsa); Console.WriteLine("done."); Console.WriteLine($"Retrieving your key from {keyVaultName}."); var key = await client.GetKeyAsync(keyName); Console.WriteLine($"Your key version is '{key.Value.Properties.Version}'."); Console.Write($"Deleting your key from {keyVaultName} ..."); var deleteOperation = await client.StartDeleteKeyAsync(keyName); // You only need to wait for completion if you want to purge or recover the key. await deleteOperation.WaitForCompletionAsync(); Console.WriteLine("done."); Console.Write($"Purging your key from {keyVaultName} ..."); await client.PurgeDeletedKeyAsync(keyName); Console.WriteLine(" done."); } } }
Testar e verificar
Execute o seguinte comando para criar o projeto
dotnet build
Execute o seguinte comando para executar o aplicativo.
dotnet run
Quando solicitado, insira um valor secreto. Por exemplo, mySecretPassword.
É apresentada uma variação da seguinte saída:
Creating a key in mykeyvault called 'myKey' ... done. Retrieving your key from mykeyvault. Your key version is '8532359bced24e4bb2525f2d2050738a'. Deleting your key from jl-kv ... done Purging your key from <your-unique-keyvault-name> ... done.
Próximos passos
Neste início rápido, você criou um cofre de chaves, armazenou uma chave e recuperou essa chave.
Para saber mais sobre o Key Vault e como integrá-lo aos seus aplicativos, consulte os seguintes artigos:
- Leia uma visão geral do Azure Key Vault
- Leia uma visão geral das chaves
- Veja um Tutorial do Aplicativo do Cofre da Chave de Acesso do Serviço de Aplicativo
- Veja um tutorial do Cofre da Chave de Acesso da Máquina Virtual
- Consulte o guia do desenvolvedor do Azure Key Vault
- Revise a visão geral de segurança do Cofre de Chaves