Quickstart: Azure Key Vault certificate client library for.NET (SDK v4)Quickstart: Azure Key Vault certificate client library for .NET (SDK v4)

Começa com a biblioteca de clientes do Certificado Azure Key Vault para .NET.Get started with the Azure Key Vault certificate client library for .NET. Azure Key Vault é um serviço de nuvem que fornece uma loja segura para certificados.Azure Key Vault is a cloud service that provides a secure store for certificates. Pode armazenar chaves, palavras-passe, certificados e outros segredos em segurança.You can securely store keys, passwords, certificates, and other secrets. Os cofres de chaves do Azure podem ser criados e geridos através do portal do Azure.Azure key vaults may be created and managed through the Azure portal. Neste arranque rápido, aprende-se a criar, recuperar e apagar certificados de um cofre de chaves Azure utilizando a biblioteca de clientes .NETIn this quickstart, you learn how to create, retrieve, and delete certificates from an Azure key vault using the .NET client library

Recursos da biblioteca do cliente Key Vault:Key Vault client library resources:

Documentação de | referência da API Código fonte da biblioteca | Pacote (NuGet)API reference documentation | Library source code | Package (NuGet)

Para obter mais informações sobre o Cofre-Chave e certificados, consulte:For more information about Key Vault and certificates, see:

Pré-requisitosPrerequisites

Este quickstart está a usar dotnet e o Azure CLIThis quickstart is using dotnet and Azure CLI

ConfiguraçãoSetup

Este quickstart está a utilizar a biblioteca Azure Identity com o Azure CLI para autenticar o utilizador nos Serviços Azure.This quickstart is using Azure Identity library with Azure CLI to authenticate user to Azure Services. Os desenvolvedores também podem usar o Visual Studio ou Visual Studio Code para autenticar as suas chamadas, para obter mais informações, ver Autenticar o cliente com a biblioteca de clientes da Azure Identity.Developers can also use Visual Studio or Visual Studio Code to authenticate their calls, for more information, see Authenticate the client with Azure Identity client library.

Iniciar sessão no AzureSign in to Azure

  1. Execute o comando login.Run the login command.

    az login
    

    Se o CLI conseguir abrir o seu navegador predefinido, fá-lo-á e carregará uma página de inscrição do Azure.If the CLI can open your default browser, it will do so and load an Azure sign-in page.

    Caso contrário, abra uma página do navegador https://aka.ms/devicelogin e introduza o código de autorização exibido no seu terminal.Otherwise, open a browser page at https://aka.ms/devicelogin and enter the authorization code displayed in your terminal.

  2. Inicie sessão com as credenciais da sua conta no browser.Sign in with your account credentials in the browser.

Conceder acesso ao seu cofre chaveGrant access to your key vault

Crie uma política de acesso para o cofre-chave que concede permissões de certificados à sua conta de utilizadorCreate an access policy for your key vault that grants certificate permissions to your user account

az keyvault set-policy --name <your-key-vault-name> --upn user@domain.com --certificate-permissions delete get list create purge

Criar nova aplicação de consola .NETCreate new .NET console app

  1. Numa concha de comando, executar o seguinte comando para criar um projeto chamado key-vault-console-app :In a command shell, run the following command to create a project named key-vault-console-app:

    dotnet new console --name key-vault-console-app
    
  2. Mude para o recém-criado diretório de consola-consola-cofre-cofre, e executar o seguinte comando para construir o projeto:Change to the newly created key-vault-console-app directory, and run the following command to build the project:

    dotnet build
    

    A saída de construção não deve conter avisos ou erros.The build output should contain no warnings or errors.

    Build succeeded.
     0 Warning(s)
     0 Error(s)
    

Instalar as embalagensInstall the packages

A partir da concha de comando, instale a biblioteca do cliente certificado Azure Key Vault para .NET:From the command shell, install the Azure Key Vault certificate client library for .NET:

dotnet add package Azure.Security.KeyVault.Certificates

Para este arranque rápido, também terá de instalar a biblioteca de clientes Azure SDK para a Identidade Azure:For this quickstart, you'll also need to install the Azure SDK client library for Azure Identity:

dotnet add package Azure.Identity

Definir variáveis de ambienteSet environment variables

Esta aplicação está a usar o nome do cofre como uma variável ambiental chamada KEY_VAULT_NAME .This application is using key vault name as an environment variable called KEY_VAULT_NAME.

WindowsWindows

set KEY_VAULT_NAME=<your-key-vault-name>

Windows PowerShellWindows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

macOS ou LinuxmacOS or Linux

export KEY_VAULT_NAME=<your-key-vault-name>

Modelo de objetoObject model

A biblioteca de clientes do Certificado Azure Key Vault para .NET permite-lhe gerir certificados.The Azure Key Vault certificate client library for .NET allows you to manage certificates. A secção de exemplos de Código mostra como criar um cliente, definir um certificado, recuperar um certificado e apagar um certificado.The Code examples section shows how to create a client, set a certificate, retrieve a certificate, and delete a certificate.

Exemplos de códigoCode examples

Adicionar diretivasAdd directives

Adicione as seguintes diretivas ao topo de Program.cs:Add the following directives to the top of Program.cs:

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

Autenticar e criar um clienteAuthenticate and create a client

