Biblioteca cliente de certificados de Azure Key Vault para .NET, versión 4.5.1

  • Artículo

Azure Key Vault es un servicio en la nube que proporciona almacenamiento seguro y administración automatizada de certificados usados en una aplicación en la nube. Se pueden conservar varios certificados y varias versiones del mismo certificado en azure Key Vault. Cada certificado del almacén tiene una directiva asociada que controla la emisión y duración del certificado, junto con las acciones que se deben realizar a medida que los certificados están a punto de expirar.

La biblioteca cliente de certificados de Azure Key Vault permite administrar certificados mediante programación, ofrecer métodos para crear, actualizar, enumerar y eliminar certificados, directivas, emisores y contactos. La biblioteca también admite la administración de operaciones de certificados pendientes y la administración de certificados eliminados.

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 certificados de Azure Key Vault para .NET con NuGet:

dotnet add package Azure.Security.KeyVault.Certificates

Prerrequisitos

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 CertificateClient. 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

Creación de CertificateClient

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 certificate 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 CertificateClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

Conceptos clave

KeyVaultCertificate

Un KeyVaultCertificate es el recurso fundamental dentro de Azure Key Vault. Usará certificados para cifrar y comprobar los datos cifrados o firmados.

CertificateClient

Con un CertificateClient puede obtener certificados del almacén, crear nuevos certificados y nuevas versiones de certificados existentes, actualizar metadatos de certificado y eliminar certificados. También puede administrar emisores de certificados, contactos y directivas de administración de certificados. Esto se muestra en los ejemplos siguientes.

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.Certificates admite API sincrónicas y asincrónicas.

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

Ejemplos de sincronización

Ejemplos asincrónicos

Crear un certificado

StartCreateCertificatecrea un certificado que se va a almacenar en azure Key Vault. Si ya existe un certificado con el mismo nombre, se crea una nueva versión del certificado. Al crear el certificado, el usuario puede especificar la directiva que controla la duración del certificado. Si no se especifica ninguna directiva, se usará la directiva predeterminada. La StartCreateCertificate operación devuelve un CertificateOperation. En el ejemplo siguiente se crea un certificado autofirmado con la directiva predeterminada.

// Create a certificate. This starts a long running operation to create and sign the certificate.
CertificateOperation operation = client.StartCreateCertificate("MyCertificate", CertificatePolicy.Default);

// You can await the completion of the create certificate operation.
// You should run UpdateStatus in another thread or do other work like pumping messages between calls.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

KeyVaultCertificateWithPolicy certificate = operation.Value;

NOTA: En función de los métodos de validación y emisor de certificados, la creación y la firma de certificados pueden tardar una cantidad de tiempo indeterminada. Los usuarios solo deben esperar a las operaciones de certificado cuando la operación se pueda completar razonablemente en el ámbito de la aplicación, como con certificados autofirmados o emisores con tiempos de respuesta conocidos.

Recuperación de un certificado

GetCertificaterecupera la versión más reciente de un certificado almacenado en azure Key Vault junto con su CertificatePolicy.

KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("MyCertificate");

GetCertificateVersion recupera una versión específica de un certificado en el almacén.

KeyVaultCertificate certificate = client.GetCertificateVersion(certificateWithPolicy.Name, certificateWithPolicy.Properties.Version);

Actualización de un certificado existente

UpdateCertificateactualiza un certificado almacenado en azure Key Vault.

CertificateProperties certificateProperties = new CertificateProperties(certificate.Id);
certificateProperties.Tags["key1"] = "value1";

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

Enumeración de certificados

GetCertificates enumera los certificados en el almacén y devuelve las propiedades de selección del certificado. No se devolverán campos confidenciales del certificado. Esta operación requiere el permiso certificates/list.

Pageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificates();

foreach (CertificateProperties certificateProperties in allCertificates)
{
    Console.WriteLine(certificateProperties.Name);
}

Eliminación de un certificado

DeleteCertificateelimina todas las versiones de un certificado almacenado en azure Key Vault. Cuando la eliminación temporal no está habilitada para azure Key Vault, esta operación elimina permanentemente el certificado. Si la eliminación temporal está habilitada, el certificado se marca para su eliminación y se puede purgar o recuperar opcionalmente hasta su fecha de purga programada.

DeleteCertificateOperation operation = client.StartDeleteCertificate("MyCertificate");

// You only need to wait for completion if you want to purge or recover the certificate.
// You should call `UpdateStatus` in another thread or after doing additional work like pumping messages.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedCertificate certificate = operation.Value;
client.PurgeDeletedCertificate(certificate.Name);

Creación de un certificado 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 certificado en azure Key Vault con los argumentos opcionales especificados.

// Create a certificate. This starts a long running operation to create and sign the certificate.
CertificateOperation operation = await client.StartCreateCertificateAsync("MyCertificate", CertificatePolicy.Default);

// You can await the completion of the create certificate operation.
KeyVaultCertificateWithPolicy certificate = await operation.WaitForCompletionAsync();

Enumerar certificados de forma asincrónica

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

AsyncPageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificatesAsync();

await foreach (CertificateProperties certificateProperties in allCertificates)
{
    Console.WriteLine(certificateProperties.Name);
}

Eliminar un certificado de forma asincrónica

Al eliminar un certificado 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.

DeleteCertificateOperation operation = await client.StartDeleteCertificateAsync("MyCertificate");

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

DeletedCertificate certificate = operation.Value;
await client.PurgeDeletedCertificateAsync(certificate.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 de certificados 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 una clave que no existe en la Key Vault de Azure, se devuelve un 404 error que indica Not Found.

try
{
    KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("SomeCertificate");
}
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":"CertificateNotFound","message":"Certificate not found: MyCertificate"}}

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 certificados 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 certificados de Azure Key Vault, entre los que se incluyen:

    • Crear un certificado
    • Obtención de un certificado existente
    • Actualización de un certificado existente
    • Eliminación de un certificado

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

    • Creación de certificados
    • Enumerar todos los certificados del Key Vault
    • Enumeración de versiones de un certificado especificado
    • Eliminación de certificados de la Key Vault
    • Enumeración de certificados eliminados en el Key Vault

Documentación adicional

Contribuir

Consulte la 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