Partilhar via

Biblioteca de cliente secreta do Azure Key Vault para .NET – versão 4.5.0

  • Artigo

O Azure Key Vault é um serviço cloud que fornece um armazenamento seguro de segredos, como palavras-passe e cadeias de ligação de base de dados.

A biblioteca de cliente de segredos do Azure Key Vault permite-lhe armazenar e controlar de forma segura o acesso a tokens, palavras-passe, chaves de API e outros segredos. Esta biblioteca oferece operações para criar, obter, atualizar, eliminar, remover, fazer cópias de segurança, restaurar e listar os segredos e as respetivas versões.

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

Introdução

Instalar o pacote

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

dotnet add package Azure.Security.KeyVault.Secrets

Pré-requisitos

Se utilizar a CLI do Azure, substitua <your-resource-group-name> e <your-key-vault-name> pelos 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, terá de criar uma instância da classe SecretClient. Precisa de um URL do cofre, que poderá ver como "Nome DNS" no portal e credenciais para instanciar um objeto de cliente.

Os exemplos mostrados abaixo utilizam um DefaultAzureCredential, que é adequado para a maioria dos cenários, incluindo ambientes de desenvolvimento e produção locais. Além disso, recomendamos a utilização de uma identidade gerida para autenticação em ambientes de produção. Pode encontrar mais informações sobre as diferentes formas de autenticação e os tipos de credenciais correspondentes na documentação da Identidade do Azure .

Para utilizar o DefaultAzureCredential fornecedor mostrado abaixo ou outros fornecedores de credenciais fornecidos com o SDK do Azure, primeiro tem de instalar o pacote Azure.Identity:

dotnet add package Azure.Identity

Instanciar um DefaultAzureCredential para passar para o cliente. A mesma instância de uma credencial de token pode ser utilizada com vários clientes se estiverem a autenticar 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");

Conceitos-chave

KeyVaultSecret

A KeyVaultSecret é o recurso fundamental no Azure Key Vault. Do ponto de vista de um programador, as APIs do Azure Key Vault aceitam e devolvem valores secretos como cadeias.

SecretClient

A SecretClient fornece operações síncronas e assíncronas no SDK, permitindo a seleção de um cliente com base no caso de utilização de uma aplicação. Depois de inicializar um SecretClient, pode interagir com segredos no Azure Key Vault.

Segurança de threads

Garantimos que todos os métodos de instância de cliente são seguros para threads e independentes uns dos outros (orientação). Isto garante que a recomendação de reutilização de instâncias de cliente é sempre segura, mesmo entre threads.

Conceitos adicionais

Opções de | cliente Aceder à resposta | Operações de execução prolongada | Lidar com falhas | Diagnósticos | A gozar | Duração do cliente

Exemplos

O pacote Azure.Security.KeyVault.Secrets suporta APIs síncronas e assíncronas.

A secção seguinte fornece vários fragmentos de código com o client criado acima, abrangendo algumas das tarefas mais comuns relacionadas com o serviço secreto do Azure Key Vault:

Exemplos de sincronização

Exemplos assíncronos

Criar um segredo

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

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

Obter um segredo

GetSecretobtém um segredo anteriormente armazenado 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 anteriormente armazenado no Key Vault do Azure. Apenas os atributos do segredo são atualizados. Para atualizar o valor, chame SecretClient.SetSecret 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);

Eliminar um segredo

StartDeleteSecretinicia uma operação de execução prolongada para eliminar um segredo anteriormente armazenado no Key Vault do Azure. Pode obter o segredo imediatamente sem esperar que a operação seja concluída. Quando a eliminação recuperável não está ativada para o Azure Key Vault, esta operação elimina permanentemente o segredo.

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

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

Eliminar e remover um segredo

Terá de aguardar que a operação de execução prolongada seja concluída antes de tentar remover ou recuperar o segredo. Pode fazê-lo ao chamar UpdateStatus num ciclo, 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 na Key Vault do Azure especificada. O valor não é devolvido ao listar todos os segredos. Terá de chamar SecretClient.GetSecret para obter 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 às suas congéneres síncronas, mas devolvem com o sufixo "Assíncrono" típico para métodos assíncronos e devolvem um Task.

Este exemplo cria um segredo na 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 de aguardar o GetPropertiesOfSecretsAsync método, mas devolve uma AsyncPageable<SecretProperties> que pode utilizar com a await foreach instrução :

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

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

Eliminar um segredo de forma assíncrona

Ao eliminar um segredo de forma assíncrona antes de o remover, pode aguardar o WaitForCompletionAsync método na operação. Por predefinição, este ciclo é ciclo indefinidamente, mas pode cancelá-lo ao transmitir 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);

Resolução de problemas

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

Geral

Quando interage com a biblioteca de cliente secreta do Azure Key Vault com o SDK .NET, os erros devolvidos pelo serviço correspondem aos mesmos códigos de estado HTTP devolvidos para pedidos de API REST.

Por exemplo, se tentar obter um segredo que não existe no seu Key Vault do Azure, é devolvido um 404 erro que indica Not Found.

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

Irá reparar que são registadas informações adicionais, como o ID do Pedido de 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

Passos seguintes

Estão disponíveis vários exemplos de biblioteca de clientes de segredos do Azure Key Vault neste repositório do GitHub. Estes exemplos fornecem código de exemplo para cenários adicionais normalmente encontrados ao trabalhar com o Azure Key Vault:

  • Sample1_HelloWorld.md - para trabalhar com o Azure Key Vault, incluindo:

    • Criar um segredo
    • Obter um segredo existente
    • Atualizar um segredo existente
    • Eliminar segredo

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

    • Criar cópias de segurança e recuperar um segredo

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

    • Criar segredos
    • Listar todos os segredos no Key Vault
    • Atualizar segredos no Key Vault
    • Listar versões de um segredo especificado
    • Eliminar segredos do Key Vault
    • Listar segredos eliminados no Key Vault

Documentação Adicional

Contribuir

Veja o CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para estas bibliotecas.

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou o contacto opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Impressões