Biblioteca cliente secreta de Azure Key Vault para .NET: versión 4.5.0

  • Artículo

Azure Key Vault es un servicio en la nube que proporciona un almacenamiento seguro de secretos, como contraseñas y cadenas de conexión de base de datos.

La biblioteca cliente de secretos de Azure Key Vault permite almacenar y controlar de forma segura el acceso a tokens, contraseñas, claves de API y otros secretos. Esta biblioteca ofrece operaciones para crear, recuperar, actualizar, eliminar, purgar, realizar copias de seguridad, restaurar y enumerar los secretos y sus versiones.

Código | fuente Paquete (NuGet) | Documentación | de referencia de API | Documentación del productoMuestras | Guía de migración

Introducción

Instalar el paquete

Instale la biblioteca cliente de secretos de Azure Key Vault para .NET con NuGet:

dotnet add package Azure.Security.KeyVault.Secrets

Prerequisites

Si usa la CLI de Azure, reemplace <your-resource-group-name> y <your-key-vault-name> por sus propios nombres únicos:

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

Autenticar el cliente

Para interactuar con el servicio azure Key Vault, deberá crear una instancia de la clase SecretClient. Necesita una dirección URL del almacén, que puede ver como "Nombre DNS" en el portal y credenciales para crear instancias de un objeto de cliente.

Los ejemplos que se muestran a continuación usan , DefaultAzureCredentialque es adecuado para la mayoría de los escenarios, incluidos los entornos de desarrollo y producción locales. Además, se recomienda usar una identidad administrada para la autenticación en entornos de producción. Puede encontrar más información sobre las distintas formas de autenticación y sus tipos de credenciales correspondientes en la documentación de Azure Identity .

Para usar el DefaultAzureCredential proveedor que se muestra a continuación u otros proveedores de credenciales proporcionados con el SDK de Azure, primero debe instalar el paquete Azure.Identity:

dotnet add package Azure.Identity

Cree una instancia de para DefaultAzureCredential pasar al cliente. La misma instancia de una credencial de token se puede usar con varios clientes si se autenticarán con la misma identidad.

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

Conceptos clave

KeyVaultSecret

Un KeyVaultSecret es el recurso fundamental dentro de Azure Key Vault. Desde la perspectiva de un desarrollador, las API de Azure Key Vault aceptan y devuelven valores secretos como cadenas.

SecretClient

A SecretClient proporciona operaciones sincrónicas y asincrónicas en el SDK que permiten seleccionar un cliente en función del caso de uso de una aplicación. Una vez que haya inicializado un SecretClient, puede interactuar con secretos en Azure Key Vault.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente son seguros para subprocesos e independientes entre sí (instrucciones). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Opciones | de cliente Acceso a la respuesta | Operaciones | de larga duraciónControl de errores | Diagnóstico | Burla | Duración del cliente

Ejemplos

El paquete Azure.Security.KeyVault.Secrets admite API sincrónicas y asincrónicas.

En la sección siguiente se proporcionan varios fragmentos de código con el client creado anteriormente, que abarcan algunas de las tareas relacionadas con el servicio secreto de Azure Key Vault más comunes:

Ejemplos de sincronización

Ejemplos asincrónicos

Crear un secreto

SetSecretcrea un objeto KeyVaultSecret que se va a almacenar en la Key Vault de Azure. Si ya existe un secreto con el mismo nombre, se crea una nueva versión del secreto.

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

Recuperación de un secreto

GetSecretrecupera un secreto almacenado previamente en la Key Vault de Azure.

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

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

Actualizar un secreto existente

UpdateSecretPropertiesactualiza un secreto previamente almacenado en azure Key Vault. Solo se actualizan los atributos del secreto. Para actualizar el valor, llame a SecretClient.SetSecret en un secreto con el mismo nombre.

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 un secreto

StartDeleteSecretinicia una operación de ejecución prolongada para eliminar un secreto previamente almacenado en azure Key Vault. Puede recuperar el secreto inmediatamente sin esperar a que se complete la operación. Cuando la eliminación temporal no está habilitada para azure Key Vault, esta operación elimina permanentemente el secreto.

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

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

Eliminar y purgar un secreto

Tendrá que esperar a que se complete la operación de larga duración antes de intentar purgar o recuperar el secreto. Para ello, llame a UpdateStatus en un bucle, como se muestra a continuación:

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

Enumeración de secretos

En este ejemplo se enumeran todos los secretos de la Key Vault de Azure especificada. El valor no se devuelve al enumerar todos los secretos. Deberá llamar SecretClient.GetSecret a para recuperar el valor.

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

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

Creación de un secreto de forma asincrónica

Las API asincrónicas son idénticas a sus homólogos sincrónicos, pero devuelven con el sufijo "asincrónico" típico para los métodos asincrónicos y devuelven .Task

En este ejemplo se crea un secreto en azure Key Vault con los argumentos opcionales especificados.

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

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

Enumeración de secretos de forma asincrónica

Enumerar secretos no se basa en esperar el GetPropertiesOfSecretsAsync método , pero devuelve un AsyncPageable<SecretProperties> valor que puede usar con la await foreach instrucción :

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

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

Eliminar un secreto de forma asincrónica

Al eliminar un secreto de forma asincrónica antes de purgarlo, puede esperar al WaitForCompletionAsync método en la operación. De forma predeterminada, este bucle se realiza indefinidamente, pero puede cancelarlo pasando un 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);

Solución de problemas

Consulte nuestra guía de solución de problemas para obtener más información sobre cómo diagnosticar varios escenarios de error.

General

Al interactuar con la biblioteca cliente secreta de Azure Key Vault mediante el SDK de .NET, los errores devueltos por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de la API REST.

Por ejemplo, si intenta recuperar un secreto que no existe en azure Key Vault, se devuelve un 404 error que indica Not Found.

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

Observará que se registra información adicional, como el identificador de solicitud de cliente de la operación.

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

Pasos siguientes

Hay varios ejemplos de biblioteca cliente de secretos de Azure Key Vault disponibles en este repositorio de GitHub. Estos ejemplos proporcionan código de ejemplo para escenarios adicionales que se suelen encontrar al trabajar con Azure Key Vault:

  • Sample1_HelloWorld.md: para trabajar con Azure Key Vault, entre los que se incluyen:

    • Crear un secreto
    • Obtención de un secreto existente
    • Actualizar un secreto existente
    • Eliminar un secreto

  • Sample2_BackupAndRestore.md: contiene los fragmentos de código que funcionan con secretos de Azure Key Vault, entre los que se incluyen:

    • Copia de seguridad y recuperación de un secreto

  • Sample3_GetSecrets.md: código de ejemplo para trabajar con secretos de Azure Key Vault, entre los que se incluyen:

    • Crear secretos
    • Enumeración de todos los secretos de la Key Vault
    • Actualización de secretos en el Key Vault
    • Enumeración de versiones de un secreto especificado
    • Eliminación de secretos del Key Vault
    • Enumeración de secretos eliminados en el Key Vault

Documentación adicional

Contribuir

Consulte el CONTRIBUTING.md para obtener más información sobre la compilación, las pruebas y la contribución a estas bibliotecas.

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones