Poskytovatel konfigurace Azure Key Vault v ASP.NET CoreAzure Key Vault Configuration Provider in ASP.NET Core

Luke Latham a Andrew Stanton – sestryBy Luke Latham and Andrew Stanton-Nurse

Tento dokument vysvětluje, jak pomocí poskytovatele konfigurace Microsoft Azure Key Vault načíst hodnoty konfigurace aplikace z Azure Key Vault tajných klíčů.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 je cloudová služba, která pomáhá chránit kryptografické klíče a tajné klíče používané aplikacemi a službami.Azure Key Vault is a cloud-based service that assists in safeguarding cryptographic keys and secrets used by apps and services. Mezi běžné scénáře použití Azure Key Vault s ASP.NET Core aplikacemi patří:Common scenarios for using Azure Key Vault with ASP.NET Core apps include:

  • Řízení přístupu k citlivým datům konfigurace.Controlling access to sensitive configuration data.
  • Splnění požadavku na Standard FIPS 140-2 úrovně 2: ověřované moduly hardwarového zabezpečení (HSM) při ukládání konfiguračních dat.Meeting the requirement for FIPS 140-2 Level 2 validated Hardware Security Modules (HSM's) when storing configuration data.

Tento scénář je k dispozici pro aplikace cílené na ASP.NET Core 2,1 nebo novější.This scenario is available for apps that target ASP.NET Core 2.1 or later.

Zobrazit nebo stáhnout ukázkový kód (Jak stáhnout)View or download sample code (how to download)

BalíčkyPackages

Chcete-li použít poskytovatele konfigurace Azure Key Vault, přidejte odkaz na balíček do balíčku Microsoft. Extensions. Configuration. AzureKeyVault .To use the Azure Key Vault Configuration Provider, add a package reference to the Microsoft.Extensions.Configuration.AzureKeyVault package.

Pokud chcete přijmout spravované identity pro prostředky Azure , přidejte odkaz na balíček do balíčku Microsoft. Azure. Services. AppAuthentication .To adopt the Managed identities for Azure resources scenario, add a package reference to the Microsoft.Azure.Services.AppAuthentication package.

Poznámka

V době psaní nejnovější stabilní verze Microsoft.Azure.Services.AppAuthentication, verze 1.0.3, poskytuje podporu pro spravované identity přiřazené systémem.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. V balíčku 1.2.0-preview2 je dostupná podpora pro uživatelem přiřazené spravované identity .Support for user-assigned managed identities is available in the 1.2.0-preview2 package. Toto téma ukazuje použití identit spravovaných systémem a zadaná ukázková aplikace používá verzi 1.0.3 balíčku Microsoft.Azure.Services.AppAuthentication.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.

Ukázková aplikaceSample app

Ukázková aplikace běží v jednom ze dvou režimů určených příkazem #define v horní části souboru 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 – ukazuje použití Azure Key Vaultho ID klienta a certifikátu X. 509 pro přístup k tajným klíčům uloženým v 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. Tuto verzi ukázky můžete spustit z libovolného umístění, nasadit do Azure App Service nebo libovolného hostitele, který podporuje aplikaci 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.
  • Managed – ukazuje, jak používat spravované identity pro prostředky Azure k ověření aplikace pro Azure Key Vault s ověřováním Azure AD bez přihlašovacích údajů uložených v kódu nebo konfiguraci aplikace.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. Při ověřování identity pomocí spravovaných identit se nevyžaduje ID a heslo aplikace služby Azure AD (tajný klíč klienta).When using managed identities to authenticate, an Azure AD Application ID and Password (Client Secret) aren't required. Ukázková verze Managed se musí nasadit do Azure.The Managed version of the sample must be deployed to Azure. Postupujte podle pokynů v části použití spravovaných identit pro prostředky Azure .Follow the guidance in the Use the Managed identities for Azure resources section.

Další informace o tom, jak nakonfigurovat ukázkovou aplikaci pomocí direktiv preprocesoru (#define), najdete v tématu Úvod do ASP.NET Core.For more information on how to configure a sample app using preprocessor directives (#define), see Úvod do ASP.NET Core.

Tajné úložiště ve vývojovém prostředíSecret storage in the Development environment

Místně nastavte tajné klíče pomocí nástroje Správce tajnýchklíčů.Set secrets locally using the Secret Manager tool. Když je ukázková aplikace spuštěná na místním počítači ve vývojovém prostředí, tajné klíče se načtou z místního úložiště správce tajných klíčů.When the sample app runs on the local machine in the Development environment, secrets are loaded from the local Secret Manager store.

Nástroj Správce tajných klíčů vyžaduje vlastnost <UserSecretsId> v souboru projektu aplikace.The Secret Manager tool requires a <UserSecretsId> property in the app's project file. Nastavte hodnotu vlastnosti ({GUID}) na libovolný jedinečný identifikátor GUID:Set the property value ({GUID}) to any unique GUID:

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

Tajné kódy jsou vytvořeny jako páry název-hodnota.Secrets are created as name-value pairs. Hierarchické hodnoty (konfigurační oddíly) používají v názvech ASP.NET Core konfiguračních klíčů : (dvojtečku) jako oddělovač.Hierarchical values (configuration sections) use a : (colon) as a separator in ASP.NET Core configuration key names.

Správce tajného klíče se používá z příkazového prostředí otevřeného pro kořen obsahuprojektu, kde {SECRET NAME} je název a {SECRET VALUE} je hodnota: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}"

Spusťte následující příkazy v příkazovém prostředí z kořenu obsahu projektu pro nastavení tajných kódů pro ukázkovou aplikaci: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"

Pokud jsou tyto tajné klíče uložené v Azure Key Vault v tajném úložišti v produkčním prostředí s Azure Key Vault oddílem, _dev přípona se změní na _prod.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. Přípona poskytuje vizuální hromádku ve výstupu aplikace, která označuje zdroj hodnot konfigurace.The suffix provides a visual cue in the app's output indicating the source of the configuration values.

Tajné úložiště v produkčním prostředí pomocí Azure Key VaultSecret storage in the Production environment with Azure Key Vault

Pokyny poskytované rychlým startem: nastavení a načtení tajného klíče z Azure Key Vault pomocí rozhraní příkazového řádku Azure najdete zde shrnuté pro vytvoření Azure Key Vault a ukládání tajných kódů používaných ukázkovou aplikací.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. Další podrobnosti najdete v tématu.Refer to the topic for further details.

  1. Otevřete Azure Cloud Shell pomocí jedné z následujících metod v Azure Portal:Open Azure Cloud shell using any one of the following methods in the Azure portal:

    • Vyberte vyzkoušet v pravém horním rohu bloku kódu.Select Try It in the upper-right corner of a code block. V textovém poli použijte hledaný řetězec "Azure CLI".Use the search string "Azure CLI" in the text box.
    • Otevřete Cloud Shell v prohlížeči pomocí tlačítka pro spuštění Cloud Shell .Open Cloud Shell in your browser with the Launch Cloud Shell button.
    • V nabídce v pravém horním rohu Azure Portal vyberte tlačítko Cloud Shell .Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal.

    Další informace najdete v tématu rozhraní příkazového řádku Azure (CLI) a Přehled Azure Cloud Shell.For more information, see Azure Command-Line Interface (CLI) and Overview of Azure Cloud Shell.

  2. Pokud jste to ještě neověřili, přihlaste se pomocí příkazu az login.If you aren't already authenticated, sign in with the az login command.

  3. Vytvořte skupinu prostředků pomocí následujícího příkazu, kde {RESOURCE GROUP NAME} je název skupiny prostředků pro novou skupinu prostředků a {LOCATION} je oblast 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. Vytvořte Trezor klíčů ve skupině prostředků pomocí následujícího příkazu, kde {KEY VAULT NAME} je název nového trezoru klíčů a {LOCATION} je oblast 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. Vytvořte tajné klíče v trezoru klíčů jako páry název-hodnota.Create secrets in the key vault as name-value pairs.

    Názvy tajných kódů Azure Key Vault jsou omezené na alfanumerické znaky a pomlčky.Azure Key Vault secret names are limited to alphanumeric characters and dashes. Hierarchické hodnoty (konfigurační oddíly) používají jako oddělovač -- (dvě pomlčky).Hierarchical values (configuration sections) use -- (two dashes) as a separator. Dvojtečky, které se obvykle používají k vymezení oddílu z podklíče v konfiguraci ASP.NET Core, nejsou povoleny v tajných názvech trezoru klíčů.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. Proto se při načtení tajných klíčů do konfigurace aplikace použijí dvě pomlčky, které jsou v případě dvojtečky zahozeny.Therefore, two dashes are used and swapped for a colon when the secrets are loaded into the app's configuration.

    Následující tajné klíče jsou pro použití s ukázkovou aplikací.The following secrets are for use with the sample app. Mezi hodnoty patří _prod přípona pro odlišení od hodnot _dev přípony načtených ve vývojovém prostředí od uživatelských tajných kódů.The values include a _prod suffix to distinguish them from the _dev suffix values loaded in the Development environment from User Secrets. Nahraďte {KEY VAULT NAME} názvem trezoru klíčů, který jste vytvořili v předchozím kroku: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"
    

Použití ID aplikace a certifikátu X. 509 pro aplikace hostované mimo AzureUse Application ID and X.509 certificate for non-Azure-hosted apps

Nakonfigurujte Azure AD, Azure Key Vault a aplikaci tak, aby používala Azure Active Directory ID aplikace a certifikát X. 509 k ověřování u trezoru klíčů, když je aplikace hostovaná mimo 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. Další informace najdete v tématu o klíčích, tajných klíčích a certifikátech.For more information, see About keys, secrets, and certificates.

Poznámka

I když se pro aplikace hostované v Azure podporuje certifikát s ID aplikace a X. 509, doporučujeme při hostování aplikace v Azure používat spravované identity pro prostředky 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. Spravované identity nevyžadují uložení certifikátu v aplikaci nebo ve vývojovém prostředí.Managed identities don't require storing a certificate in the app or in the development environment.

Ukázková aplikace používá ID aplikace a certifikát X. 509, pokud je příkaz #define v horní části souboru program.cs nastavený na Certificate.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. Vytvořte certifikát PKCS # 12 ( . pfx).Create a PKCS#12 archive (.pfx) certificate. Mezi možnosti vytváření certifikátů patří Makecert ve Windows a OpenSSL.Options for creating certificates include MakeCert on Windows and OpenSSL.
  2. Nainstalujte certifikát do osobního úložiště certifikátů aktuálního uživatele.Install the certificate into the current user's personal certificate store. Označení klíče jako exportovatelných je volitelné.Marking the key as exportable is optional. Poznamenejte si kryptografický otisk certifikátu, který se používá později v tomto procesu.Note the certificate's thumbprint, which is used later in this process.
  3. Exportujte certifikát PKCS # 12 ( . pfx) jako certifikát kódovaný v kódování DER ( . cer).Export the PKCS#12 archive (.pfx) certificate as a DER-encoded certificate (.cer).
  4. Zaregistrujte aplikaci ve službě Azure AD (Registrace aplikací).Register the app with Azure AD (App registrations).
  5. Nahrajte certifikát s kódováním DER ( . cer) do Azure AD:Upload the DER-encoded certificate (.cer) to Azure AD:
    1. Vyberte aplikaci ve službě Azure AD.Select the app in Azure AD.
    2. Přejděte na certifikáty & tajnýchkódů.Navigate to Certificates & secrets.
    3. Vyberte Odeslat certifikát pro nahrání certifikátu, který obsahuje veřejný klíč.Select Upload certificate to upload the certificate, which contains the public key. Je přijatelný certifikát . cer, . pemnebo . CRT .A .cer, .pem, or .crt certificate is acceptable.
  6. V souboru appSettings. JSON aplikace uložte název trezoru klíčů, ID aplikace a kryptografický otisk certifikátu.Store the key vault name, Application ID, and certificate thumbprint in the app's appsettings.json file.
  7. V Azure Portal přejděte na trezory klíčů .Navigate to Key vaults in the Azure portal.
  8. V části provozní prostředí s Azure Key Vault vyberte Trezor klíčů, který jste vytvořili v tajném úložišti.Select the key vault that you created in the Secret storage in the Production environment with Azure Key Vault section.
  9. Vyberte zásady přístupu.Select Access policies.
  10. Vyberte Přidat nový.Select Add new.
  11. Vyberte Vybrat objekt zabezpečení a vyberte zaregistrovanou aplikaci podle názvu.Select Select principal and select the registered app by name. Vyberte tlačítko Vybrat .Select the Select button.
  12. Otevřete oprávnění tajného klíče a poskytněte aplikaci oprávnění získat a vytvořit seznam .Open Secret permissions and provide the app with Get and List permissions.
  13. Vyberte OK.Select OK.
  14. Vyberte Uložit.Select Save.
  15. Nasaďte aplikaci.Deploy the app.

Ukázková aplikace Certificate získá své konfigurační hodnoty z IConfigurationRoot se stejným názvem, jako má název tajného kódu:The Certificate sample app obtains its configuration values from IConfigurationRoot with the same name as the secret name:

  • Hodnoty, které nejsou hierarchicky: hodnota pro SecretName je získána pomocí config["SecretName"].Non-hierarchical values: The value for SecretName is obtained with config["SecretName"].
  • Hierarchické hodnoty (oddíly): použijte notaci : (dvojtečky) nebo metodu rozšíření GetSection.Hierarchical values (sections): Use : (colon) notation or the GetSection extension method. K získání hodnoty konfigurace použijte některý z těchto přístupů:Use either of these approaches to obtain the configuration value:
    • config["Section:SecretName"]
    • config.GetSection("Section")["SecretName"]

Certifikát X. 509 spravuje operační systém.The X.509 certificate is managed by the OS. Aplikace volá AddAzureKeyVault s hodnotami poskytnutými souborem 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>();

Příklady hodnot:Example values:

  • Název trezoru klíčů: contosovaultKey vault name: contosovault
  • ID aplikace: 627e911e-43cc-61d4-992e-12db9c81b413Application ID: 627e911e-43cc-61d4-992e-12db9c81b413
  • Kryptografický otisk certifikátu: fe14593dd66b2406c5269d742d04b6e1ab03adb1Certificate thumbprint: fe14593dd66b2406c5269d742d04b6e1ab03adb1

appSettings. JSON:appsettings.json:

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

Když aplikaci spouštíte, zobrazí se na webové stránce načtené tajné hodnoty.When you run the app, a webpage shows the loaded secret values. Ve vývojovém prostředí se tajné hodnoty načítají s příponou _dev.In the Development environment, secret values load with the _dev suffix. V produkčním prostředí se hodnoty načítají s příponou _prod.In the Production environment, the values load with the _prod suffix.

Použití spravovaných identit pro prostředky AzureUse Managed identities for Azure resources

Aplikace nasazená do Azure může využít výhod spravovaných identit pro prostředky Azure, což umožňuje Azure Key Vault aplikacím ověřování pomocí ověřování Azure AD bez přihlašovacích údajů (ID aplikace a heslo/tajný klíč klienta). Uloženo v aplikaci.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.

Ukázková aplikace používá spravované identity pro prostředky Azure, pokud je příkaz #define v horní části souboru program.cs nastavený na Managed.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.

Do souboru appSettings. JSON aplikace zadejte název trezoru.Enter the vault name into the app's appsettings.json file. Ukázková aplikace nevyžaduje ID aplikace a heslo (tajný klíč klienta), pokud je nastavená na verzi Managed, takže tyto položky konfigurace můžete ignorovat.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. Aplikace je nasazená do Azure a Azure ověřuje aplikaci pro přístup k Azure Key Vault jenom pomocí názvu trezoru uloženého v souboru 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.

Nasaďte ukázkovou aplikaci do Azure App Service.Deploy the sample app to Azure App Service.

Aplikace nasazená do Azure App Service se při vytvoření služby automaticky zaregistruje ve službě Azure AD.An app deployed to Azure App Service is automatically registered with Azure AD when the service is created. Získejte ID objektu z nasazení pro použití v následujícím příkazu.Obtain the Object ID from the deployment for use in the following command. ID objektu se zobrazí v Azure Portal na panelu identita App Service.The Object ID is shown in the Azure portal on the Identity panel of the App Service.

Pomocí rozhraní příkazového řádku Azure a ID objektu aplikace poskytněte aplikaci list a get oprávnění pro přístup k trezoru klíčů: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

Restartujte aplikaci pomocí rozhraní příkazového řádku Azure CLI, PowerShellu nebo Azure Portal.Restart the app using Azure CLI, PowerShell, or the Azure portal.

Ukázková aplikace:The sample app:

  • Vytvoří instanci třídy AzureServiceTokenProvider bez připojovacího řetězce.Creates an instance of the AzureServiceTokenProvider class without a connection string. Pokud není zadaný připojovací řetězec, pokusí se zprostředkovatel získat přístupový token ze spravovaných identit pro prostředky Azure.When a connection string isn't provided, the provider attempts to obtain an access token from Managed identities for Azure resources.
  • Nový KeyVaultClient se vytvoří pomocí zpětného volání tokenu instance AzureServiceTokenProvider.A new KeyVaultClient is created with the AzureServiceTokenProvider instance token callback.
  • Instance KeyVaultClient se používá s výchozí implementací IKeyVaultSecretManager, která načte všechny tajné hodnoty a nahradí dvojité spojovníky (--) dvojtečkami (:) v názvech klíčů.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>();

Ukázková hodnota názvu trezoru klíčů: contosovaultKey vault name example value: contosovault

appSettings. JSON:appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

Když aplikaci spouštíte, zobrazí se na webové stránce načtené tajné hodnoty.When you run the app, a webpage shows the loaded secret values. Ve vývojovém prostředí mají tajné hodnoty příponu _dev, protože jsou poskytovány uživatelskými tajemstvími.In the Development environment, secret values have the _dev suffix because they're provided by User Secrets. V produkčním prostředí se hodnoty načítají s příponou _prod, protože jsou k dispozici v Azure Key Vault.In the Production environment, the values load with the _prod suffix because they're provided by Azure Key Vault.

Pokud se zobrazí chyba Access denied, potvrďte, že je aplikace zaregistrovaná ve službě Azure AD a poskytuje přístup k trezoru klíčů.If you receive an Access denied error, confirm that the app is registered with Azure AD and provided access to the key vault. Potvrďte, že jste službu restartovali v Azure.Confirm that you've restarted the service in Azure.

Informace o používání zprostředkovatele se spravovanou identitou a kanálem Azure DevOps najdete v tématu vytvoření připojení služby Azure Resource Manager k virtuálnímu počítači s identitou spravované služby.For information on using the provider with a managed identity and an Azure DevOps pipeline, see Create an Azure Resource Manager service connection to a VM with a managed service identity.

Použít předponu názvu klíčeUse a key name prefix

AddAzureKeyVault poskytuje přetížení, které přijímá implementaci IKeyVaultSecretManager, což vám umožní řídit, jak se tajné klíče trezoru klíčů převádějí do konfiguračních klíčů.AddAzureKeyVault provides an overload that accepts an implementation of IKeyVaultSecretManager, which allows you to control how key vault secrets are converted into configuration keys. Například můžete implementovat rozhraní pro načtení tajných hodnot na základě hodnoty předpony, kterou zadáte při spuštění aplikace.For example, you can implement the interface to load secret values based on a prefix value you provide at app startup. To vám umožní například načíst tajné kódy na základě verze aplikace.This allows you, for example, to load secrets based on the version of the app.

Varování

Nepoužívejte předpony pro tajné klíče trezoru klíčů k umístění tajných kódů pro několik aplikací do stejného trezoru klíčů nebo k umístění tajných kódů prostředí (například vývoj a produkčních tajemství) do stejného trezoru.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. Doporučujeme, aby různé aplikace a vývojové a provozní prostředí používaly samostatné trezory klíčů k izolaci aplikačních prostředí na nejvyšší úrovni zabezpečení.We recommend that different apps and development/production environments use separate key vaults to isolate app environments for the highest level of security.

V následujícím příkladu se v trezoru klíčů vytvoří tajný kód (a pomocí nástroje Správce tajných klíčů pro vývojové prostředí) pro 5000-AppSecret (období nejsou v tajných názvech trezoru klíčů povolená).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). Tento tajný klíč představuje tajný klíč aplikace pro 5.0.0.0 verze aplikace.This secret represents an app secret for version 5.0.0.0 of the app. V případě jiné verze aplikace se 5.1.0.0 do trezoru klíčů přidá tajný kód (a pomocí nástroje Správce tajného klíče) pro 5100-AppSecret.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. Každá verze aplikace načte svou tajnou hodnotu do své konfigurace jako AppSecret. při načítání tajného kódu se vymění jeho verze.Each app version loads its versioned secret value into its configuration as AppSecret, stripping off the version as it loads the secret.

AddAzureKeyVault se volá s vlastním 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>();

Implementace IKeyVaultSecretManager reaguje na předpony verze tajných klíčů, aby se do konfigurace načetl správný tajný kód: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);
    }
}

Metoda Load je volána algoritmem poskytovatele, který prochází tajné klíče trezoru, aby bylo možné najít ty, které mají předponu verze.The Load method is called by a provider algorithm that iterates through the vault secrets to find the ones that have the version prefix. Pokud je nalezena předpona verze s Load, algoritmus používá metodu GetKey k vrácení názvu konfigurace tajného názvu.When a version prefix is found with Load, the algorithm uses the GetKey method to return the configuration name of the secret name. Oddělí předponu verze z názvu tajného klíče a vrátí zbytek tajného názvu pro načtení do dvojice název-hodnota konfigurace aplikace.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.

Při implementaci tohoto přístupu:When this approach is implemented:

  1. Verze aplikace zadaná v souboru projektu aplikaceThe app's version specified in the app's project file. V následujícím příkladu je verze aplikace nastavená na 5.0.0.0:In the following example, the app's version is set to 5.0.0.0:

    <PropertyGroup>
      <Version>5.0.0.0</Version>
    </PropertyGroup>
    
  2. Ověřte, že se v souboru projektu aplikace nachází vlastnost <UserSecretsId>, kde {GUID} je uživatelem zadaný identifikátor GUID: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>
    

    Následující tajná klíčová okna uložte místně pomocí nástroje Správce tajných klíčů: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. Tajné kódy se ukládají v Azure Key Vault pomocí následujících příkazů Azure CLI: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. Po spuštění aplikace se načtou tajné klíče trezoru klíčů.When the app is run, the key vault secrets are loaded. Řetězec tajného kódu 5000-AppSecret se shoduje s verzí aplikace zadanou v souboru projektu aplikace (5.0.0.0).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. Verze 5000 (s pomlčkou), je z názvu klíče odstraněna.The version, 5000 (with the dash), is stripped from the key name. V celé aplikaci čtení konfigurace pomocí klíče AppSecret načte tajnou hodnotu.Throughout the app, reading configuration with the key AppSecret loads the secret value.

  6. Pokud se verze aplikace v souboru projektu změní na 5.1.0.0 a aplikace se spustí znovu, vrátí se hodnota tajného klíče 5.1.0.0_secret_value_dev ve vývojovém prostředí a 5.1.0.0_secret_value_prod v produkčním prostředí.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.

Poznámka

Můžete také poskytnout vlastní implementaci KeyVaultClient pro AddAzureKeyVault.You can also provide your own KeyVaultClient implementation to AddAzureKeyVault. Vlastní klient umožňuje v rámci aplikace sdílet jednu instanci klienta.A custom client permits sharing a single instance of the client across the app.

Vazba pole na tříduBind an array to a class

Zprostředkovatel je schopný číst konfigurační hodnoty do pole pro vazbu k poli POCO.The provider is capable of reading configuration values into an array for binding to a POCO array.

Při čtení ze zdroje konfigurace, který umožňuje klíčům obsahovat oddělovače dvojtečky (:), se pro odlišení klíčů, které tvoří pole (:0:, :1:, používá číselný segment klíče...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}:). Další informace najdete v tématu Konfigurace: vytvoření vazby pole ke třídě.For more information, see Configuration: Bind an array to a class.

Klíče Azure Key Vault nemůžou jako oddělovač použít dvojtečku.Azure Key Vault keys can't use a colon as a separator. Přístup popsaný v tomto tématu používá dvojité pomlčky (--) jako oddělovač pro hierarchické hodnoty (oddíly).The approach described in this topic uses double dashes (--) as a separator for hierarchical values (sections). Klíče polí jsou uloženy v Azure Key Vault s dvojitými pomlčkami a segmenty číselných klíčů (--0--, --1--, … --{n}--).Array keys are stored in Azure Key Vault with double dashes and numeric key segments (--0--, --1--, … --{n}--).

Projděte si následující konfiguraci poskytovatele protokolování Serilog poskytnutou souborem JSON.Examine the following Serilog logging provider configuration provided by a JSON file. V poli WriteTo jsou definovány dva literály objektů, které odrážejí dvě Serilog jímky, které popisují umístění pro výstup protokolování: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=="
      }
    }
  ]
}

Konfigurace zobrazená v předchozím souboru JSON je uložená v Azure Key Vault s použitím dvojité pomlčky (--) Notation a číselných segmentů:The configuration shown in the preceding JSON file is stored in Azure Key Vault using double dash (--) notation and numeric segments:

KeyKey HodnotaValue
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==

Znovu načíst tajné kódyReload secrets

Tajné kódy jsou ukládány do mezipaměti, dokud se nevolá IConfigurationRoot.Reload().Secrets are cached until IConfigurationRoot.Reload() is called. Aplikace nedodržuje, zakázala a aktualizovala tajné klíče v trezoru klíčů, dokud se neprovede Reload.Expired, disabled, and updated secrets in the key vault are not respected by the app until Reload is executed.

Configuration.Reload();

Zakázané a neprošlé tajné klíčeDisabled and expired secrets

Zakázané a neplatné tajné klíče vyvolají za běhu KeyVaultClientException.Disabled and expired secrets throw a KeyVaultClientException at runtime. Chcete-li zabránit tomu, aby se aplikace vyvolala, zadejte konfiguraci pomocí jiného poskytovatele konfigurace nebo aktualizujte zakázané nebo neprošlé tajné klíče.To prevent the app from throwing, provide the configuration using a different configuration provider or update the disabled or expired secret.

Řešení potížíTroubleshoot

Když se aplikaci nepovede načíst konfiguraci pomocí poskytovatele, do ASP.NET Core infrastruktury protokolováníse zapíše chybová zpráva.When the app fails to load configuration using the provider, an error message is written to the ASP.NET Core Logging infrastructure. Následující podmínky zabrání načtení konfigurace:The following conditions will prevent configuration from loading:

  • Aplikace nebo certifikát nejsou správně nakonfigurované v Azure Active Directory.The app or certificate isn't configured correctly in Azure Active Directory.
  • Trezor klíčů neexistuje v Azure Key Vault.The key vault doesn't exist in Azure Key Vault.
  • Aplikace nemá autorizaci pro přístup k trezoru klíčů.The app isn't authorized to access the key vault.
  • Zásady přístupu nezahrnují oprávnění Get a List.The access policy doesn't include Get and List permissions.
  • V trezoru klíčů jsou konfigurační data (dvojice název-hodnota) nesprávně pojmenována, chybí, zakázána nebo vypršela její platnost.In the key vault, the configuration data (name-value pair) is incorrectly named, missing, disabled, or expired.
  • Aplikace má nesprávný název trezoru klíčů (KeyVaultName), ID aplikace Azure AD (AzureADApplicationId) nebo kryptografický otisk certifikátu Azure AD (AzureADCertThumbprint).The app has the wrong key vault name (KeyVaultName), Azure AD Application Id (AzureADApplicationId), or Azure AD certificate thumbprint (AzureADCertThumbprint).
  • Konfigurační klíč (Name) je v aplikaci v případě hodnoty, kterou se pokoušíte načíst, nesprávný.The configuration key (name) is incorrect in the app for the value you're trying to load.

Další zdrojeAdditional resources