Fournisseur de configuration Azure Key Vault dans ASP.NET CoreAzure Key Vault Configuration Provider in ASP.NET Core

Par Luke Latham et Andrew Stanton-infirmièreBy Luke Latham and Andrew Stanton-Nurse

Ce document explique comment utiliser le fournisseur de configuration Microsoft Azure Key Vault pour charger des valeurs de configuration d’application à partir de Azure Key Vault secrets.This document explains how to use the Microsoft Azure Key Vault Configuration Provider to load app configuration values from Azure Key Vault secrets. Azure Key Vault est un service basé sur le Cloud qui permet de protéger les clés de chiffrement et les secrets utilisés par les applications et les services.Azure Key Vault is a cloud-based service that assists in safeguarding cryptographic keys and secrets used by apps and services. Les scénarios courants d’utilisation de Azure Key Vault avec les applications ASP.NET Core sont les suivants:Common scenarios for using Azure Key Vault with ASP.NET Core apps include:

  • Contrôle de l’accès aux données de configuration sensibles.Controlling access to sensitive configuration data.
  • Respect de la configuration requise pour les modules de sécurité matériels (HSM) certifiés FIPS 140-2 de niveau 2 lors du stockage des données de configuration.Meeting the requirement for FIPS 140-2 Level 2 validated Hardware Security Modules (HSM's) when storing configuration data.

Ce scénario est disponible pour les applications qui ciblent ASP.NET Core 2,1 ou une version ultérieure.This scenario is available for apps that target ASP.NET Core 2.1 or later.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

PackagesPackages

Pour utiliser le fournisseur de configuration Azure Key Vault, ajoutez une référence de package au package Microsoft. extensions. Configuration. AzureKeyVault .To use the Azure Key Vault Configuration Provider, add a package reference to the Microsoft.Extensions.Configuration.AzureKeyVault package.

Pour adopter le scénario gestion des identités pour les ressources Azure , ajoutez une référence de package au package Microsoft. Azure. services. AppAuthentication .To adopt the Managed identities for Azure resources scenario, add a package reference to the Microsoft.Azure.Services.AppAuthentication package.

Notes

Au moment de l’écriture, la dernière version stable de Microsoft.Azure.Services.AppAuthentication, version 1.0.3, prend en charge les identités gérées affectées par le système.At the time of writing, the latest stable release of Microsoft.Azure.Services.AppAuthentication, version 1.0.3, provides support for system-assigned managed identities. La prise en charge des identités gérées affectées 1.2.0-preview2 par l’utilisateur est disponible dans le package.Support for user-assigned managed identities is available in the 1.2.0-preview2 package. Cette rubrique montre l’utilisation des identités gérées par le système, et l’exemple d' 1.0.3 application fourni Microsoft.Azure.Services.AppAuthentication utilise la version du package.This topic demonstrates the use of system-managed identities, and the provided sample app uses version 1.0.3 of the Microsoft.Azure.Services.AppAuthentication package.

Exemple d’applicationSample app

L’exemple d’application s’exécute dans l’un des deux modes #define déterminés par l’instruction en haut du fichier Program.cs :The sample app runs in either of two modes determined by the #define statement at the top of the Program.cs file:

  • 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.Certificate – Demonstrates the use of an Azure Key Vault Client ID and X.509 certificate to access secrets stored in Azure Key Vault. Cette version de l’exemple peut être exécutée à partir de n’importe quel emplacement, déployée sur Azure App Service ou n’importe quel hôte capable de servir une application ASP.NET Core.This version of the sample can be run from any location, deployed to Azure App Service or any host capable of serving an ASP.NET Core app.
  • ManagedMontre comment utiliser des identités gérées pour les ressources Azure pour authentifier l’application afin de Azure Key Vault avec l’authentification Azure ad sans les informations d’identification stockées dans le code ou la configuration de l’application. –Managed – Demonstrates how to use Managed identities for Azure resources to authenticate the app to Azure Key Vault with Azure AD authentication without credentials stored in the app's code or configuration. Lorsque vous utilisez des identités gérées pour l’authentification, un ID d’application et un mot de passe de Azure AD (clé secrète client) ne sont pas requis.When using managed identities to authenticate, an Azure AD Application ID and Password (Client Secret) aren't required. La Managed version de l’exemple doit être déployée sur Azure.The Managed version of the sample must be deployed to Azure. Suivez les instructions de la section utiliser les identités gérées pour les ressources Azure .Follow the guidance in the Use the Managed identities for Azure resources section.

Pour plus d’informations sur la configuration d’un exemple d’application à l’aide de#definedirectives de préprocesseur (), consultez. Présentation d’ASP.NET CoreFor more information on how to configure a sample app using preprocessor directives (#define), see Présentation d’ASP.NET Core.

Stockage secret dans l’environnement de développementSecret storage in the Development environment

Définissez les secrets localement à l’aide de l' outil Gestionnaire de secret.Set secrets locally using the Secret Manager tool. Lorsque l’exemple d’application s’exécute sur l’ordinateur local dans l’environnement de développement, les secrets sont chargés à partir du magasin du gestionnaire de secret local.When the sample app runs on the local machine in the Development environment, secrets are loaded from the local Secret Manager store.

L’outil Gestionnaire de secret nécessite <UserSecretsId> une propriété dans le fichier projet de l’application.The Secret Manager tool requires a <UserSecretsId> property in the app's project file. Définissez la valeur de la{GUID}propriété () sur un GUID unique:Set the property value ({GUID}) to any unique GUID:

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

Les secrets sont créés en tant que paires nom-valeur.Secrets are created as name-value pairs. Les valeurs hiérarchiques (sections de configuration) : utilisent un (deux-points) comme séparateur dans ASP.net Core noms de clé de configuration .Hierarchical values (configuration sections) use a : (colon) as a separator in ASP.NET Core configuration key names.

Le gestionnaire de secret est utilisé à partir d’une interface de commande ouverte à la racine de {SECRET NAME} contenu du projet, {SECRET VALUE} où est le nom et est la valeur:The Secret Manager is used from a command shell opened to the project's content root, where {SECRET NAME} is the name and {SECRET VALUE} is the value:

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

Exécutez les commandes suivantes dans une interface de commande à partir de la racine de contenu du projet pour définir les secrets de l’exemple d’application:Execute the following commands in a command shell from the project's content root to set the secrets for the sample app:

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 le stockage secret dans l’environnement de production avec Azure Key Vault section, _dev le suffixe est _prodremplacé par.When these secrets are stored in Azure Key Vault in the Secret storage in the Production environment with Azure Key Vault section, the _dev suffix is changed to _prod. Le suffixe fournit un signal visuel dans la sortie de l’application qui indique la source des valeurs de configuration.The suffix provides a visual cue in the app's output indicating the source of the configuration values.

Stockage secret dans l’environnement de production avec Azure Key VaultSecret storage in the Production environment with Azure Key Vault

Les instructions fournies par le Guide de démarrage rapide: Définir et récupérer un secret à partir d’Azure Key Vault à l’aide d’Azure CLI rubrique sont résumées ici pour créer un Azure Key Vault et stocker des secrets utilisés par l’exemple d’application.The instructions provided by the Quickstart: Set and retrieve a secret from Azure Key Vault using Azure CLI topic are summarized here for creating an Azure Key Vault and storing secrets used by the sample app. Pour plus d’informations, reportez-vous à la rubrique.Refer to the topic for further details.

  1. Ouvrez Azure Cloud Shell à l’aide de l’une des méthodes suivantes dans la portail Azure:Open Azure Cloud shell using any one of the following methods in the Azure portal:

    • Sélectionnez essayer dans le coin supérieur droit d’un bloc de code.Select Try It in the upper-right corner of a code block. Utilisez la chaîne de recherche «Azure CLI» dans la zone de texte.Use the search string "Azure CLI" in the text box.
    • Ouvrez Cloud Shell dans votre navigateur à l’aide du bouton Launch Cloud Shell .Open Cloud Shell in your browser with the Launch Cloud Shell button.
    • Sélectionnez le bouton Cloud Shell dans le menu situé dans l’angle supérieur droit du portail Azure.Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal.

    Pour plus d’informations, consultez interface de ligne de commande (CLI) Azure et vue d’ensemble de Azure Cloud Shell.For more information, see Azure Command-Line Interface (CLI) and Overview of Azure Cloud Shell.

  2. Si vous n’êtes pas déjà authentifié, connectez-vous az login à l’aide de la commande.If you aren't already authenticated, sign in with the az login command.

  3. Créez un groupe de ressources à l’aide de la {RESOURCE GROUP NAME} commande suivante, où est le nom du groupe de ressources {LOCATION} pour le nouveau groupe de ressources et est la région Azure (Datacenter):Create a resource group with the following command, where {RESOURCE GROUP NAME} is the resource group name for the new resource group and {LOCATION} is the Azure region (datacenter):

    az group create --name "{RESOURCE GROUP NAME}" --location {LOCATION}
    
  4. Créez un coffre de clés dans le groupe de ressources à l’aide de {KEY VAULT NAME} la commande suivante, où est le nom du {LOCATION} nouveau coffre de clés et est la région Azure (Datacenter):Create a key vault in the resource group with the following command, where {KEY VAULT NAME} is the name for the new key vault and {LOCATION} is the Azure region (datacenter):

    az keyvault create --name "{KEY VAULT NAME}" --resource-group "{RESOURCE GROUP NAME}" --location {LOCATION}
    
  5. Créez des secrets dans le coffre de clés en tant que paires nom-valeur.Create secrets in the key vault as name-value pairs.

    Azure Key Vault noms de secrets sont limités aux caractères alphanumériques et aux tirets.Azure Key Vault secret names are limited to alphanumeric characters and dashes. Pour des valeurs hiérarchiques (sections de configuration), utilisez -- (deux tirets) comme séparateur.Hierarchical values (configuration sections) use -- (two dashes) as a separator. Les signes deux-points, qui sont normalement utilisés pour délimiter une section d’une sous-clé dans ASP.net Core configuration, ne sont pas autorisés dans les noms de secrets du coffre de clés.Colons, which are normally used to delimit a section from a subkey in ASP.NET Core configuration, aren't allowed in key vault secret names. Par conséquent, les deux tirets sont remplacés par deux points lorsque les clés secrètes sont chargées dans la configuration de l’application.Therefore, two dashes are used and swapped for a colon when the secrets are loaded into the app's configuration.

    Les secrets suivants sont destinés à être utilisés avec l’exemple d’application.The following secrets are for use with the sample app. Les valeurs incluent un _prod suffixe pour les distinguer _dev des valeurs de suffixe chargées dans l’environnement de développement des secrets d’utilisateur.The values include a _prod suffix to distinguish them from the _dev suffix values loaded in the Development environment from User Secrets. Remplacez {KEY VAULT NAME} par le nom du coffre de clés que vous avez créé à l’étape précédente:Replace {KEY VAULT NAME} with the name of the key vault that you created in the prior step:

    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 AzureUse Application ID and X.509 certificate for non-Azure-hosted apps

Configurez Azure AD, Azure Key Vault et l’application pour qu’elle utilise un ID d’application Azure Active Directory et un certificat X. 509 pour s’authentifier auprès d’un coffre de clés lorsque l’application est hébergée en dehors d’Azure.Configure Azure AD, Azure Key Vault, and the app to use an Azure Active Directory Application ID and X.509 certificate to authenticate to a key vault when the app is hosted outside of Azure. Pour plus d’informations, consultez à propos des clés, des secrets et des certificats.For more information, see About keys, secrets, and certificates.

Notes

Bien que l’utilisation d’un ID d’application et d’un certificat X. 509 soit prise en charge pour les applications hébergées dans Azure, nous vous recommandons d’utiliser des identités gérées pour les ressources Azure lors de l’hébergement d’une application dans Azure.Although using an Application ID and X.509 certificate is supported for apps hosted in Azure, we recommend using Managed identities for Azure resources when hosting an app in Azure. Les identités gérées ne nécessitent pas le stockage d’un certificat dans l’application ou dans l’environnement de développement.Managed identities don't require storing a certificate in the app or in the development environment.

L’exemple d’application utilise un ID d’application et un certificat X. #define 509 lorsque l’instruction en haut du Certificatefichier Program.cs a la valeur.The sample app uses an Application ID and X.509 certificate when the #define statement at the top of the Program.cs file is set to Certificate.

  1. Créez un certificat d’archive PKCS # 12 ( . pfx).Create a PKCS#12 archive (.pfx) certificate. Les options de création de certificats incluent Makecert sur Windows et OpenSSL.Options for creating certificates include MakeCert on Windows and OpenSSL.
  2. Installez le certificat dans le magasin de certificats personnel de l’utilisateur actuel.Install the certificate into the current user's personal certificate store. Le marquage de la clé comme étant exportable est facultatif.Marking the key as exportable is optional. Notez l’empreinte numérique du certificat, qui est utilisé plus loin dans ce processus.Note the certificate's thumbprint, which is used later in this process.
  3. Exportez le certificat PKCS # 12 ( . pfx) sous la forme d’un certificat encodé der ( . cer).Export the PKCS#12 archive (.pfx) certificate as a DER-encoded certificate (.cer).
  4. Inscrire l’application auprès de Azure AD (inscriptions d’applications).Register the app with Azure AD (App registrations).
  5. Chargez le certificat codé DER ( . cer) dans Azure ad:Upload the DER-encoded certificate (.cer) to Azure AD:
    1. Sélectionnez l’application dans Azure AD.Select the app in Azure AD.
    2. Accédez à certificats & secrets.Navigate to Certificates & secrets.
    3. Sélectionnez Télécharger le certificat pour télécharger le certificat, qui contient la clé publique.Select Upload certificate to upload the certificate, which contains the public key. Un certificat. CER, . pemou . CRT est acceptable.A .cer, .pem, or .crt certificate is acceptable.
  6. Stockez le nom du coffre de clés, l’ID de l’application et l’empreinte numérique du certificat dans le fichier appSettings. JSON de l’application.Store the key vault name, Application ID, and certificate thumbprint in the app's appsettings.json file.
  7. Accédez à coffres de clés dans le portail Azure.Navigate to Key vaults in the Azure portal.
  8. Sélectionnez le coffre de clés que vous avez créé dans la section stockage secret dans l’environnement de production avec Azure Key Vault .Select the key vault that you created in the Secret storage in the Production environment with Azure Key Vault section.
  9. Sélectionnez stratégies d’accès.Select Access policies.
  10. Sélectionnez Ajouter nouveau.Select Add new.
  11. Sélectionnez Sélectionner un principal et sélectionnez l’application inscrite par son nom.Select Select principal and select the registered app by name. Sélectionnez le bouton Sélectionner .Select the Select button.
  12. Ouvrez les autorisations secret et fournissez à l’application les autorisations obtenir et liste .Open Secret permissions and provide the app with Get and List permissions.
  13. Sélectionnez OK.Select OK.
  14. Sélectionnez Enregistrer.Select Save.
  15. Déployez l’application.Deploy the app.

L' Certificate exemple d’application obtient ses valeurs de configuration IConfigurationRoot à partir du même nom que le nom de la clé secrète:The Certificate sample app obtains its configuration values from IConfigurationRoot with the same name as the secret name:

  • Valeurs non hiérarchiques: La valeur de SecretName est obtenu avec config["SecretName"].Non-hierarchical values: The value for SecretName is obtained with config["SecretName"].
  • Valeurs hiérarchiques (sections): Utilisez : la notation (deux-points GetSection ) ou la méthode d’extension.Hierarchical values (sections): Use : (colon) notation or the GetSection extension method. Utilisez une des ces approches pour obtenir la valeur de configuration, :Use either of these approaches to obtain the configuration value:
    • config["Section:SecretName"]
    • config.GetSection("Section")["SecretName"]

Le certificat X. 509 est géré par le système d’exploitation.The X.509 certificate is managed by the OS. L’application appelle AddAzureKeyVault avec les valeurs fournies par le fichier appSettings. JSON :The app calls AddAzureKeyVault with values supplied by the appsettings.json file:

// using System.Linq;
// using System.Security.Cryptography.X509Certificates;
// using Microsoft.Extensions.Configuration;
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((context, config) =>
        {
            if (context.HostingEnvironment.IsProduction())
            {
                var builtConfig = config.Build();

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

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

                    store.Close();
                }
            }
        })
        .UseStartup<Startup>();

Exemples de valeurs:Example values:

  • Nom du coffre de clés:contosovaultKey vault name: contosovault
  • ID de l’application:627e911e-43cc-61d4-992e-12db9c81b413Application ID: 627e911e-43cc-61d4-992e-12db9c81b413
  • Empreinte numérique du certificat:fe14593dd66b2406c5269d742d04b6e1ab03adb1Certificate thumbprint: fe14593dd66b2406c5269d742d04b6e1ab03adb1

appsettings.json :appsettings.json:

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

Quand vous exécutez l’application, une page Web affiche les valeurs de secret chargées.When you run the app, a webpage shows the loaded secret values. Dans l’environnement de développement, les valeurs secrètes _dev sont chargées avec le suffixe.In the Development environment, secret values load with the _dev suffix. Dans l’environnement de production, les valeurs sont chargées avec le _prod suffixe.In the Production environment, the values load with the _prod suffix.

Utiliser des identités gérées pour les ressources AzureUse Managed identities for Azure resources

Une application déployée sur Azure peut tirer parti des identités gérées pour les ressources Azure, ce qui permet à l’application de s’authentifier avec Azure Key Vault à l’aide de l’authentification Azure ad sans informations d’identification (ID d’application et mot de passe/clé secrète client) stocké dans l’application.An app deployed to Azure can take advantage of Managed identities for Azure resources, which allows the app to authenticate with Azure Key Vault using Azure AD authentication without credentials (Application ID and Password/Client Secret) stored in the app.

L’exemple d’application utilise des identités gérées pour #define les ressources Azure lorsque l’instruction en haut du Managedfichier Program.cs a la valeur.The sample app uses Managed identities for Azure resources when the #define statement at the top of the Program.cs file is set to Managed.

Entrez le nom du coffre dans le fichier appSettings. JSON de l’application.Enter the vault name into the app's appsettings.json file. L’exemple d’application n’a pas besoin d’un ID d’application et d’un mot de Managed passe (clé secrète client) lorsqu’il est défini sur la version. vous pouvez donc ignorer ces entrées de configuration.The sample app doesn't require an Application ID and Password (Client Secret) when set to the Managed version, so you can ignore those configuration entries. L’application est déployée sur Azure et Azure authentifie l’application pour accéder à Azure Key Vault uniquement à l’aide du nom de coffre stocké dans le fichier appSettings. JSON .The app is deployed to Azure, and Azure authenticates the app to access Azure Key Vault only using the vault name stored in the appsettings.json file.

Déployez l’exemple d’application sur Azure App Service.Deploy the sample app to Azure App Service.

Une application déployée sur Azure App Service est automatiquement inscrite auprès de Azure AD lors de la création du service.An app deployed to Azure App Service is automatically registered with Azure AD when the service is created. Obtenez l’ID d’objet à partir du déploiement pour l’utiliser dans la commande suivante.Obtain the Object ID from the deployment for use in the following command. L’ID d’objet est affiché dans le Portail Azure sur le panneau d' identité du App service.The Object ID is shown in the Azure portal on the Identity panel of the App Service.

À l’aide de Azure CLI et de l’ID d’objet de l' list application get , fournissez l’application avec et les autorisations d’accès au coffre de clés:Using Azure CLI and the app's Object ID, provide the app with list and get permissions to access the key vault:

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

Redémarrez l’application à l’aide de Azure CLI, de PowerShell ou de l’portail Azure.Restart the app using Azure CLI, PowerShell, or the Azure portal.

L’exemple d’application:The sample app:

  • Crée une instance de la AzureServiceTokenProvider classe sans chaîne de connexion.Creates an instance of the AzureServiceTokenProvider class without a connection string. Lorsqu’une chaîne de connexion n’est pas fournie, le fournisseur tente d’obtenir un jeton d’accès à partir des identités gérées pour les ressources Azure.When a connection string isn't provided, the provider attempts to obtain an access token from Managed identities for Azure resources.
  • Une nouvelle KeyVaultClient est créée avec le AzureServiceTokenProvider rappel de jeton d’instance.A new KeyVaultClient is created with the AzureServiceTokenProvider instance token callback.
  • L' KeyVaultClient instance est utilisée avec une implémentation par défaut IKeyVaultSecretManager de qui charge toutes les valeurs de secret et remplace les doubles--tirets () par:des signes deux-points () dans les noms de clés.The KeyVaultClient instance is used with a default implementation of IKeyVaultSecretManager that loads all secret values and replaces double-dashes (--) with colons (:) in key names.
// using Microsoft.Azure.KeyVault;
// using Microsoft.Azure.Services.AppAuthentication;
// using Microsoft.Extensions.Configuration.AzureKeyVault;

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

                    var azureServiceTokenProvider = new AzureServiceTokenProvider();
                    var keyVaultClient = new KeyVaultClient(
                        new KeyVaultClient.AuthenticationCallback(
                            azureServiceTokenProvider.KeyVaultTokenCallback));

                    config.AddAzureKeyVault(
                        $"https://{builtConfig["KeyVaultName"]}.vault.azure.net/",
                        keyVaultClient,
                        new DefaultKeyVaultSecretManager());
            }
        })
        .UseStartup<Startup>();

Quand vous exécutez l’application, une page Web affiche les valeurs de secret chargées.When you run the app, a webpage shows the loaded secret values. Dans l’environnement de développement, les valeurs secrètes ont le _dev suffixe, car elles sont fournies par des secrets d’utilisateur.In the Development environment, secret values have the _dev suffix because they're provided by User Secrets. Dans l’environnement de production, les valeurs sont chargées avec le _prod suffixe, car elles sont fournies par Azure Key Vault.In the Production environment, the values load with the _prod suffix because they're provided by Azure Key Vault.

Si vous recevez une Access denied erreur, vérifiez que l’application est inscrite auprès de Azure ad et que vous avez accès au coffre de clés.If you receive an Access denied error, confirm that the app is registered with Azure AD and provided access to the key vault. Confirmez que vous avez redémarré le service dans Azure.Confirm that you've restarted the service in Azure.

Utiliser un préfixe de nom de cléUse a key name prefix

AddAzureKeyVaultfournit une surcharge qui accepte une implémentation de IKeyVaultSecretManager, qui vous permet de contrôler la façon dont les secrets de coffre de clés sont convertis en clés de configuration.AddAzureKeyVault provides an overload that accepts an implementation of IKeyVaultSecretManager, which allows you to control how key vault secrets are converted into configuration keys. Par exemple, vous pouvez implémenter l’interface pour charger les valeurs des secrets selon une valeur de préfixe que vous indiquez au démarrage de l’application.For example, you can implement the interface to load secret values based on a prefix value you provide at app startup. Cela vous permet, par exemple, de charger des secrets en fonction de la version de l’application.This allows you, for example, to load secrets based on the version of the app.

Avertissement

N’utilisez pas de préfixes sur les secrets de coffre de clés pour placer les secrets de plusieurs applications dans le même coffre de clés ou pour placer des secrets d'environnement (par exemple, des secrets de développement / de production) dans le même coffre.Don't use prefixes on key vault secrets to place secrets for multiple apps into the same key vault or to place environmental secrets (for example, development versus production secrets) into the same vault. Nous recommandons d'utiliser un coffre de clés distinct pour chaque application et chaque environnement de développement/production afin d’isoler les environnements d’application et ainsi de garantir le niveau de sécurité le plus élevé possible.We recommend that different apps and development/production environments use separate key vaults to isolate app environments for the highest level of security.

Dans l’exemple suivant, un secret est établi dans le coffre de clés (et à l’aide de l’outil secret Manager pour l' 5000-AppSecret environnement de développement) pour (les périodes ne sont pas autorisées dans les noms de secret de coffre de clés).In the following example, a secret is established in the key vault (and using the Secret Manager tool for the Development environment) for 5000-AppSecret (periods aren't allowed in key vault secret names). Ce secret représente un secret d’application pour la version 5.0.0.0 de l’application.This secret represents an app secret for version 5.0.0.0 of the app. Pour une autre version de l’application, 5.1.0.0, un secret est ajouté au coffre de clés (et à l’aide de l’outil 5100-AppSecretsecret Manager) pour.For another version of the app, 5.1.0.0, a secret is added to the key vault (and using the Secret Manager tool) for 5100-AppSecret. Chaque version de l’application charge sa valeur secrète avec version dans sa AppSecretconfiguration en tant que, en éliminant la version au fur et à mesure qu’elle charge le secret.Each app version loads its versioned secret value into its configuration as AppSecret, stripping off the version as it loads the secret.

AddAzureKeyVaultest appelé avec un personnalisé IKeyVaultSecretManager:AddAzureKeyVault is called with a custom IKeyVaultSecretManager:

// using System.Reflection;
// using Microsoft.Azure.KeyVault;
// using Microsoft.Azure.Services.AppAuthentication;
// using Microsoft.Extensions.Configuration;
// using Microsoft.Extensions.Configuration.AzureKeyVault;

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((context, config) =>
        {
            if (context.HostingEnvironment.IsProduction())
            {
                // The appVersion obtains the app version (5.0.0.0), which 
                // is set in the project file and obtained from the entry 
                // assembly. The versionPrefix holds the version without 
                // dot notation for the PrefixKeyVaultSecretManager.
                var appVersion = Assembly.GetEntryAssembly().GetName().Version.ToString();
                var versionPrefix = appVersion.Replace(".", string.Empty);

                var builtConfig = config.Build();

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

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

                    store.Close();
                }
            }
        })
        .UseStartup<Startup>();

L' IKeyVaultSecretManager implémentation réagit aux préfixes de version des secrets pour charger le secret approprié dans la configuration:The IKeyVaultSecretManager implementation reacts to the version prefixes of secrets to load the proper secret into configuration:

public class PrefixKeyVaultSecretManager : IKeyVaultSecretManager
{
    private readonly string _prefix;

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

    public bool Load(SecretItem secret)
    {
        // Load a vault secret when its secret name starts with the 
        // prefix. Other secrets won't be loaded.
        return secret.Identifier.Name.StartsWith(_prefix);
    }

    public string GetKey(SecretBundle secret)
    {
        // Remove the prefix from the secret name and replace two 
        // dashes in any name with the KeyDelimiter, which is the 
        // delimiter used in configuration (usually a colon). Azure 
        // Key Vault doesn't allow a colon in secret names.
        return secret.SecretIdentifier.Name
            .Substring(_prefix.Length)
            .Replace("--", ConfigurationPath.KeyDelimiter);
    }
}

La méthode Load est appelée par un algorithme de fourniture qui effectue une itération dans les secrets du coffre pour trouver ceux qui comportent le préfixe de la version.The Load method is called by a provider algorithm that iterates through the vault secrets to find the ones that have the version prefix. Quand un préfixe de version a été trouvé avec la méthode Load, l’algorithme utilise la méthode GetKey pour retourner le nom de configuration du nom du secret.When a version prefix is found with Load, the algorithm uses the GetKey method to return the configuration name of the secret name. Il supprime le préfixe de version du nom du secret et retourne le reste du nom du secret pour le charger dans les paires nom-valeur de configuration de l’application.It strips off the version prefix from the secret's name and returns the rest of the secret name for loading into the app's configuration name-value pairs.

Lorsque cette approche est implémentée:When this approach is implemented:

  1. Version de l’application spécifiée dans le fichier projet de l’application.The app's version specified in the app's project file. Dans l’exemple suivant, la version de l’application est définie 5.0.0.0sur:In the following example, the app's version is set to 5.0.0.0:

    <PropertyGroup>
      <Version>5.0.0.0</Version>
    </PropertyGroup>
    
  2. Vérifiez qu’une <UserSecretsId> propriété est présente dans le fichier projet de l’application, {GUID} où est un GUID fourni par l’utilisateur:Confirm that a <UserSecretsId> property is present in the app's project file, where {GUID} is a user-supplied GUID:

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

    Enregistrez les secrets suivants localement à l’aide de l' outil secret Manager:Save the following secrets locally with the Secret Manager tool:

    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 de Azure CLI suivantes:Secrets are saved in Azure Key Vault using the following Azure CLI commands:

    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 du coffre de clés sont chargés.When the app is run, the key vault secrets are loaded. Le secret de chaîne 5000-AppSecret de est mis en correspondance avec la version de l’application spécifiée dans le fichier projet5.0.0.0de l’application ().The string secret for 5000-AppSecret is matched to the app's version specified in the app's project file (5.0.0.0).

  5. La version 5000 (avec le tiret) est supprimée du nom de la clé.The version, 5000 (with the dash), is stripped from the key name. Tout au long de l’application, la lecture AppSecret de la configuration avec la clé charge la valeur du secret.Throughout the app, reading configuration with the key AppSecret loads the secret value.

  6. Si la version de l’application est modifiée dans le fichier 5.1.0.0 projet et que l’application est à nouveau exécutée, la valeur secrète renvoyée se trouve 5.1.0.0_secret_value_prod 5.1.0.0_secret_value_dev dans l’environnement de développement et en production.If the app's version is changed in the project file to 5.1.0.0 and the app is run again, the secret value returned is 5.1.0.0_secret_value_dev in the Development environment and 5.1.0.0_secret_value_prod in Production.

Notes

Vous pouvez également fournir votre propre implémentation KeyVaultClient à AddAzureKeyVault.You can also provide your own KeyVaultClient implementation to AddAzureKeyVault. Un client personnalisé permet de partager une seule instance du client dans l’application.A custom client permits sharing a single instance of the client across the app.

Lier un tableau à une classeBind an array to a class

Le fournisseur est en mesure de lire les valeurs de configuration dans un tableau pour la liaison à un tableau POCO.The provider is capable of reading configuration values into an array for binding to a POCO array.

Lors de la lecture à partir d’une source de configuration qui permet:aux clés de contenir des séparateurs de deux-points (), un segment de clé numérique est:0:utilisé :1:pour distinguer les clés qui composent un tableau (,,...When reading from a configuration source that allows keys to contain colon (:) separators, a numeric key segment is used to distinguish the keys that make up an array (:0:, :1:, … :{n}:).:{n}:). Pour plus d’informations, consultez Configuration: Liez un tableau à une classe.For more information, see Configuration: Bind an array to a class.

Les clés de Azure Key Vault ne peuvent pas utiliser un signe deux-points comme séparateur.Azure Key Vault keys can't use a colon as a separator. L’approche décrite dans cette rubrique utilise des doubles tirets--() comme séparateur pour les valeurs hiérarchiques (sections).The approach described in this topic uses double dashes (--) as a separator for hierarchical values (sections). Les clés de tableau sont stockées dans Azure Key Vault avec des doubles tirets et des--0--segments --1--de … clé numériques (,, --{n}--).Array keys are stored in Azure Key Vault with double dashes and numeric key segments (--0--, --1--, … --{n}--).

Examinez la configuration de fournisseur de journalisation Serilog suivante fournie par un fichier JSON.Examine the following Serilog logging provider configuration provided by a JSON file. Deux littéraux d’objet définis dans le WriteTo tableau reflètent deux récepteursSerilog, qui décrivent les destinations pour la sortie de journalisation:There are two object literals defined in the WriteTo array that reflect two Serilog sinks, which describe destinations for logging output:

"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 à deux tirets () et des segments numériques:The configuration shown in the preceding JSON file is stored in Azure Key Vault using double dash (--) notation and numeric segments:

CléKey ValueValue
Serilog--WriteTo--0--Name AzureTableStorage
Serilog--WriteTo--0--Args--storageTableName logs
Serilog--WriteTo--0--Args--connectionString DefaultEnd...ountKey=Eby8...GMGw==
Serilog--WriteTo--1--Name AzureDocumentDB
Serilog--WriteTo--1--Args--endpointUrl https://contoso.documents.azure.com:443
Serilog--WriteTo--1--Args--authorizationKey Eby8...GMGw==

Recharger les secretsReload secrets

Les secrets sont mis en cache jusqu'à ce que la méthode IConfigurationRoot.Reload() soit appelée.Secrets are cached until IConfigurationRoot.Reload() is called. Les secrets ayant expiré, désactivés et mis à jour dans le coffre de clés ne Reload sont pas respectés par l’application tant qu’elle n’est pas exécutée.Expired, disabled, and updated secrets in the key vault are not respected by the app until Reload is executed.

Configuration.Reload();

Secrets désactivés et arrivés à expirationDisabled and expired secrets

Les secrets désactivés et KeyVaultClientException arrivés à expiration lèvent un lors de l’exécution.Disabled and expired secrets throw a KeyVaultClientException at runtime. Pour empêcher l’application de se déclencher, fournissez la configuration à l’aide d’un autre fournisseur de configuration ou mettez à jour le secret désactivé ou expiré.To prevent the app from throwing, provide the configuration using a different configuration provider or update the disabled or expired secret.

Résolution des problèmesTroubleshoot

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.When the app fails to load configuration using the provider, an error message is written to the ASP.NET Core Logging infrastructure. Les conditions suivantes empêchent le chargement de la configuration :The following conditions will prevent configuration from loading:

  • L’application ou le certificat n’est pas configuré correctement dans Azure Active Directory.The app or certificate isn't configured correctly in Azure Active Directory.
  • Le coffre de clés n’existe pas dans Azure Key Vault.The key vault doesn't exist in Azure Key Vault.
  • L’application n’est pas autorisée à accéder au coffre de clés.The app isn't authorized to access the key vault.
  • La stratégie d’accès n’inclut pas les autorisations Get et List.The access policy doesn't include Get and List permissions.
  • Dans le coffre de clés, les données de configuration (paire nom-valeur) sont manquantes, désactivées, expirées ou incorrectement nommées.In the key vault, the configuration data (name-value pair) is incorrectly named, missing, disabled, or expired.
  • L’application a un nom de coffre de clésKeyVaultName(), un ID d'AzureADApplicationIdapplication Azure ad () ou une empreinteAzureADCertThumbprintde certificat Azure ad () incorrect.The app has the wrong key vault name (KeyVaultName), Azure AD Application Id (AzureADApplicationId), or Azure AD certificate thumbprint (AzureADCertThumbprint).
  • La clé de configuration (nom) est incorrecte dans l’application pour la valeur que vous essayez de charger.The configuration key (name) is incorrect in the app for the value you're trying to load.

Ressources supplémentairesAdditional resources