Bibliothèque cliente secrète Azure Key Vault pour .NET - version 4.5.0

  • Article

Azure Key Vault est un service cloud qui fournit un stockage sécurisé des secrets, tels que des mots de passe et des chaînes de connexion de base de données.

La bibliothèque cliente azure Key Vault secrets vous permet de stocker et de contrôler en toute sécurité l’accès aux jetons, mots de passe, clés API et autres secrets. Cette bibliothèque offre des opérations pour créer, récupérer, mettre à jour, supprimer, vider, sauvegarder, restaurer et répertorier les secrets et leurs versions.

| 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 secrets pour .NET avec NuGet :

dotnet add package Azure.Security.KeyVault.Secrets

Prérequis

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 une instance de la classe SecretClient. Vous avez besoin d’une URL de coffre, que vous pouvez voir sous le nom « Nom DNS » dans le portail, et d’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, notamment aux 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

Instanciez un DefaultAzureCredential à transmettre au client. Les mêmes instance d’informations d’identification de jeton peuvent être utilisées avec plusieurs clients s’ils authentificationnt avec la même identité.

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

Concepts clés

KeyVaultSecret

A KeyVaultSecret est la ressource fondamentale dans Azure Key Vault. Du point de vue d’un développeur, les API Azure Key Vault acceptent et retournent des valeurs secrètes sous forme de chaînes.

SecretClient

Un SecretClient fournit des opérations synchrones et asynchrones dans le KIT de développement logiciel (SDK) permettant la sélection d’un client en fonction du cas d’usage d’une application. Une fois que vous avez initialisé un SecretClient, vous pouvez interagir avec des secrets dans Azure Key Vault.

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont sécurisées pour les threads et indépendantes les unes des autres (recommandations). 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 clientes | Accès à la réponse | Opérations de longue durée | Gestion des défaillances | Diagnostics | Moqueur | Durée de vie du client

Exemples

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

La section suivante fournit plusieurs extraits de code à l’aide de ce client qui a été créé ci-dessus, couvrant certaines des tâches les plus courantes liées au service secret Azure Key Vault :

Exemples de synchronisation

Exemples asynchrones

Créer un secret

SetSecretcrée un KeyVaultSecret à stocker dans azure Key Vault. Si un secret portant le même nom existe déjà, une nouvelle version du secret est créée.

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

Récupérer un secret

GetSecretrécupère un secret précédemment stocké dans azure Key Vault.

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

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

Mettre à jour un secret existant

UpdateSecretPropertiesmet à jour un secret précédemment stocké dans le Key Vault Azure. Seuls les attributs du secret sont mis à jour. Pour mettre à jour la valeur, appelez SecretClient.SetSecret un secret portant le même nom.

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

supprimer un secret

StartDeleteSecretdémarre une opération de longue durée pour supprimer un secret précédemment stocké dans le Key Vault Azure. Vous pouvez récupérer le secret immédiatement sans attendre la fin de l’opération. Lorsque la suppression réversible n’est pas activée pour azure Key Vault, cette opération supprime définitivement le secret.

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

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

Supprimer et vider un secret

Vous devrez attendre la fin de l’opération de longue durée avant d’essayer de vider ou de récupérer le secret. Pour ce faire, appelez UpdateStatus dans une boucle comme indiqué ci-dessous :

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

Afficher la liste des secrets

Cet exemple répertorie tous les secrets dans le Key Vault Azure spécifié. La valeur n’est pas retournée lors de la liste de tous les secrets. Vous devez appeler SecretClient.GetSecret pour récupérer la valeur.

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

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

Créer un secret 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 secret dans le Key Vault Azure avec les arguments facultatifs spécifiés.

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

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

Répertorier les secrets de manière asynchrone

La liste des secrets ne repose pas sur l’attente de la GetPropertiesOfSecretsAsync méthode, mais retourne un AsyncPageable<SecretProperties> que vous pouvez utiliser avec l’instruction await foreach :

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

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

Supprimer un secret de manière asynchrone

Lors de la suppression asynchrone d’un secret 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.

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

Résolution des problèmes

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 secrets 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 un secret qui n’existe pas dans votre Key Vault Azure, une 404 erreur est retournée, indiquant Not Found.

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

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

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

Étapes suivantes

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

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

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

  • Sample2_BackupAndRestore.md : contient les extraits de code travaillant avec les secrets Azure Key Vault, notamment :

    • Sauvegarder et récupérer un secret

  • Sample3_GetSecrets.md : exemple de code pour l’utilisation des secrets Azure Key Vault, notamment :

    • Créer des secrets
    • Répertorier tous les secrets dans le Key Vault
    • Mettre à jour les secrets dans le Key Vault
    • Répertorier les versions d’un secret spécifié
    • Supprimer des secrets du Key Vault
    • Répertorier les secrets supprimés dans le Key Vault

Documentation complémentaire

Contribution

Consultez le 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