Neste arranque rápido, o utilizador com sessão é utilizado para autenticar o cofre de chaves, que é o método preferido para o desenvolvimento local.In this quickstart, logged in user is used to authenticate to key vault, which is preferred method for local development. Para aplicações implantadas no Azure, a identidade gerida deve ser atribuída ao Serviço de Aplicações ou Máquina Virtual, para obter mais informações, consulte a Visão Geral da Identidade Gerida.For applications deployed to Azure, managed identity should be assigned to App Service or Virtual Machine, for more information, see Managed Identity Overview.

Por exemplo, o nome do seu cofre-chave é expandido para o cofre uri chave, no formato "https:// <your-key-vault-name> .vault.azure.net".In below example, the name of your key vault is expanded to the key vault URI, in the format "https://<your-key-vault-name>.vault.azure.net". Este exemplo está a utilizar a classe 'DefaultAzureCredential)' da Azure Identity Library,que permite utilizar o mesmo código em diferentes ambientes com diferentes opções para fornecer identidade.This example is using 'DefaultAzureCredential()' class from Azure Identity Library, which allows to use the same code across different environments with different options to provide identity. Para obter mais informações sobre a autenticação no cofre da chave, consulte o Guia do Programador.For more information about authenticating to key vault, see Developer's Guide.

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

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

Guardar um certificadoSave a certificate

Neste exemplo, para simplificar, pode utilizar o certificado auto-assinado com a política de emissão por defeito.In this example, for simplicity you can use self-signed certificate with default issuance policy. Para esta tarefa, utilize o método StartCreateCertificateAsync.For this task, use the StartCreateCertificateAsync method. Os parâmetros do método aceitam um nome de certificado e a política de certificados.The method's parameters accepts a certificate name and the certificate policy.

var operation = await client.StartCreateCertificateAsync("myCertificate", CertificatePolicy.Default);
var certificate = await operation.WaitForCompletionAsync();

Nota

Se existir o nome do certificado, o código acima criará uma nova versão desse certificado.If certificate name exists, above code will create new version of that certificate.

Recuperar um certificadoRetrieve a certificate

Agora pode recuperar o certificado previamente criado com o método GetCertificateAsync.You can now retrieve the previously created certificate with the GetCertificateAsync method.

var certificate = await client.GetCertificateAsync("myCertificate");

Apagar um certificadoDelete a certificate

Finalmente, vamos apagar e limpar o certificado do seu cofre-chave com os métodos StartDeleteCertificateAsync e PurpurDeletedCertificateAsync.Finally, let's delete and purge the certificate from your key vault with the StartDeleteCertificateAsync and PurgeDeletedCertificateAsync methods.

var operation = await client.StartDeleteCertificateAsync("myCertificate");

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

var certificate = operation.Value;
await client.PurgeDeletedCertificateAsync("myCertificate");

Código de exemploSample code

Modifique a aplicação de consola .NET Core para interagir com o Cofre de Chaves, completando os seguintes passos:Modify the .NET Core console app to interact with the Key Vault by completing the following steps:

  • Substitua o código em Program.cs pelo seguinte código:Replace the code in Program.cs with the following code:

    using System;
    using System.Threading.Tasks;
    using Azure.Identity;
    using Azure.Security.KeyVault.Certificates;
    
    namespace key_vault_console_app
    {
        class Program
        {
            static async Task Main(string[] args)
            {
                const string certificateName = "myCertificate";
                var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
                var kvUri = $"https://{keyVaultName}.vault.azure.net";
    
                var client = new CertificateClient(new Uri(kvUri), new DefaultAzureCredential());
    
                Console.Write($"Creating a certificate in {keyVaultName} called '{certificateName}' ...");
                CertificateOperation operation = await client.StartCreateCertificateAsync(certificateName, CertificatePolicy.Default);
                await operation.WaitForCompletionAsync();
                Console.WriteLine(" done.");
    
                Console.WriteLine($"Retrieving your certificate from {keyVaultName}.");
                var certificate = await client.GetCertificateAsync(certificateName);
                Console.WriteLine($"Your certificate version is '{certificate.Value.Properties.Version}'.");
    
                Console.Write($"Deleting your certificate from {keyVaultName} ...");
                DeleteCertificateOperation deleteOperation = await client.StartDeleteCertificateAsync(certificateName);
                // You only need to wait for completion if you want to purge or recover the certificate.
                await deleteOperation.WaitForCompletionAsync();
                Console.WriteLine(" done.");
    
                Console.Write($"Purging your certificate from {keyVaultName} ...");
                await client.PurgeDeletedCertificateAsync(certificateName);
                Console.WriteLine(" done.");
            }
        }
    }
    

Testar e verificarTest and verify

Execute o seguinte comando para construir o projetoExecute the following command to build the project

dotnet build

É apresentada uma variação da seguinte saída:A variation of the following output appears:

Creating a certificate in mykeyvault called 'myCertificate' ... done.
Retrieving your certificate from mykeyvault.
Your certificate version is '8532359bced24e4bb2525f2d2050738a'.
Deleting your certificate from mykeyvault ... done
Purging your certificate from mykeyvault ... done

Passos seguintesNext steps

Neste quickstart, criou um cofre chave, guardou um certificado e recuperou o certificado.In this quickstart, you created a key vault, stored a certificate, and retrieved that certificate.

Para saber mais sobre o Key Vault e como integrá-lo com as suas apps, consulte os seguintes artigos:To learn more about Key Vault and how to integrate it with your apps, see the following articles: