Bibliothèque de client Azure Key Vault Certificate pour .NET - version 4.5.1

  • Article

Azure Key Vault est un service cloud qui fournit un stockage sécurisé et une gestion automatisée des certificats utilisés dans une application cloud. Plusieurs certificats, et plusieurs versions du même certificat, peuvent être conservés dans le Key Vault Azure. Chaque certificat du coffre est associé à une stratégie qui contrôle l’émission et la durée de vie du certificat, ainsi que les actions à entreprendre en tant que certificats arrivant à expiration.

La bibliothèque de client Azure Key Vault certificats permet de gérer les certificats par programmation, en offrant des méthodes pour créer, mettre à jour, répertorier et supprimer des certificats, des stratégies, des émetteurs et des contacts. La bibliothèque prend également en charge la gestion des opérations de certificat en attente et la gestion des certificats supprimés.

| Code sourcePackage (NuGet) | Documentation de référence sur les | API | Documentation produitÉchantillons | Guide de migration

Prise en main

Installer le package

Installez la bibliothèque de client Azure Key Vault certificats pour .NET avec NuGet :

dotnet add package Azure.Security.KeyVault.Certificates

Prérequis

  • Un abonnement Azure.
  • Un Key Vault Azure existant. Si vous devez créer un Key Vault Azure, vous pouvez utiliser le portail Azure ou Azure CLI.
  • L’autorisation à un Key Vault Azure existant à l’aide du RBAC (recommandé) ou du contrôle d’accès.

Si vous utilisez Azure CLI, remplacez <your-resource-group-name> et <your-key-vault-name> par vos propres noms uniques :

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

Authentifier le client

Pour interagir avec le service Azure Key Vault, vous devez créer un instance de la classe CertificateClient. Vous avez besoin d’une URL de coffre, que vous pouvez voir sous la forme « Nom DNS » dans le portail, ainsi que des informations d’identification pour instancier un objet client.

Les exemples présentés ci-dessous utilisent un DefaultAzureCredential, qui convient à la plupart des scénarios, y compris les environnements de développement et de production locaux. En outre, nous vous recommandons d’utiliser une identité managée pour l’authentification dans les environnements de production. Vous trouverez plus d’informations sur les différentes méthodes d’authentification et leurs types d’informations d’identification correspondants dans la documentation Azure Identity .

Pour utiliser le DefaultAzureCredential fournisseur indiqué ci-dessous ou d’autres fournisseurs d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, vous devez d’abord installer le package Azure.Identity :

dotnet add package Azure.Identity

Créer CertificateClient

Instanciez un DefaultAzureCredential à passer au client. La même instance d’informations d’identification de jeton peut être utilisée avec plusieurs clients s’ils s’authentifient avec la même identité.

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

Concepts clés

KeyVaultCertificate

Un KeyVaultCertificate est la ressource fondamentale dans Azure Key Vault. Vous allez utiliser des certificats pour chiffrer et vérifier les données chiffrées ou signées.

CertificateClient

Avec un CertificateClient , vous pouvez obtenir des certificats à partir du coffre, créer de nouveaux certificats et de nouvelles versions de certificats existants, mettre à jour les métadonnées de certificat et supprimer des certificats. Vous pouvez également gérer les émetteurs de certificats, les contacts et les stratégies de gestion des certificats. Cela est illustré dans les exemples ci-dessous.

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont thread-safe et indépendantes les unes des autres (instructions). Cela garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Options | du client Accès à la réponse | Opérations | de longue duréeGestion des défaillances | Diagnostics | Moqueur | Durée de vie du client

Exemples

Le package Azure.Security.KeyVault.Certificates prend en charge les API synchrones et asynchrones.

La section suivante fournit plusieurs extraits de code utilisant le clientcréé ci-dessus, couvrant certaines des tâches les plus courantes liées au service de certificat Azure Key Vault :

Exemples de synchronisation

Exemples asynchrones

Créer un certificat

StartCreateCertificatecrée un certificat à stocker dans le Key Vault Azure. Si un certificat portant le même nom existe déjà, une nouvelle version du certificat est créée. Lors de la création du certificat, l’utilisateur peut spécifier la stratégie qui contrôle la durée de vie du certificat. Si aucune stratégie n’est spécifiée, la stratégie par défaut est utilisée. L’opération StartCreateCertificate retourne un CertificateOperation. L’exemple suivant crée un certificat auto-signé avec la stratégie par défaut.

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

REMARQUE : Selon l’émetteur du certificat et les méthodes de validation, la création et la signature du certificat peuvent prendre un temps indéterminé. Les utilisateurs ne doivent attendre les opérations de certificat que lorsque l’opération peut être raisonnablement terminée dans l’étendue de l’application, par exemple avec des certificats auto-signés ou des émetteurs avec des temps de réponse bien connus.

Récupérer un certificat

GetCertificaterécupère la dernière version d’un certificat stocké dans le Key Vault Azure avec son CertificatePolicy.

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

GetCertificateVersion récupère une version spécifique d’un certificat dans le coffre.

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

Mettre à jour un certificat existant

UpdateCertificatemet à jour un certificat stocké dans le Key Vault Azure.

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

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

Afficher la liste des certificats

GetCertificates énumère les certificats dans le coffre, en retournant les propriétés de sélection du certificat. Les champs sensibles du certificat ne seront pas retournés. Cette opération nécessite l’autorisation certificats/liste.

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

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

Supprimer un certificat

DeleteCertificatesupprime toutes les versions d’un certificat stocké dans le Key Vault Azure. Lorsque la suppression réversible n’est pas activée pour azure Key Vault, cette opération supprime définitivement le certificat. Si la suppression réversible est activée, le certificat est marqué pour suppression et peut éventuellement être vidé ou récupéré jusqu’à sa date de vidage planifiée.

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

Créer un certificat de manière asynchrone

Les API asynchrones sont identiques à leurs équivalents synchrones, mais retournent avec le suffixe « Async » classique pour les méthodes asynchrones et retournent un Task.

Cet exemple crée un certificat dans le Key Vault Azure avec les arguments facultatifs spécifiés.

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

Répertorier les certificats de manière asynchrone

Le certificat de liste ne repose pas sur l’attente de la GetPropertiesOfCertificatesAsync méthode, mais retourne un AsyncPageable<CertificateProperties> que vous pouvez utiliser avec l’instruction await foreach :

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

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

Supprimer un certificat de façon asynchrone

Lors de la suppression asynchrone d’un certificat avant de le vider, vous pouvez attendre la WaitForCompletionAsync méthode sur l’opération. Par défaut, cette boucle s’exécute indéfiniment, mais vous pouvez l’annuler en passant 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);

Dépannage

Consultez notre guide de résolution des problèmes pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

Général

Lorsque vous interagissez avec la bibliothèque cliente de certificats Azure Key Vault à l’aide du Kit de développement logiciel (SDK) .NET, les erreurs retournées par le service correspondent aux mêmes codes de status HTTP retournés pour les demandes d’API REST.

Par exemple, si vous essayez de récupérer une clé qui n’existe pas dans votre Key Vault Azure, une 404 erreur est retournée, indiquant Not Found.

try
{
    KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("SomeCertificate");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Vous remarquerez que des informations supplémentaires sont consignées, comme l’ID de demande client de l’opération.

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

Étapes suivantes

Plusieurs exemples de bibliothèque cliente de certificats Azure Key Vault sont disponibles dans ce dépôt GitHub. Ces exemples fournissent un exemple de code pour des scénarios supplémentaires couramment rencontrés lors de l’utilisation d’Azure Key Vault :

  • Sample1_HelloWorld.md : pour utiliser des certificats Azure Key Vault, notamment :

    • Créer un certificat
    • Obtenir un certificat existant
    • Mettre à jour un certificat existant
    • Supprimer un certificat

  • Sample2_GetCertificates.md : exemple de code permettant d’utiliser des certificats Azure Key Vault, notamment :

    • Créer des certificats
    • Répertorier tous les certificats dans le Key Vault
    • Répertorier les versions d’un certificat spécifié
    • Supprimer des certificats du Key Vault
    • Répertorier les certificats supprimés dans le Key Vault

Documentation complémentaire

Contribution

Consultez la CONTRIBUTING.md pour plus d’informations sur la création, le test et la contribution à ces bibliothèques.

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions