Share via

Biblioteca de clientes secretos do Azure Key Vault para .NET – versão 4.5.0

  • Artigo

O Azure Key Vault é um serviço de nuvem que fornece um armazenamento seguro de segredos, como senhas e cadeias de conexão de banco de dados.

A biblioteca de clientes do Azure Key Vault segredos permite que você armazene e controle com segurança o acesso a tokens, senhas, chaves de API e outros segredos. Essa biblioteca oferece operações para criar, recuperar, atualizar, excluir, limpar, fazer backup, restaurar e listar os segredos e suas versões.

Código-fonte | Pacote (NuGet) | Documentação | de referência da APIDocumentação do produto | Amostras | Guia de migração

Introdução

Instalar o pacote

Instale a biblioteca de clientes de segredos do Azure Key Vault para .NET com o NuGet:

dotnet add package Azure.Security.KeyVault.Secrets

Pré-requisitos

  • Uma assinatura do Azure.
  • Um Key Vault existente do Azure. Se você precisar criar um Key Vault do Azure, poderá usar o Portal do Azure ou a CLI do Azure.
  • Autorização para um Key Vault existente do Azure usando o RBAC (recomendado) ou o controle de acesso.

Se você usar a CLI do Azure, substitua <your-resource-group-name> e <your-key-vault-name> por seus próprios nomes exclusivos:

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

Autenticar o cliente

Para interagir com o serviço Key Vault do Azure, você precisará criar uma instância da classe SecretClient. Você precisa de uma URL do cofre, que você pode ver como "Nome DNS" no portal e credenciais para instanciar um objeto cliente.

Os exemplos mostrados abaixo usam um DefaultAzureCredential, que é apropriado para a maioria dos cenários, incluindo ambientes locais de desenvolvimento e produção. Além disso, recomendamos usar uma identidade gerenciada para autenticação em ambientes de produção. Você pode encontrar mais informações sobre diferentes maneiras de autenticação e seus tipos de credencial correspondentes na documentação da Identidade do Azure .

Para usar o DefaultAzureCredential provedor mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, primeiro você deve instalar o pacote Azure.Identity:

dotnet add package Azure.Identity

Instancie um DefaultAzureCredential para passar para o cliente. A mesma instância de uma credencial de token poderá ser usada com vários clientes se eles estiverem se autenticando com a mesma identidade.

// Create a new secret client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
var client = new SecretClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

// Create a new secret using the secret client.
KeyVaultSecret secret = client.SetSecret("secret-name", "secret-value");

// Retrieve a secret using the secret client.
secret = client.GetSecret("secret-name");

Principais conceitos

KeyVaultSecret

Um KeyVaultSecret é o recurso fundamental no Key Vault do Azure. Da perspectiva de um desenvolvedor, as APIs de Key Vault do Azure aceitam e retornam valores secretos como cadeias de caracteres.

SecretClient

Um SecretClient fornece operações síncronas e assíncronas no SDK, permitindo a seleção de um cliente com base no caso de uso de um aplicativo. Depois de inicializar um SecretClient, você poderá interagir com segredos no Azure Key Vault.

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções | do cliente Acessando a resposta | Operações de execução prolongada | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

O pacote Azure.Security.KeyVault.Secrets dá suporte a APIs síncronas e assíncronas.

A seção a seguir fornece vários snippets de código usando o client criado acima, abrangendo algumas das tarefas mais comuns relacionadas ao serviço secreto do Azure Key Vault:

Exemplos de sincronização

Exemplos assíncronos

Criar um segredo

SetSecretcria um KeyVaultSecret a ser armazenado no Key Vault do Azure. Se já existir um segredo com o mesmo nome, uma nova versão do segredo será criada.

KeyVaultSecret secret = client.SetSecret("secret-name", "secret-value");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);
Console.WriteLine(secret.Properties.Version);
Console.WriteLine(secret.Properties.Enabled);

Recuperar um segredo

GetSecretrecupera um segredo armazenado anteriormente no Key Vault do Azure.

KeyVaultSecret secret = client.GetSecret("secret-name");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

Atualizar um segredo existente

UpdateSecretPropertiesatualiza um segredo armazenado anteriormente no Key Vault do Azure. Somente os atributos do segredo são atualizados. Para atualizar o valor, chame SecretClient.SetSecret em um segredo com o mesmo nome.

KeyVaultSecret secret = client.GetSecret("secret-name");

// Clients may specify the content type of a secret to assist in interpreting the secret data when its retrieved.
secret.Properties.ContentType = "text/plain";

// You can specify additional application-specific metadata in the form of tags.
secret.Properties.Tags["foo"] = "updated tag";

SecretProperties updatedSecretProperties = client.UpdateSecretProperties(secret.Properties);

Console.WriteLine(updatedSecretProperties.Name);
Console.WriteLine(updatedSecretProperties.Version);
Console.WriteLine(updatedSecretProperties.ContentType);

Excluir um segredo

StartDeleteSecretinicia uma operação de execução prolongada para excluir um segredo armazenado anteriormente no Key Vault do Azure. Você pode recuperar o segredo imediatamente sem aguardar a conclusão da operação. Quando a exclusão reversível não está habilitada para o Key Vault do Azure, essa operação exclui permanentemente o segredo.

DeleteSecretOperation operation = client.StartDeleteSecret("secret-name");

DeletedSecret secret = operation.Value;
Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

Excluir e limpar um segredo

Você precisará aguardar a conclusão da operação de longa duração antes de tentar limpar ou recuperar o segredo. Você pode fazer isso chamando UpdateStatus em um loop, conforme mostrado abaixo:

DeleteSecretOperation operation = client.StartDeleteSecret("secret-name");

// You only need to wait for completion if you want to purge or recover the secret.
// You should call `UpdateStatus` in another thread or after doing additional work like pumping messages.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedSecret secret = operation.Value;
client.PurgeDeletedSecret(secret.Name);

Listar segredos

Este exemplo lista todos os segredos no Key Vault do Azure especificado. O valor não é retornado ao listar todos os segredos. Você precisará chamar SecretClient.GetSecret para recuperar o valor.

Pageable<SecretProperties> allSecrets = client.GetPropertiesOfSecrets();

foreach (SecretProperties secretProperties in allSecrets)
{
    Console.WriteLine(secretProperties.Name);
}

Criar um segredo de forma assíncrona

As APIs assíncronas são idênticas aos seus equivalentes síncronos, mas retornam com o sufixo "Assíncrono" típico para métodos assíncronos e retornam um Task.

Este exemplo cria um segredo no Key Vault do Azure com os argumentos opcionais especificados.

KeyVaultSecret secret = await client.SetSecretAsync("secret-name", "secret-value");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

Listar segredos de forma assíncrona

A listagem de segredos não depende da espera do GetPropertiesOfSecretsAsync método, mas retorna um AsyncPageable<SecretProperties> que você pode usar com a await foreach instrução :

AsyncPageable<SecretProperties> allSecrets = client.GetPropertiesOfSecretsAsync();

await foreach (SecretProperties secretProperties in allSecrets)
{
    Console.WriteLine(secretProperties.Name);
}

Excluir um segredo de forma assíncrona

Ao excluir um segredo de forma assíncrona antes de purgá-lo, você pode aguardar o WaitForCompletionAsync método na operação. Por padrão, isso faz loops indefinidamente, mas você pode cancelá-lo passando um CancellationToken.

DeleteSecretOperation operation = await client.StartDeleteSecretAsync("secret-name");

// You only need to wait for completion if you want to purge or recover the secret.
await operation.WaitForCompletionAsync();

DeletedSecret secret = operation.Value;
await client.PurgeDeletedSecretAsync(secret.Name);

Solução de problemas

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

Geral

Quando você interage com a biblioteca de clientes secreta do Azure Key Vault usando o SDK do .NET, os erros retornados pelo serviço correspondem aos mesmos códigos de status HTTP retornados para solicitações da API REST.

Por exemplo, se você tentar recuperar um segredo que não existe no Key Vault do Azure, um 404 erro será retornado, indicando Not Found.

try
{
    KeyVaultSecret secret = client.GetSecret("some_secret");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Você observará que informações adicionais são registradas, como a ID de Solicitação do Cliente da operação.

Message:
    Azure.RequestFailedException : Service request failed.
    Status: 404 (Not Found)
Content:
    {"error":{"code":"SecretNotFound","message":"Secret not found: some_secret"}}

Headers:
    Cache-Control: no-cache
    Pragma: no-cache
    Server: Microsoft-IIS/10.0
    x-ms-keyvault-region: westus
    x-ms-request-id: 625f870e-10ea-41e5-8380-282e5cf768f2
    x-ms-keyvault-service-version: 1.1.0.866
    x-ms-keyvault-network-info: addr=131.107.174.199;act_addr_fam=InterNetwork;
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Strict-Transport-Security: max-age=31536000;includeSubDomains
    X-Content-Type-Options: nosniff
    Date: Tue, 18 Jun 2019 16:02:11 GMT
    Content-Length: 75
    Content-Type: application/json; charset=utf-8
    Expires: -1

Próximas etapas

Vários exemplos de biblioteca de clientes de segredos Key Vault do Azure estão disponíveis para você neste repositório GitHub. Esses exemplos fornecem código de exemplo para cenários adicionais comumente encontrados ao trabalhar com o Azure Key Vault:

  • Sample1_HelloWorld.md – para trabalhar com Key Vault do Azure, incluindo:

    • Criar um segredo
    • Obter um segredo existente
    • Atualizar um segredo existente
    • Excluir segredo

  • Sample2_BackupAndRestore.md – contém os snippets de código que funcionam com segredos Key Vault do Azure, incluindo:

    • Fazer backup e recuperar um segredo

  • Sample3_GetSecrets.md – código de exemplo para trabalhar com segredos Key Vault do Azure, incluindo:

    • Criar segredos
    • Listar todos os segredos no Key Vault
    • Atualizar segredos no Key Vault
    • Listar versões de um segredo especificado
    • Excluir segredos do Key Vault
    • Listar segredos excluídos no Key Vault

Documentação Adicional

Participante

Consulte o CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essas bibliotecas.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões