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

  • Artigo

Introdução à biblioteca de clientes de chaves do Azure Key Vault para .NET. O Azure Key Vault é um serviço de nuvem que funciona como um repositório seguro de chaves de criptografia. Você pode armazenar chaves de criptografia, 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 chaves de um cofre de chaves do Azure usando a biblioteca de clientes de chaves do .NET

Recursos da biblioteca de clientes de chaves 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 as chaves, confira:

Pré-requisitos

Este guia de início rápido usa o dotnet e a CLI do Azure

Instalação

Este guia de início rápido usa a biblioteca de identidades 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 as chamadas. Para saber mais, confira Autenticar o cliente na biblioteca de clientes do Azure Idendity.

Entrar no Azure

  1. Execute o comando login.

    az login

    Se a CLI puder abrir o navegador padrão, ela o fará e carregará uma página de entrada do Azure.

    Caso contrário, abra uma página de navegador em https://aka.ms/devicelogin e insira o código de autorização exibido no terminal.

  2. Entre com suas credenciais de conta no navegador.

Permitir acesso ao cofre de chaves

Para conceder permissões de aplicativo ao cofre de chaves por meio do controle de acesso baseado em função (RBAC), atribua uma função usando o comando az role assignment create da CLI do Azure.

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

Substitua <app-id>, <subscription-id>, <resource-group-name> e <your-unique-keyvault-name> pelos valores reais. <app-id> é a ID do Aplicativo (cliente) do aplicativo registrado no Microsoft Entra.

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 de chaves do Azure Key Vault para .NET:

dotnet add package Azure.Security.KeyVault.Keys

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

Com a biblioteca de clientes de chaves do Azure Key Vault para .NET, você pode gerenciar chaves. A seção Exemplos de código mostra como criar um cliente, definir, recuperar e excluir uma chave.

Exemplos de código

Adicionar diretivas

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

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

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.

var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = $"https://{keyVaultName}.vault.azure.net";

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

Salvar uma chave

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

Observação

Se o nome da chave existir, o este 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");

Excluir uma chave

Por fim, 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 Core para interagir com o Key Vault concluindo as seguintes etapas:

  • 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.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

  1. Execute o comando a seguir para compilar o projeto

    dotnet build

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

    dotnet run

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

    Uma variação do seguinte resultado é exibida:

    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óximas etapas

Neste guia de início rápido, você criou um cofre de chaves, armazenou uma chave e a recuperou.

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