Utiliser Azure Key Vault fournisseur de configuration dans ASP.NET Core

Cet article explique comment utiliser le fournisseur de configuration Azure Key Vault pour charger des valeurs de configuration d’application à partir de Key Vault secrets. Key Vault est un service cloud qui permet de protéger les clés de chiffrement et les secrets utilisés par les applications et les services. Les scénarios courants d’utilisation de Key Vault avec des applications ASP.NET Core sont les suivants :

• Contrôler l’accès aux données de configuration sensibles.
• Respect des exigences relatives aux modules de sécurité matérielle (HSM) validés FIPS 140-2 niveau 2 lors du stockage des données de configuration.

Packages

Ajoutez des références de package pour les packages suivants :

• Azure.Extensions.AspNetCore.Configuration.Secrets
• Azur.Identity

Exemple d’application

L’exemple d’application s’exécute dans l’un des deux modes déterminés par la #define directive de préprocesseur en haut du fichier Program.cs :

• Certificate : montre comment utiliser un id client Key Vault et un certificat X.509 pour accéder aux secrets stockés dans un key vault. Vous pouvez exécuter l’exemple à partir de n’importe quel emplacement, qu’il soit déployé sur Azure App Service ou sur n’importe quel hôte pouvant servir une application ASP.NET Core.

• Managed : illustre comment utiliser les identités gérées pour les ressources Azure. L’identité managée authentifie l’application pour Key Vault avec des identités managées pour Azure ressources sans stocker d’informations d’identification dans le code ou la configuration de l’application. La version Managed de l’exemple doit être déployée sur Azure. Suivez les instructions de la section Utilisation des identités gérées pour les ressources Azure.

Pour plus d’informations sur la configuration d’un exemple d’application à l’aide #definede , consultez les directives de préprocesseur dans l’exemple de code.

Afficher ou télécharger l’exemple de code (comment télécharger)

Stockage des secrets dans l’environnement de développement

Définissez les secrets localement à l’aide de l’outil Gestionnaire de secrets . Lorsque l’exemple d’application s’exécute sur l’ordinateur local dans l’environnement Development , les secrets sont chargés à partir du magasin de secrets utilisateur local.

Secret Manager nécessite une <UserSecretsId> propriété dans le fichier projet d’application. Définissez la valeur de la propriété ({GUID}) sur un GUID unique :

<PropertyGroup>
  <UserSecretsId>{GUID}</UserSecretsId>
</PropertyGroup>

Les secrets sont créés sous forme de paires nom-valeur. Les valeurs hiérarchiques (sections de configuration) utilisent les deux-points (:) comme séparateurs dans ASP.NET Core configuration noms de clés.

Secret Manager est utilisé dans un interpréteur de commandes (ou un terminal) ouvert à la racine de contenu du projet, où {SECRET NAME} est le nom et {SECRET VALUE} la valeur :

dotnet user-secrets set "{SECRET NAME}" "{SECRET VALUE}"

Exécutez les commandes suivantes dans un interpréteur de commandes à partir de la racine de contenu du projet. Les commandes définissent les secrets de l’exemple d’application :

dotnet user-secrets set "SecretName" "secret_value_1_dev"
dotnet user-secrets set "Section:SecretName" "secret_value_2_dev"

Lorsque ces secrets sont stockés dans Key Vault, comme décrit dans le stockage Secret dans l’environnement de production avec Key Vault section, le suffixe _dev change en _prod. Le suffixe fournit un indicateur visuel dans la sortie de l’application indiquant la source des valeurs de configuration.

Stockage secret dans l’environnement de production avec Key Vault

Créez un coffre de clés Azure et stockez les exemples de secrets d’application en effectuant les étapes suivantes. Pour plus d’informations, consultez Démarrage rapide : définir et récupérer un secret à partir de Key Vault avec Azure CLI.

1. Ouvrez Azure Cloud Shell à l’aide de l’une des méthodes suivantes dans le portail Azure :

   • Sélectionnez Essayer dans le coin supérieur droit d’un bloc de code. Utilisez la chaîne de recherche « Azure CLI » dans la zone de texte.
   • Ouvrez Cloud Shell dans votre navigateur à l’aide du bouton Lancer Cloud Shell.
   • Sélectionnez le bouton Cloud Shell dans le menu en haut à droite du portail Azure.

   Pour plus d’informations, consultez la documentation Azure CLI et Overview de Azure Cloud Shell.

2. Si vous n’êtes pas encore authentifié, connectez-vous à l’aide de la commande az login.

3. Créez un groupe de ressources avec la commande suivante, où {RESOURCE GROUP NAME} est le nom du nouveau groupe de ressources et {LOCATION} est la région Azure :

   az group create --name "{RESOURCE GROUP NAME}" --location {LOCATION}
   

4. Créez un coffre de clés Azure dans le groupe de ressources avec la commande suivante, où {KEY VAULT NAME} est le nom du nouveau coffre et {LOCATION} est la région Azure :

   az keyvault create --name {KEY VAULT NAME} --resource-group "{RESOURCE GROUP NAME}" --location {LOCATION}
   

5. Créez des secrets dans le coffre sous forme de paires nom-valeur.

   Les noms de secrets Key Vault peuvent contenir des caractères alphanumériques et des tirets (-). Les valeurs hiérarchiques (sections de configuration) utilisent deux tirets ou traits d’union (--) comme délimiteur. Le caractère « : » n'est pas autorisé dans les noms de secrets de Key Vault. Les deux-points délimitent une section d’une sous-clé dans la configuration ASP.NET Core. La séquence de deux tirets est remplacée par un deux-points lorsque les secrets sont chargés dans la configuration de l’application.

   Les secrets suivants sont destinés à être utilisés avec l’application exemple. Les valeurs incluent le suffixe _prod, qui les distingue des valeurs portant le suffixe _dev chargées dans l’environnement Development via Secret Manager. Remplacez {KEY VAULT NAME} par le nom du coffre de clés que vous avez créé précédemment :

   az keyvault secret set --vault-name {KEY VAULT NAME} --name "SecretName" --value "secret_value_1_prod"
   az keyvault secret set --vault-name {KEY VAULT NAME} --name "Section--SecretName" --value "secret_value_2_prod"
   

Utiliser l’ID d’application et le certificat X.509 pour les applications non hébergées sur Azure

Configurez Key Vault et l’application pour utiliser un ID d’application Microsoft Entra ID et un certificat X.509 pour s’authentifier auprès d’un coffre lorsque l’application est hébergée en dehors de Azure. Pour plus d’informations, consultez À propos des clés, des secrets et des certificats.

L’application exemple utilise un ID d’application et un certificat X.509 lorsque la directive de préprocesseur #define en haut du fichier Program.cs est définie sur Certificate.

1. Créez un certificat d’archive PKCS#12 (.pfx). Les options de création de certificats incluent New-SelfSignedCertificate sur Windows et OpenSSL.

2. Installez le certificat dans le magasin de certificats personnels de l’utilisateur actuel. Le marquage de la clé comme exportable est facultatif. Notez l’empreinte digitale du certificat, qui sera utilisée plus tard dans ce processus.

3. Exportez le certificat d’archive PKCS#12 (.pfx) en tant que certificat codé DER (.cer).

4. Enregistrez l’application avec Microsoft Entra ID (Inscriptions d’applications).

5. Chargez le certificat codé en DER (.cer) dans Microsoft Entra ID :

   1. Sélectionnez l’application dans Microsoft Entra ID.
   2. Accédez à Certificats et secrets.
   3. Sélectionnez Charger le certificat pour charger le certificat, qui contient la clé publique. Un certificat .cer, .pem ou .crt est acceptable.

6. Stockez le nom du coffre de clés, l’ID d’application et l’empreinte numérique du certificat dans le fichier appsettings.jsonde l’application .

7. Dans le portail Azure, accédez à Key Vaults.

8. Sélectionnez le coffre de clés que vous avez créé dans la section Stockage des secrets dans l’environnement de production avec Azure Key Vault.

9. Sélectionnez Stratégies d’accès, puis ajoutez une stratégie d’accès.

10. Ouvrez les permissions secrètes et accordez à l’application les permissions Obtenir et Lister.

11. Choisissez Sélectionner principal. Sélectionnez l’application inscrite par nom, puis sélectionnez Sélectionner.

12. Sélectionnez OK, puis sélectionnez Enregistrer.

13. Déployez l’application.

L’application exemple Certificate obtient ses valeurs de configuration à partir de IConfigurationRoot avec le même nom que le nom secret :

• Valeurs non hiérarchiques : la valeur de SecretName est obtenue avec config["SecretName"].
• Valeurs hiérarchiques (sections) : utilisez la notation deux-points (:) ou la GetSection méthode. Utilisez l’une des approches suivantes pour obtenir la valeur de configuration :
  • config["Section:SecretName"]
  • config.GetSection("Section")["SecretName"]

Le système d’exploitation gère le certificat X.509. L’application appelle la AddAzureKeyVault méthode avec des valeurs fournies par le fichier appsettings.json :

using System.Security.Cryptography.X509Certificates;
using Azure.Identity;

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsProduction())
{
    using var x509Store = new X509Store(StoreLocation.CurrentUser);

    x509Store.Open(OpenFlags.ReadOnly);

    var x509Certificate = x509Store.Certificates
        .Find(
            X509FindType.FindByThumbprint,
            builder.Configuration["AzureADCertThumbprint"],
            validOnly: false)
        .OfType<X509Certificate2>()
        .Single();

    builder.Configuration.AddAzureKeyVault(
        new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
        new ClientCertificateCredential(
            builder.Configuration["AzureADDirectoryId"],
            builder.Configuration["AzureADApplicationId"],
            x509Certificate));
}

var app = builder.Build();

Exemples de valeurs

• Nom du coffre de clés : contosovault
• ID application : 00001111-aaaa-2222-bbbb-3333cccc4444
• Empreinte digitale du certificat : fe14593dd66b2406c5269d742d04b6e1ab03adb1

Valeurs du fichier appsettings.json :

{
  "KeyVaultName": "Key Vault Name",
  "AzureADApplicationId": "Azure AD Application ID",
  "AzureADCertThumbprint": "Azure AD Certificate Thumbprint",
  "AzureADDirectoryId": "Azure AD Directory ID"
}

Lorsque vous exécutez l’application, une page Web affiche les valeurs secrètes chargées. Dans l’environnement Development , les valeurs secrètes se chargent avec le _dev suffixe. Dans l’environnement Production , les valeurs se chargent avec le _prod suffixe.

Utiliser des identités managées pour des ressources Azure

Une application déployée sur Azure peut tirer parti des identités gérées pour les ressources Azure. Une identité managée permet à l’application de s’authentifier avec Azure Key Vault à l’aide d’une authentification Microsoft Entra ID sans stocker d’informations d’identification dans le code ou la configuration de l’application.

L’application exemple utilise une identité managée attribuée par le système lorsque la directive de préprocesseur #define en haut du fichier Program.cs est définie sur Managed. Pour créer une identité managée pour une application Azure App Service, consultez Comment utiliser des identités managées pour App Service et Azure Functions. Une fois l’identité managée créée, notez l’ID d’objet de l’application affiché dans le portail Azure dans le panneau Identity de l’App Service.

Entrez le nom du coffre de clés dans le fichier appsettings.jsonde l’application . L’application exemple ne nécessite pas d’ID d’application ni de mot de passe (secret client) lorsqu’elle est définie sur la version Managed. Vous pouvez donc ignorer ces entrées de configuration. L’application est déployée sur Azure et Azure authentifie l’application pour accéder à Key Vault uniquement à l’aide du nom du coffre stocké dans le fichier appsettings.json.

Déployez l’application exemple sur Azure App Service.

À l'aide de l'Azure CLI et de l'ID d'objet de l'application, fournissez à l'application des autorisations list et get pour accéder au coffre de clés :

az keyvault set-policy --name {KEY VAULT NAME} --object-id {OBJECT ID} --secret-permissions get list

Redémarrez l’application à l’aide d’Azure CLI, d’Azure PowerShell ou du portail Azure.

L’application exemple crée une instance de la classe DefaultAzureCredential. Les informations d’identification tentent d’obtenir un jeton d’accès à partir de l’environnement pour les ressources Azure :

using Azure.Identity;

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsProduction())
{
    builder.Configuration.AddAzureKeyVault(
        new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
        new DefaultAzureCredential());
}

Exemple de nom pour le coffre de clés : contosovault

Valeur du nom dans le fichier appsettings.json :

{
  "KeyVaultName": "Key Vault Name"
}

Pour les applications qui utilisent une identité managée affectée par l’utilisateur, configurez l’ID client de l’identité managée à l’aide de l’une des approches suivantes :

• Définissez la variable d’environnement AZURE_CLIENT_ID.

• Définissez la propriété DefaultAzureCredentialOptions.ManagedIdentityClientId lors de l’appel de la méthode AddAzureKeyVault :

  builder.Configuration.AddAzureKeyVault(
      new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
      new DefaultAzureCredential(new DefaultAzureCredentialOptions
      {
          ManagedIdentityClientId = builder.Configuration["AzureADManagedIdentityClientId"]
      }));
  

Lorsque vous exécutez l’application, une page Web affiche les valeurs secrètes chargées. Dans l’environnement Development , les valeurs secrètes ont le _dev suffixe, car elles sont fournies par Secret Manager. Dans l’environnement Production , les valeurs sont chargées avec le _prod suffixe, car elles sont fournies par Azure Key Vault.

Si vous recevez une erreur Access denied, vérifiez que l’application est enregistrée dans Microsoft Entra ID et qu’elle a accès au coffre. Vérifiez que vous avez redémarré le service dans Azure.

Pour plus d’informations sur l’utilisation du fournisseur avec une identité managée et un Azure Pipelines, consultez Connect to Azure with an Azure Resource Manager service connection.

Options de configuration

La AddAzureKeyVault méthode peut accepter un AzureKeyVaultConfigurationOptions objet :

// using Azure.Extensions.AspNetCore.Configuration.Secrets;

builder.Configuration.AddAzureKeyVault(
    new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
    new DefaultAzureCredential(),
    new AzureKeyVaultConfigurationOptions
    {
        // ...
    });

L’objet AzureKeyVaultConfigurationOptions contient les propriétés suivantes :

Utilisez un préfixe de nom de clé

La méthode AddAzureKeyVault fournit une surcharge qui accepte une implémentation de KeyVaultSecretManager, ce qui vous permet de contrôler la façon dont les secrets Key Vault sont convertis en clés de configuration. Par exemple, vous pouvez implémenter l’interface pour charger les valeurs secrètes en fonction d’une valeur de préfixe que vous fournissez au démarrage de l’application. Cette technique vous permet, par exemple, de charger des secrets en fonction de la version de l’application.

Dans l'exemple suivant, un secret est établi dans Key Vault (à l'aide du Gestionnaire de secrets pour l'environnement Development) pour 5000-AppSecret (les périodes ne sont pas autorisées dans Key Vault noms de secrets). Ce secret représente un secret d’application pour la version 5.0.0.0 de l’application. Pour une autre version de l’application, 5.1.0.0, un secret est ajouté au même coffre de clés (à l’aide du Gestionnaire de secrets) pour 5100-AppSecret. Chaque version de l’application charge sa valeur de secret versionnée dans sa configuration en tant que AppSecret, en supprimant la version lors du chargement du secret.

La AddAzureKeyVault méthode est appelée avec une implémentation personnalisée KeyVaultSecretManager :

// using Azure.Extensions.AspNetCore.Configuration.Secrets;

builder.Configuration.AddAzureKeyVault(
    new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
    new DefaultAzureCredential(),
    new SamplePrefixKeyVaultSecretManager("5000"));

L’implémentation réagit aux préfixes de version des secrets pour charger le secret approprié dans la configuration :

• La Load méthode charge un secret quand son nom commence par le préfixe. Les autres secrets ne sont pas chargés.
• La méthode GetKey :
  • Supprime le préfixe du nom du secret.
  • Remplace deux tirets (--) dans n’importe quel nom par le KeyDelimiter. Ce délimiteur (généralement un signe deux-points :) est utilisé dans la configuration, car Key Vault n'autorise pas de signe deux-points (:) dans les noms de secrets.

public class SamplePrefixKeyVaultSecretManager : KeyVaultSecretManager
{
    private readonly string _prefix;

    public SamplePrefixKeyVaultSecretManager(string prefix)
        => _prefix = $"{prefix}-";

    public override bool Load(SecretProperties properties)
        => properties.Name.StartsWith(_prefix);

    public override string GetKey(KeyVaultSecret secret)
        => secret.Name[_prefix.Length..].Replace("--", ConfigurationPath.KeyDelimiter);
}

Un algorithme de fournisseur appelle la méthode Load et parcourt les secrets du coffre de clés pour trouver les secrets dont le nom est préfixé par la version. Lorsqu’un préfixe de version est trouvé avec Load, l’algorithme utilise la méthode GetKey pour renvoyer le nom de configuration du nom du secret. Il supprime le préfixe de version du nom du secret. Le reste du nom du secret est renvoyé pour être chargé dans les paires nom-valeur de la configuration de l’application.

Lorsque vous implémentez cette approche, procédez comme suit :

1. Spécifiez la version de l’application dans le fichier projet d’application. Dans l’exemple suivant, la version de l’application est définie sur 5.0.0.0:

   <PropertyGroup>
     <Version>5.0.0.0</Version>
   </PropertyGroup>
   

2. Vérifiez que la <UserSecretsId> propriété est définie dans le fichier projet d’application, où {GUID} est un GUID fourni par l’utilisateur :

   <PropertyGroup>
     <UserSecretsId>{GUID}</UserSecretsId>
   </PropertyGroup>
   

   Enregistrez les secrets suivants localement à l’aide du Gestionnaire de secrets :

   dotnet user-secrets set "5000-AppSecret" "5.0.0.0_secret_value_dev"
   dotnet user-secrets set "5100-AppSecret" "5.1.0.0_secret_value_dev"
   

3. Enregistrez les secrets dans Azure Key Vault à l’aide des commandes Azure CLI suivantes :

   az keyvault secret set --vault-name {KEY VAULT NAME} --name "5000-AppSecret" --value "5.0.0.0_secret_value_prod"
   az keyvault secret set --vault-name {KEY VAULT NAME} --name "5100-AppSecret" --value "5.1.0.0_secret_value_prod"
   

Le processus effectue les tâches suivantes :

• Lorsque l’application s’exécute, l’implémentation charge les secrets du coffre de clés. La chaîne secrète pour 5000-AppSecret correspond à la version de l’application spécifiée dans le fichier de projet de l’application (5.0.0.0).

• La version, 5000 (avec le tiret), est supprimée du nom de la clé. Dans toute l’application, la lecture de la configuration avec la clé AppSecret charge la valeur secrète.

• Si la version de l’application est modifiée dans le fichier projet 5.1.0.0 et que l’application est réexécutée, la valeur secrète renvoyée est 5.1.0.0_secret_value_dev dans l’environnement Development et 5.1.0.0_secret_value_prod dans Production.

Lier un tableau à une classe

Le fournisseur peut lire les valeurs de configuration dans un tableau pour les lier à un tableau POCO.

Lors de la lecture à partir d’une source de configuration qui autorise les séparateurs deux-points (:) dans les clés, un segment de clé numérique est utilisé pour distinguer les clés qui composent un tableau (:0:, :1:, … :{n}:). Pour plus d’informations, consultez Configuration : lier un tableau à une classe.

Key Vault clés ne peuvent pas utiliser de signe deux-points (:) comme séparateur. L’approche décrite dans cet article utilise des doubles tirets (--) comme séparateur pour les valeurs hiérarchiques (sections). Les clés d’un tableau sont stockées dans Key Vault avec des tirets doubles et des segments numériques de clé (--0--, --1--, … --{n}--).

Examinez la configuration suivante du fournisseur de journalisation Serilog fournie dans un fichier JSON. Deux littéraux d’objet sont définis dans le tableau WriteTo qui reflètent deux récepteurs Serilog, qui décrivent les destinations pour la sortie de journalisation :

"Serilog": {
  "WriteTo": [
    {
      "Name": "AzureTableStorage",
      "Args": {
        "storageTableName": "logs",
        "connectionString": "DefaultEnd...ountKey=Eby8...GMGw=="
      }
    },
    {
      "Name": "AzureDocumentDB",
      "Args": {
        "endpointUrl": "https://contoso.documents.azure.com:443",
        "authorizationKey": "Eby8...GMGw=="
      }
    }
  ]
}

La configuration dans le fichier JSON est stockée dans Key Vault à l’aide de la notation double tiret (--) et des segments numériques :

Recharger les secrets

Par défaut, le fournisseur de configuration met en cache les secrets pour la durée de vie de l’application. L’application ignore les secrets désactivés ou mis à jour ultérieurement dans le Key Vault.

Pour recharger les secrets, appelez la méthode IConfigurationRoot.Reload :

config.Reload();

Pour recharger les secrets périodiquement, à un intervalle spécifié, définissez la propriété AzureKeyVaultConfigurationOptions.ReloadInterval. Pour plus d’informations, consultez Options de configuration.

Secrets désactivés et expirés

Les secrets expirés sont inclus par défaut dans le fournisseur de configuration. Pour exclure les valeurs de ces secrets dans la configuration de l’application, mettez à jour le secret expiré ou fournissez la configuration à l’aide d’un fournisseur de configuration personnalisé :

class SampleKeyVaultSecretManager : KeyVaultSecretManager
{
  public override bool Load(SecretProperties properties) =>
    properties.ExpiresOn.HasValue &&
    properties.ExpiresOn.Value > DateTimeOffset.Now;
}

Passez ce fournisseur personnalisé KeyVaultSecretManager à la méthode AddAzureKeyVault :

// using Azure.Extensions.AspNetCore.Configuration.Secrets;

builder.Configuration.AddAzureKeyVault(
    new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
    new DefaultAzureCredential(),
    new SampleKeyVaultSecretManager());

Les secrets désactivés ne peuvent pas être récupérés à partir de Key Vault et ne sont jamais inclus.

Résoudre les problèmes de charge de configuration

Lorsque l’application ne parvient pas à charger la configuration à l’aide du fournisseur, un message d’erreur est écrit dans l’infrastructure de journalisation ASP.NET Core.

Les conditions suivantes peuvent empêcher le chargement de la configuration :

• L’application ou le certificat n’est pas configuré correctement dans Microsoft Entra ID.
• Le coffre-fort n’existe pas dans Azure Key Vault.
• L’application n’est pas autorisée à accéder au coffre-fort.
• La stratégie d’accès n’inclut pas les permissions Get et List.
• Dans le coffre-fort, les données de configuration (paire nom-valeur) sont incorrectement nommées, manquantes ou désactivées.
• L’application a un nom de coffre de clés incorrect (KeyVaultName), un ID d’application Microsoft Entra ID (AzureADApplicationId), une empreinte numérique de certificat Microsoft Entra ID (AzureADCertThumbprint) ou un ID d’annuaire Microsoft Entra ID (AzureADDirectoryId).
• Lorsque la stratégie d'accès Key Vault est ajoutée pour l'application, la stratégie est correctement créée, mais l'utilisateur n'a pas sélectionné Save dans la boîte de dialogue Access.

Contenu connexe

• Afficher ou télécharger l’exemple de code (comment télécharger)
• Configuration dans ASP.NET Core
• Documentation d’Azure Key Vault
• Importer les clés protégées par HSM dans Azure Key Vault
• Quickstart : bibliothèque de client secret Azure Key Vault pour .NET
• Tutoriel : Utiliser Azure Key Vault avec une machine virtuelle dans .NET

Cet article explique comment utiliser le fournisseur de configuration Azure Key Vault pour charger les valeurs de configuration d’une application à partir des secrets Azure Key Vault. Azure Key Vault est un service cloud qui permet de protéger les clés cryptographiques et les secrets utilisés par les applications et les services. Voici quelques scénarios courants d’utilisation d’Azure Key Vault avec des applications ASP.NET Core :

• Contrôler l’accès aux données de configuration sensibles.
• Respect des exigences relatives aux modules de sécurité matérielle (HSM) validés FIPS 140-2 niveau 2 lors du stockage des données de configuration.

Packages

Ajoutez des références de package pour les packages suivants :

• Azure.Extensions.AspNetCore.Configuration.Secrets
• Azur.Identity

Exemple d’application

L’application exemple s’exécute dans l’un des deux modes déterminés par la directive du préprocesseur #define en haut de Program.cs :

• Certificate : illustre l’utilisation d’un ID client Azure Key Vault et d’un certificat X.509 pour accéder aux secrets stockés dans Azure Key Vault. Cet exemple peut être exécuté à partir de n’importe quel emplacement, qu’il soit déployé sur Azure App Service ou sur n’importe quel hôte pouvant servir une application ASP.NET Core.
• Managed : illustre comment utiliser les identités gérées pour les ressources Azure. L’identité managée authentifie l’application auprès d’Azure Key Vault avec des identités managées pour les ressources Azure sans informations d’identification stockées dans le code ou la configuration de l’application. Lorsque vous utilisez des identités gérées pour l’authentification, un ID d’application Identités gérées pour les ressources Azure et un mot de passe (secret client) ne sont pas requis. La version Managed de l’exemple doit être déployée sur Azure. Suivez les instructions de la section Utilisation des identités gérées pour les ressources Azure.

Pour plus d’informations sur la configuration d’une application exemple à l’aide de directives de préprocesseur (#define), consultez Présentation d’ASP.NET Core.

Afficher ou télécharger l’exemple de code (comment télécharger)

Stockage secret dans l’environnement Development

Définissez les secrets localement à l’aide du Gestionnaire de secrets. Lorsque l’exemple d’application s’exécute sur l’ordinateur local dans l’environnement Development , les secrets sont chargés à partir du magasin de secrets utilisateur local.

Le Gestionnaire de secrets nécessite une propriété <UserSecretsId> dans le fichier de projet de l’application. Définissez la valeur de la propriété ({GUID}) sur un GUID unique :

<PropertyGroup>
  <UserSecretsId>{GUID}</UserSecretsId>
</PropertyGroup>

Les secrets sont créés sous forme de paires nom-valeur. Les valeurs hiérarchiques (sections de configuration) utilisent un : (deux points) comme séparateur dans les noms de clés de configuration ASP.NET Core.

Secret Manager est utilisé à partir d’un interpréteur de commandes ouvert à la racine du contenu du projet, où {SECRET NAME} est le nom et {SECRET VALUE} est la valeur :

dotnet user-secrets set "{SECRET NAME}" "{SECRET VALUE}"

Exécutez les commandes suivantes dans un interpréteur de commandes à partir de la racine du contenu du projet pour définir les secrets de l’application d’exemple :

dotnet user-secrets set "SecretName" "secret_value_1_dev"
dotnet user-secrets set "Section:SecretName" "secret_value_2_dev"

Lorsque ces secrets sont stockés dans Azure Key Vault dans la section Stockage secret dans l'environnement Azure Key VaultProduction, le suffixe _dev est modifié en _prod. Le suffixe fournit un repère visuel dans la sortie de l’application indiquant la source des valeurs de configuration.

Stockage secret dans l’environnement Production avec Azure Key Vault

Suivez ces étapes pour créer un Azure Key Vault et y stocker les secrets de l’application exemple. Pour plus d’informations, consultez Démarrage rapide : Définir et récupérer un secret depuis Azure Key Vault à l’aide d’Azure CLI.

1. Ouvrez Azure Cloud Shell à l’aide de l’une des méthodes suivantes dans le portail Azure :

   • Sélectionnez Essayer dans le coin supérieur droit d’un bloc de code. Utilisez la chaîne de recherche « Azure CLI » dans la zone de texte.
   • Ouvrez Cloud Shell dans votre navigateur à l’aide du bouton Lancer Cloud Shell.
   • Sélectionnez le bouton Cloud Shell dans le menu en haut à droite du portail Azure.

   Pour plus d’informations, consultez Azure CLI et Présentation d’Azure Cloud Shell.

2. Si vous n’êtes pas encore authentifié, connectez-vous à l’aide de la commande az login.

3. Créez un groupe de ressources à l’aide de la commande suivante, où {RESOURCE GROUP NAME} correspond au nom du nouveau groupe de ressources et {LOCATION} à la région Azure :

   az group create --name "{RESOURCE GROUP NAME}" --location {LOCATION}
   

4. Créez un Key Vault dans le groupe de ressources à l’aide de la commande suivante, où {KEY VAULT NAME} correspond au nom du nouveau coffre et {LOCATION} à la région Azure :

   az keyvault create --name {KEY VAULT NAME} --resource-group "{RESOURCE GROUP NAME}" --location {LOCATION}
   

5. Créez des secrets dans le coffre sous forme de paires nom-valeur.

   Les noms de secrets Azure Key Vault sont limités aux caractères alphanumériques et aux tirets. Les valeurs hiérarchiques (sections de configuration) utilisent -- (deux tirets) comme délimiteur, car les deux-points ne sont pas autorisés dans les noms de secrets Key Vault. Les deux-points délimitent une section d’une sous-clé dans la configuration ASP.NET Core. La séquence de deux tirets est remplacée par un deux-points lorsque les secrets sont chargés dans la configuration de l’application.

   Les secrets suivants sont destinés à être utilisés avec l’application exemple. Les valeurs incluent un _prod suffixe pour les distinguer des valeurs de suffixe _dev chargées dans l’environnement Development depuis le Secret Manager. Remplacez {KEY VAULT NAME} par le nom du Key Vault que vous avez créé à l’étape précédente :

   az keyvault secret set --vault-name {KEY VAULT NAME} --name "SecretName" --value "secret_value_1_prod"
   az keyvault secret set --vault-name {KEY VAULT NAME} --name "Section--SecretName" --value "secret_value_2_prod"
   

Utiliser l’ID d’application et le certificat X.509 pour les applications non hébergées sur Azure

Configurez Azure Key Vault et l’application pour utiliser un ID d’application Microsoft Entra ID et un certificat X.509 pour s’authentifier auprès d’un coffre lorsque l’application est hébergée en dehors d’Azure. Pour plus d’informations, consultez À propos des clés, des secrets et des certificats.

L’application exemple utilise un ID d’application et un certificat X.509 lorsque la directive de préprocesseur #define en haut de Program.cs est définie sur Certificate.

1. Créez un certificat d’archive PKCS#12 (.pfx). Les options de création de certificats incluent New-SelfSignedCertificate sur Windows et OpenSSL.
2. Installez le certificat dans le magasin de certificats personnels de l’utilisateur actuel. Le marquage de la clé comme exportable est facultatif. Notez l’empreinte digitale du certificat, qui sera utilisée plus tard dans ce processus.
3. Exportez le certificat d’archive PKCS#12 (.pfx) en tant que certificat codé DER (.cer).
4. Enregistrez l’application avec Microsoft Entra ID (Inscriptions d’applications).
5. Chargez le certificat codé DER (.cer) dans Microsoft Entra ID : XXX
   1. Sélectionnez l’application dans Microsoft Entra ID.
   2. Accédez à Certificats & secrets.
   3. Sélectionnez Charger le certificat pour charger le certificat, qui contient la clé publique. Un certificat .cer, .pem ou .crt est acceptable.
6. Stockez le nom du Key Vault, l’ID de l’application et l’empreinte digitale du certificat dans le fichier appsettings.json de l’application.
7. Accédez à Key Vaults dans le portail Azure.
8. Sélectionnez le coffre de clés que vous avez créé dans la section stockage secret dans l’environnement Production avec Azure Key Vault.
9. Sélectionnez Stratégies d’accès.
10. Sélectionnez Ajouter une stratégie d’accès.
11. Ouvrez les permissions secrètes et accordez à l’application les permissions Obtenir et Lister.
12. Sélectionnez Sélectionner le principal et sélectionnez l’application enregistrée par son nom. Sélectionnez le bouton Sélectionner.
13. Cliquez sur OK.
14. Cliquez sur Enregistrer.
15. Déployez l’application.

L’application exemple Certificate obtient ses valeurs de configuration à partir de IConfigurationRoot avec le même nom que le nom secret :

• Valeurs non hiérarchiques : la valeur de SecretName est obtenue avec config["SecretName"].
• Valeurs hiérarchiques (sections) : utilisez la notation : (deux points) ou la méthode GetSection. Utilisez l’une de ces deux approches pour obtenir la valeur de configuration :
  • config["Section:SecretName"]
  • config.GetSection("Section")["SecretName"]

Le certificat X.509 est géré par le système d’exploitation. L’application appelle AddAzureKeyVault avec les valeurs fournies par le fichier appsettings.json :

// using System.Linq;
// using System.Security.Cryptography.X509Certificates;
// using Azure.Extensions.AspNetCore.Configuration.Secrets;
// using Azure.Identity;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((context, config) =>
        {
            if (context.HostingEnvironment.IsProduction())
            {
                var builtConfig = config.Build();

                using var store = new X509Store(StoreLocation.CurrentUser);
                store.Open(OpenFlags.ReadOnly);
                var certs = store.Certificates.Find(
                    X509FindType.FindByThumbprint,
                    builtConfig["AzureADCertThumbprint"], false);

                config.AddAzureKeyVault(new Uri($"https://{builtConfig["KeyVaultName"]}.vault.azure.net/"),
                                        new ClientCertificateCredential(builtConfig["AzureADDirectoryId"], builtConfig["AzureADApplicationId"], certs.OfType<X509Certificate2>().Single()),
                                        new KeyVaultSecretManager());

                store.Close();
            }
        })
        .ConfigureWebHostDefaults(webBuilder => webBuilder.UseStartup<Startup>());

Exemples de valeurs

• Nom du Key Vault : contosovault
• ID application : 00001111-aaaa-2222-bbbb-3333cccc4444
• Empreinte digitale du certificat : fe14593dd66b2406c5269d742d04b6e1ab03adb1

appsettings.json :

{
  "KeyVaultName": "Key Vault Name",
  "AzureADApplicationId": "Azure AD Application ID",
  "AzureADCertThumbprint": "Azure AD Certificate Thumbprint",
  "AzureADDirectoryId": "Azure AD Directory ID"
}

Lorsque vous exécutez l’application, une page Web affiche les valeurs secrètes chargées. Dans l’environnement Development , les valeurs secrètes se chargent avec le _dev suffixe. Dans l’environnement Production , les valeurs se chargent avec le _prod suffixe.

Utiliser des identités managées pour des ressources Azure

Une application déployée sur Azure peut tirer parti des identités gérées pour les ressources Azure. Une identité managée permet à l’application de s’authentifier auprès d’Azure Key Vault à l’aide de l’authentification d’ID Microsoft Entra sans informations d’identification (ID d’application et mot de passe/secret client) stockées dans l’application.

L’application exemple utilise des identités gérées pour les ressources Azure lorsque la directive de préprocesseur #define en haut de Program.cs est définie sur Managed.

Entrez le nom du coffre-fort dans le fichier appsettings.json de l’application. L’application exemple ne nécessite pas d’ID d’application ni de mot de passe (secret client) lorsqu’elle est définie sur la version Managed. Vous pouvez donc ignorer ces entrées de configuration. L’application est déployée sur Azure, et Azure authentifie l’application pour accéder à Azure Key Vault en utilisant uniquement le nom du coffre-fort stocké dans le fichier appsettings.json.

Déployez l’application exemple sur Azure App Service.

Une application déployée sur Azure App Service est automatiquement enregistrée avec Microsoft Entra ID lors de la création du service. Obtenez l’ID d’objet à partir du déploiement pour l’utiliser dans la commande suivante. L’ID d’objet s’affiche dans le portail Azure, dans le panneau Identity du service App Service.

À l’aide d’Azure CLI et de l’ID d’objet de l’application, fournissez à l’application les autorisations list et get pour accéder au coffre :

az keyvault set-policy --name {KEY VAULT NAME} --object-id {OBJECT ID} --secret-permissions get list

Redémarrez l’application à l’aide d’Azure CLI, PowerShell ou le portail Azure.

Exemple d’application :

• Crée une instance de la classe DefaultAzureCredential. Les informations d’identification tentent d’obtenir un jeton d’accès à partir de l’environnement pour les ressources Azure.
• Un nouveau SecretClient est créé avec l’instance DefaultAzureCredential.
• L’instance SecretClient est utilisée avec une instance KeyVaultSecretManager, qui charge les valeurs secrètes et remplace les doubles tirets (--) par des deux-points (:) dans les noms de clé.

// using Azure.Security.KeyVault.Secrets;
// using Azure.Identity;
// using Azure.Extensions.AspNetCore.Configuration.Secrets;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((context, config) =>
        {
            if (context.HostingEnvironment.IsProduction())
            {
                var builtConfig = config.Build();
                var secretClient = new SecretClient(
                    new Uri($"https://{builtConfig["KeyVaultName"]}.vault.azure.net/"),
                    new DefaultAzureCredential());
                config.AddAzureKeyVault(secretClient, new KeyVaultSecretManager());
            }
        })
        .ConfigureWebHostDefaults(webBuilder => webBuilder.UseStartup<Startup>());

Exemple de valeur de nom de Key Vault : contosovault

appsettings.json :

{
  "KeyVaultName": "Key Vault Name"
}

Lorsque vous exécutez l’application, une page Web affiche les valeurs secrètes chargées. Dans l’environnement Development , les valeurs secrètes ont le _dev suffixe, car elles sont fournies par Secret Manager. Dans l’environnement Production , les valeurs sont chargées avec le _prod suffixe, car elles sont fournies par Azure Key Vault.

Si vous recevez une erreur Access denied, vérifiez que l’application est enregistrée avec Microsoft Entra ID et qu’elle a accès au coffre. Vérifiez que vous avez redémarré le service dans Azure.

Pour plus d’informations sur l’utilisation du fournisseur avec une identité managée et Azure Pipelines, consultez Créer une connexion de service Azure Resource Manager à une machine virtuelle avec une identité de service managée.

Options de configuration

AddAzureKeyVaultpeut accepter un objet AzureKeyVaultConfigurationOptions :

config.AddAzureKeyVault(
    new SecretClient(
        new Uri("Your Key Vault Endpoint"),
        new DefaultAzureCredential(),
        new AzureKeyVaultConfigurationOptions())
    {
        ...
    });

L’objet AzureKeyVaultConfigurationOptions contient les propriétés suivantes.

Utilisez un préfixe de nom de clé

AddAzureKeyVaultfournit une surcharge qui accepte une implémentation de KeyVaultSecretManager, ce qui vous permet de contrôler la manière dont les secrets Key Vault sont convertis en clés de configuration. Par exemple, vous pouvez implémenter l’interface pour charger les valeurs secrètes en fonction d’une valeur de préfixe que vous fournissez au démarrage de l’application. Cette technique vous permet, par exemple, de charger des secrets en fonction de la version de l’application.

Dans l’exemple suivant, un secret est établi dans Key Vault (et l’utilisation du Gestionnaire de secrets pour l’environnement Development ) pour 5000-AppSecret (les périodes ne sont pas autorisées dans les noms de secrets Key Vault). Ce secret représente un secret d’application pour la version 5.0.0.0 de l’application. Pour une autre version de l’application, 5.1.0.0, un secret est ajouté au coffre-fort (et à l’aide de Secret Manager) pour 5100-AppSecret. Chaque version de l’application charge sa valeur de secret versionnée dans sa configuration en tant que AppSecret, en supprimant la version lors du chargement du secret.

AddAzureKeyVaultest appelé avec une implémentation KeyVaultSecretManager personnalisée :

config.AddAzureKeyVault(
    $"https://{builtConfig["KeyVaultName"]}.vault.azure.net/",
    builtConfig["AzureADApplicationId"],
    certs.OfType<X509Certificate2>().Single(),
    new PrefixKeyVaultSecretManager(versionPrefix));

L’implémentation réagit aux préfixes de version des secrets pour charger le secret approprié dans la configuration :

• Loadcharge un secret lorsque son nom commence par le préfixe. Les autres secrets ne sont pas chargés.
• GetKey :
  • Supprime le préfixe du nom du secret.
  • Remplace deux tirets dans tout nom par KeyDelimiter, qui est le délimiteur utilisé dans la configuration (généralement un deux-points). Azure Key Vault n’autorise pas les deux-points dans les noms de secrets.

public class PrefixKeyVaultSecretManager : KeyVaultSecretManager
{
    private readonly string _prefix;

    public PrefixKeyVaultSecretManager(string prefix)
    {
        _prefix = $"{prefix}-";
    }

    public override bool Load(SecretProperties secret)
    {
        return secret.Name.StartsWith(_prefix);
    }

    public override string GetKey(KeyVaultSecret secret)
    {
        return secret.Name
            .Substring(_prefix.Length)
            .Replace("--", ConfigurationPath.KeyDelimiter);
    }
}

La méthode Load est appelée par un algorithme de fournisseur qui parcourt les secrets du coffre-fort pour trouver les secrets préfixés par la version. Lorsqu’un préfixe de version est trouvé avec Load, l’algorithme utilise la méthode GetKey pour renvoyer le nom de configuration du nom du secret. Il supprime le préfixe de version du nom du secret. Le reste du nom du secret est retourné pour être chargé dans les paires nom-valeur de la configuration de l’application.

Lorsque cette approche est mise en œuvre :

1. La version de l’application spécifiée dans le fichier de projet de l’application. Dans l’exemple suivant, la version de l’application est définie sur 5.0.0.0 :

   <PropertyGroup>
     <Version>5.0.0.0</Version>
   </PropertyGroup>
   

2. Vérifiez qu’une propriété <UserSecretsId> est présente dans le fichier de projet de l’application, où {GUID} est un GUID fourni par l’utilisateur :

   <PropertyGroup>
     <UserSecretsId>{GUID}</UserSecretsId>
   </PropertyGroup>
   

   Enregistrez les secrets suivants localement avec Secret Manager :

   dotnet user-secrets set "5000-AppSecret" "5.0.0.0_secret_value_dev"
   dotnet user-secrets set "5100-AppSecret" "5.1.0.0_secret_value_dev"
   

3. Les secrets sont enregistrés dans Azure Key Vault à l’aide des commandes Azure CLI suivantes :

   az keyvault secret set --vault-name {KEY VAULT NAME} --name "5000-AppSecret" --value "5.0.0.0_secret_value_prod"
   az keyvault secret set --vault-name {KEY VAULT NAME} --name "5100-AppSecret" --value "5.1.0.0_secret_value_prod"
   

4. Lorsque l’application est exécutée, les secrets Key Vault sont chargés. La chaîne secrète pour 5000-AppSecret correspond à la version de l’application spécifiée dans le fichier de projet de l’application (5.0.0.0).

5. La version, 5000 (avec le tiret), est supprimée du nom de la clé. Dans toute l’application, la lecture de la configuration avec la clé AppSecret charge la valeur secrète.

6. Si la version de l’application est modifiée dans le fichier projet 5.1.0.0 et que l’application est réexécutée, la valeur secrète retournée est 5.1.0.0_secret_value_dev dans l’environnement Development et 5.1.0.0_secret_value_prod dans Production.

Lier un tableau à une classe

Le fournisseur peut lire les valeurs de configuration dans un tableau pour les lier à un tableau POCO.

Lors de la lecture à partir d’une source de configuration qui autorise les séparateurs deux-points (:) dans les clés, un segment de clé numérique est utilisé pour distinguer les clés qui composent un tableau (:0:, :1:, … :{n}:). Pour plus d’informations, consultez Configuration : lier un tableau à une classe.

Les clés Azure Key Vault ne peuvent pas utiliser de deux-points comme séparateur. L’approche décrite dans cet article utilise des doubles tirets (--) comme séparateur pour les valeurs hiérarchiques (sections). Les clés de tableau sont stockées dans Azure Key Vault avec des doubles tirets et des segments de clé numériques (--0--, --1--, … --{n}--).

Examinez la configuration suivante du fournisseur de journalisation Serilog fournie par un fichier JSON. Deux littéraux d’objet sont définis dans le tableau WriteTo qui reflètent deux récepteurs Serilog, qui décrivent les destinations pour la sortie de journalisation :

"Serilog": {
  "WriteTo": [
    {
      "Name": "AzureTableStorage",
      "Args": {
        "storageTableName": "logs",
        "connectionString": "DefaultEnd...ountKey=Eby8...GMGw=="
      }
    },
    {
      "Name": "AzureDocumentDB",
      "Args": {
        "endpointUrl": "https://contoso.documents.azure.com:443",
        "authorizationKey": "Eby8...GMGw=="
      }
    }
  ]
}

La configuration indiquée dans le fichier JSON précédent est stockée dans Azure Key Vault à l’aide de la notation double tiret (--) et de segments numériques :

Recharger les secrets

Les secrets sont mis en cache jusqu’à l’appel de IConfigurationRoot.Reload. Les secrets désactivés ou mis à jour ultérieurement dans le coffre-fort ne sont pas pris en compte par l’application jusqu’à l’exécution de Reload.

Configuration.Reload();

Secrets désactivés et expirés

Les secrets expirés sont inclus par défaut dans le fournisseur de configuration. Pour exclure les valeurs de ces secrets de la configuration de l’application, mettez à jour le secret expiré ou fournissez la configuration à l’aide d’un fournisseur de configuration personnalisé :

class SampleKeyVaultSecretManager : KeyVaultSecretManager
{
  public override bool Load(SecretProperties properties) =>
    properties.ExpiresOn.HasValue &&
    properties.ExpiresOn.Value > DateTimeOffset.Now;
}

Transmettez ce KeyVaultSecretManager personnalisé à AddAzureKeyVault :

// using Azure.Extensions.AspNetCore.Configuration.Secrets;

config.AddAzureKeyVault(
    new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
    new DefaultAzureCredential(),
    new SampleKeyVaultSecretManager());

Les secrets désactivés ne peuvent pas être récupérés à partir de Key Vault et ne sont jamais inclus.

Troubleshoot

Lorsque l’application ne parvient pas à charger la configuration à l’aide du fournisseur, un message d’erreur est écrit dans l’infrastructure de journalisation ASP.NET Core. Les conditions suivantes empêchent le chargement de la configuration :

• L’application ou le certificat n’est pas configuré correctement dans Microsoft Entra ID.
• Le coffre-fort n’existe pas dans Azure Key Vault.
• L’application n’est pas autorisée à accéder au coffre-fort.
• La stratégie d’accès n’inclut pas les permissions Get et List.
• Dans le coffre-fort, les données de configuration (paire nom-valeur) sont incorrectement nommées, manquantes ou désactivées.
• L’application a un nom de Key Vault incorrect (KeyVaultName), un ID d’application Microsoft Entra ID incorrect (AzureADApplicationId), une empreinte digitale de certificat Microsoft Entra ID incorrecte (AzureADCertThumbprint) ou un ID de répertoire Microsoft Entra ID incorrect (AzureADDirectoryId).
• Lors de l’ajout de la stratégie d’accès Key Vault pour l’application, la stratégie a été créée, mais le bouton Enregistrer n’a pas été sélectionné dans l’interface utilisateur Stratégies d’accès.

Ressources supplémentaires

• Afficher ou télécharger l’exemple de code (comment télécharger)
• Configuration dans ASP.NET Core
• Microsoft Azure : documentation Key Vault
• Comment générer et transférer des clés protégées par HSM pour Azure Key Vault
• Démarrage rapide : définir et récupérer un secret à partir d’Azure Key Vault à l’aide d’une application Web .NET
• Didacticiel : Comment utiliser Azure Key Vault avec Azure Windows Virtual Machine dans .NET