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

  • Artigo

Introdução à biblioteca de cliente secreta do Azure Key Vault para .NET. O Azure Key Vault é um serviço de nuvem que fornece um armazenamento seguro para segredos. Pode armazenar chaves, palavras-passe, certificados e outros segredos em segurança. 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 segredos de um cofre de chaves do Azure usando a biblioteca de cliente .NET

Recursos da biblioteca do cliente Key Vault:

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

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

Pré-requisitos

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

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

  1. Execute o comando az 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.

  2. 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 Secrets 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

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

dotnet add package Azure.Security.KeyVault.Secrets

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 secreta do Cofre da Chave do Azure para .NET permite gerenciar segredos. A seção Exemplos de código mostra como criar um cliente, definir um segredo, recuperar um segredo e excluir um segredo.

Exemplos de código

Adicionar diretivas

Adicione as seguintes diretivas ao topo da Program.cs:

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

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.

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

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

Guarde um segredo

Agora que o aplicativo de console está 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. Neste exemplo, a variável secretName armazena a cadeia de caracteres "mySecret".

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

await client.SetSecretAsync(secretName, secretValue);

Nota

Se o nome secreto existir, o código criará uma nova versão desse segredo.

Recuperar um segredo

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

var secret = await client.GetSecretAsync(secretName);

O seu segredo está agora guardado como secret.Value.

Eliminar um segredo

Finalmente, 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 para interagir com o Cofre da Chave concluindo as seguintes etapas:

  1. Substitua o código no Program.cs pelo seguinte código:

    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 seguinte comando para executar o aplicativo.

    dotnet run

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

É apresentada uma variação da seguinte saída:

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óximos passos

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