Compartir vía

Inicio rápido: Biblioteca cliente de certificados de Azure Key Vault para .NET

  • Artículo

Empiece a trabajar con la biblioteca cliente de certificados de Azure Key Vault para .NET. Azure Key Vault es un servicio en la nube que proporciona un almacén seguro para los certificados. Puede almacenar de forma segura claves, contraseñas, certificados y otros secretos. Las instancias de Azure Key Vault se pueden crear y administrar a través de Azure Portal. En este inicio rápido, aprenderá a crear, recuperar y eliminar certificados de una instancia de Azure Key Vault mediante la biblioteca cliente de .NET.

Recursos de la biblioteca cliente de Key Vault:

Documentación de referencia de la API | Código fuente de la biblioteca | Paquete (NuGet)

Para más información sobre Key Vault y los certificados, consulte:

Requisitos previos

En este inicio rápido se usa dotnet y la CLI de Azure.

Configurar

En este inicio rápido se usa la biblioteca de identidades de Azure con la CLI de Azure para autenticar al usuario en los servicios de Azure. Los desarrolladores también pueden usar Visual Studio o Visual Studio Code para autenticar sus llamadas. Para más información, consulte Autenticación del cliente mediante la biblioteca cliente Azure Identity.

Inicio de sesión en Azure

  1. Ejecute el comando login.

    az login

    Si la CLI puede abrir el explorador predeterminado, lo hará y cargará una página de inicio de sesión de Azure.

    En caso contrario, abra una página del explorador en https://aka.ms/devicelogin y escriba el código de autorización que se muestra en el terminal.

  2. Inicie sesión con las credenciales de su cuenta en el explorador.

Concesión de acceso al almacén de claves

Para obtener permisos para el almacén de claves mediante Control de acceso basado en roles (RBAC), asigne un rol a su "Nombre principal de usuario" (UPN) mediante el comando de la CLI de Azure az role assignment create.

az role assignment create --role "Key Vault Certificate Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Reemplace <upn>, <subscription-id>, <resource-group-name> y <your-unique-keyvault-name> por los valores reales. El UPN normalmente tendrá el formato de una dirección de correo electrónico (por ejemplo, username@domain.com).

Creación de una aplicación de consola de .NET

  1. En un shell de comandos, ejecute el siguiente comando para crear un proyecto llamado key-vault-console-app:

    dotnet new console --name key-vault-console-app

  2. Cambie al directorio key-vault-console-app recién creado y ejecute el comando siguiente para compilar el proyecto:

    dotnet build

    La salida de la compilación no debe contener advertencias ni errores.

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

Instalación de los paquetes

En el shell de comandos, instale la biblioteca cliente de certificados de Azure Key Vault para .NET:

dotnet add package Azure.Security.KeyVault.Certificates

Para este inicio rápido también deberá instalar la biblioteca cliente de Azure Identity:

dotnet add package Azure.Identity

Establecimiento de variables de entorno

Esta aplicación obtiene el nombre del almacén de claves desde una variable de entorno llamada KEY_VAULT_NAME.

Windows

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

Windows PowerShell

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

macOS o Linux

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

Modelo de objetos

La biblioteca cliente de certificados de Azure Key Vault para .NET permite administrar los certificados. En la sección Ejemplos de código se muestra cómo crear un cliente y establecer, recuperar y eliminar un certificado.

Ejemplos de código

Adición de directivas

Agregue las directivas siguientes al principio de Program.cs:

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

Autenticación y creación de un cliente

Deben autorizarse las solicitudes de aplicación a la mayor parte de servicios de Azure. El uso de la clase DefaultAzureCredential que proporciona la biblioteca cliente de Azure Identity es el enfoque recomendado para implementar conexiones sin contraseña a los servicios de Azure en el código. DefaultAzureCredential admite varios métodos de autenticación y determina el que se debe usar en tiempo de ejecución. Este enfoque permite que la aplicación use diferentes métodos de autenticación en distintos entornos (local frente a producción) sin implementar código específico del entorno.

En este inicio rápido, DefaultAzureCredential se autentica en el almacén de claves mediante las credenciales del usuario de desarrollo local que inició sesión en la CLI de Azure. Cuando la aplicación se implementa en Azure, el mismo código DefaultAzureCredential puede detectar y usar automáticamente una identidad administrada asignada a una instancia de App Service, máquina virtual u otros servicios. Para más información, consulte Introducción a la identidad administrada.

En este ejemplo, el nombre del almacén de claves se expande al identificador URI del almacén de claves, con el formato https://<your-key-vault-name>.vault.azure.net. Para más información sobre la autenticación en el almacén de claves, consulte la Guía del desarrollador.

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

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

Guardar certificado

En este ejemplo, para simplificar, puede usar un certificado autofirmado con la directiva de emisión predeterminada. Para esta tarea, use el método StartCreateCertificateAsync. Los parámetros del método aceptan un nombre de certificado y la directiva de certificados.

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

Nota:

Si el nombre del certificado existe, el código anterior creará una versión de ese certificado.

Recuperación de un certificado

Ahora puede recuperar el certificado creado anteriormente con el método GetCertificateAsync.

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

Eliminación de un certificado

Por último, vamos a eliminar y purgar el certificado desde el almacén de claves con los métodos StartDeleteCertificateAsync y PurgeDeletedCertificateAsync.

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 ejemplo

Modifique la aplicación de consola de .NET para interactuar con el almacén de claves; para ello, complete los pasos siguientes:

  • Reemplace el código de Program.cs por el código siguiente:

    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.");
        }
    }
}

Prueba y comprobación

Ejecute el siguiente comando para compilar el proyecto.

dotnet build

Aparece una variación del resultado siguiente:

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

Pasos siguientes

En este inicio rápido, ha creado un almacén de claves, ha almacenado un certificado y, posteriormente, lo ha recuperado.

Para más información sobre Key Vault y cómo integrarlo con las aplicaciones, consulte los artículos siguientes: