Compartir vía

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

  • Artículo

Introducción a la biblioteca cliente de secretos de Azure Key Vault para .NET. Azure Key Vault es un servicio en la nube que ofrece el almacenamiento seguro de los secretos. 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 secretos 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 secretos, consulte:

Requisitos previos

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

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 az 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 Secrets 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 secretos de Azure Key Vault para .NET:

dotnet add package Azure.Security.KeyVault.Secrets

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 también usa el nombre del almacén de claves como 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 secretos de Azure Key Vault para .NET permite administrar los secretos. En la sección Ejemplos de código se muestra cómo crear un cliente y cómo establecer, recuperar y eliminar un secreto.

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

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 SecretClient(new Uri(kvUri), new DefaultAzureCredential());

Almacenamiento de un secreto

Ahora que la aplicación de consola se ha autenticado, agregue un secreto al almacén de claves. Para esta tarea, use el método SetSecretAsync.

El primer parámetro del método acepta un nombre para el secreto. En este ejemplo, la variable secretName almacena la cadena "mySecret".

El segundo parámetro del método acepta un valor para el secreto. En este ejemplo, el usuario introduce el secreto a través de la línea de comandos y lo almacena en la variable secretValue.

await client.SetSecretAsync(secretName, secretValue);

Nota:

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

Recuperación de un secreto

El valor establecido previamente ahora se puede recuperar con el método GetSecretAsync.

var secret = await client.GetSecretAsync(secretName);

El secreto se guarda ahora como secret.Value.

Eliminación de un secreto

Por último, se va a eliminar el secreto del almacén de claves con los métodos StartDeleteSecretAsync y 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 ejemplo

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

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

Prueba y comprobación

  1. Ejecute el siguiente comando para ejecutar la aplicación.

    dotnet run

  2. Cuando se le pida, escriba un secreto. Por ejemplo, mySecretPassword.

Aparece una variación del resultado siguiente:

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.

Pasos siguientes

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