Azure Key Vault Konfigurations Anbieters in ASP.net CoreAzure Key Vault Configuration Provider in ASP.NET Core

Von Andrew Stanton-NurseBy Andrew Stanton-Nurse

In diesem Dokument wird erläutert, wie Sie den Microsoft Azure Key Vault -Konfigurations Anbieter verwenden, um App-Konfigurationswerte aus Azure Key Vault geheimen Schlüsseln zu laden.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 ist ein cloudbasierter Dienst, der Ihnen hilft, kryptografische Schlüssel und Geheimnisse zu schützen, die von apps und Diensten verwendet werden.Azure Key Vault is a cloud-based service that assists in safeguarding cryptographic keys and secrets used by apps and services. Gängige Szenarien für die Verwendung von Azure Key Vault mit ASP.net Core-apps sind:Common scenarios for using Azure Key Vault with ASP.NET Core apps include:

  • Steuern des Zugriffs auf vertrauliche Konfigurationsdaten.Controlling access to sensitive configuration data.
  • Erfüllen der Anforderung für die Überprüfung der Hardware Sicherheitsmodule (HSM) von PPS 140-2 Level 2 bei der Speicherung von Konfigurationsdaten.Meeting the requirement for FIPS 140-2 Level 2 validated Hardware Security Modules (HSM's) when storing configuration data.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

PaketePackages

Fügen Sie einen Paket Verweis auf die Microsoft.Extensions.Config-urung hinzu. Azurekeyvault -Paket.Add a package reference to the Microsoft.Extensions.Configuration.AzureKeyVault package.

Beispiel-AppSample app

Die Beispiel-APP wird in einem von zwei Modi ausgeführt, die durch die- #define Anweisung am Anfang der Program.cs -Datei bestimmt werden:The sample app runs in either of two modes determined by the #define statement at the top of the Program.cs file:

  • Certificate: Veranschaulicht die Verwendung einer Azure Key Vault Client-ID und eines X. 509-Zertifikats für den Zugriff auf in Azure Key Vault gespeicherte Geheimnisse.Certificate: Demonstrates the use of an Azure Key Vault Client ID and X.509 certificate to access secrets stored in Azure Key Vault. Diese Version des Beispiels kann von einem beliebigen Speicherort aus ausgeführt werden, auf Azure App Service oder auf allen Hosts bereitgestellt werden, die eine ASP.net Core-App bereitstellen können.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: Veranschaulicht, wie verwaltete Identitäten für Azure-Ressourcen verwendet werden, um die APP für die Azure Key Vault mit Azure AD Authentifizierung ohne Anmelde Informationen zu authentifizieren, die im Code oder in der Konfiguration der APP gespeichert sind.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. Wenn Sie für die Authentifizierung verwaltete Identitäten verwenden, sind keine Azure AD Anwendungs-ID und kein Kennwort (geheimer Client Schlüssel) erforderlich.When using managed identities to authenticate, an Azure AD Application ID and Password (Client Secret) aren't required. Die Managed Version des Beispiels muss in Azure bereitgestellt werden.The Managed version of the sample must be deployed to Azure. Befolgen Sie die Anweisungen im Abschnitt Verwenden der verwalteten Identitäten für Azure-Ressourcen .Follow the guidance in the Use the Managed identities for Azure resources section.

Weitere Informationen zum Konfigurieren einer Beispiel-App mithilfe von Präprozessordirektiven ( #define ) finden Sie unter Einführung in ASP.NET Core .For more information on how to configure a sample app using preprocessor directives (#define), see Einführung in ASP.NET Core.

Speicherung von geheimen Schlüsseln in der EntwicklungsumgebungSecret storage in the Development environment

Legen Sie Geheimnisse mit dem Geheimnis-Manager-Toollokal fest.Set secrets locally using the Secret Manager tool. Wenn die Beispiel-App auf dem lokalen Computer in der Entwicklungsumgebung ausgeführt wird, werden Geheimnisse aus dem lokalen Speicher des geheimen Haupt Schlüssels geladen.When the sample app runs on the local machine in the Development environment, secrets are loaded from the local Secret Manager store.

Das Secret Manager-Tool erfordert eine <UserSecretsId> Eigenschaft in der Projektdatei der app.The Secret Manager tool requires a <UserSecretsId> property in the app's project file. Legen Sie den-Eigenschafts Wert ( {GUID} ) auf eine eindeutige GUID fest:Set the property value ({GUID}) to any unique GUID:

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

Geheimnisse werden als Name-Wert-Paare erstellt.Secrets are created as name-value pairs. Hierarchische Werte (Konfigurations Abschnitte) verwenden einen : (Doppelpunkt) als Trennzeichen in ASP.net Core Namen von Konfigurations Schlüsseln.Hierarchical values (configuration sections) use a : (colon) as a separator in ASP.NET Core configuration key names.

Der geheime Manager wird von einer Befehlsshell verwendet, die für den InhaltsStamm des Projekts geöffnet ist, wobei {SECRET NAME} der Name und {SECRET VALUE} der Wert ist: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}"

Führen Sie die folgenden Befehle in einer Befehlsshell aus dem Inhalts Stamm des Projekts aus, um die geheimen Schlüssel für die Beispiel-App festzulegen: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"

Wenn diese Geheimnisse in Azure Key Vault im geheimen Speicher in der Produktionsumgebung mit Azure Key Vault gespeichert werden, wird das _dev Suffix in geändert _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. Das-Suffix bietet einen visuellen Hinweis in der APP-Ausgabe, die die Quelle der Konfigurationswerte anzeigt.The suffix provides a visual cue in the app's output indicating the source of the configuration values.

Geheimer Speicher in der Produktionsumgebung mit Azure Key VaultSecret storage in the Production environment with Azure Key Vault

Die Anweisungen im Schnellstart: festlegen und Abrufen eines Geheimnisses aus Azure Key Vault mithilfe Azure CLI Themas werden hier zusammengefasst, um eine Azure Key Vault zu erstellen und Geheimnisse zu speichern, die von der Beispiel-App verwendet werden.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. Weitere Informationen finden Sie im Thema.Refer to the topic for further details.

  1. Öffnen Sie Azure Cloud Shell, indem Sie eine der folgenden Methoden in der Azure-Portalverwenden:Open Azure Cloud shell using any one of the following methods in the Azure portal:

    • Klicken Sie in der rechten oberen Ecke eines Codeblocks auf Ausprobieren.Select Try It in the upper-right corner of a code block. Verwenden Sie die Such Zeichenfolge "Azure CLI" im Textfeld.Use the search string "Azure CLI" in the text box.
    • Öffnen Sie Cloud Shell in Ihrem Browser mit der Schaltfläche Start Cloud Shell .Open Cloud Shell in your browser with the Launch Cloud Shell button.
    • Wählen Sie im Menü in der oberen rechten Ecke des Azure-Portal die Schaltfläche Cloud Shell aus.Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal.

    Weitere Informationen finden Sie unter Azure CLI und Übersicht über Azure Cloud Shell.For more information, see Azure CLI and Overview of Azure Cloud Shell.

  2. Wenn Sie nicht bereits authentifiziert sind, melden Sie sich mit dem az login Befehl an.If you aren't already authenticated, sign in with the az login command.

  3. Erstellen Sie eine Ressourcengruppe mit dem folgenden Befehl, wobei {RESOURCE GROUP NAME} der Name der Ressourcengruppe für die neue Ressourcengruppe und {LOCATION} die Azure-Region (Datacenter) ist: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. Erstellen Sie mit dem folgenden Befehl einen Schlüssel Tresor in der Ressourcengruppe, wobei {KEY VAULT NAME} der Name für den neuen Schlüssel Tresor und {LOCATION} die Azure-Region (Datacenter) ist: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. Erstellen Sie Geheimnisse im Schlüssel Tresor als Name-Wert-Paare.Create secrets in the key vault as name-value pairs.

    Azure Key Vault geheimen Namen sind auf alphanumerische Zeichen und Bindestriche beschränkt.Azure Key Vault secret names are limited to alphanumeric characters and dashes. Hierarchische Werte (Konfigurations Abschnitte) verwenden -- (zwei Bindestriche) als Trennzeichen.Hierarchical values (configuration sections) use -- (two dashes) as a separator. Doppelpunkte, die normalerweise verwendet werden, um einen Abschnitt von einem Unterschlüssel in ASP.net Core Konfigurationzu begrenzen, sind in Key Vault-Geheimnis Namen nicht zulässig.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. Aus diesem Grund werden zwei Bindestriche verwendet und für einen Doppelpunkt getauscht, wenn die geheimen Schlüssel in die Konfiguration der App geladen werden.Therefore, two dashes are used and swapped for a colon when the secrets are loaded into the app's configuration.

    Die folgenden geheimen Schlüssel sind für die Verwendung mit der Beispiel-App vorgesehen.The following secrets are for use with the sample app. Die Werte enthalten ein _prod Suffix, um Sie von den suffixwerten zu unterscheiden, die _dev in der Entwicklungsumgebung von Benutzer Geheimnissen geladen werden.The values include a _prod suffix to distinguish them from the _dev suffix values loaded in the Development environment from User Secrets. Ersetzen {KEY VAULT NAME} Sie durch den Namen des Schlüssel Tresors, den Sie im vorherigen Schritt erstellt haben: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"
    

Verwenden Sie die Anwendungs-ID und das X. 509-Zertifikat für nicht in Azure gehostete Apps.Use Application ID and X.509 certificate for non-Azure-hosted apps

Konfigurieren Sie Azure AD, Azure Key Vault und die APP für die Verwendung einer Azure Active Directory Anwendungs-ID und eines X. 509-Zertifikats, um sich bei einem Schlüssel Tresor zu authentifizieren, Wenn die APP außerhalb von Azure gehostet wird.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. Weitere Informationen finden Sie im Artikel Informationen zu Schlüsseln, Geheimnissen und Zertifikaten.For more information, see About keys, secrets, and certificates.

Hinweis

Obwohl die Verwendung einer Anwendungs-ID und eines X. 509-Zertifikats für in Azure gehostete Apps unterstützt wird, empfiehlt es sich, beim Hosten einer APP in Azure verwaltete Identitäten für Azure-Ressourcen zu verwenden.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. Für verwaltete Identitäten ist das Speichern eines Zertifikats in der APP oder in der Entwicklungsumgebung nicht erforderlich.Managed identities don't require storing a certificate in the app or in the development environment.

Die Beispiel-App verwendet eine Anwendungs-ID und ein X. 509-Zertifikat, wenn die- #define Anweisung am Anfang der Program.cs -Datei auf festgelegt ist 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. Erstellen Sie ein PKCS # 12-Archiv Zertifikat (. pfx).Create a PKCS#12 archive (.pfx) certificate. Optionen zum Erstellen von Zertifikaten sind Makecert unter Windows und OpenSSL.Options for creating certificates include MakeCert on Windows and OpenSSL.
  2. Installieren Sie das Zertifikat im persönlichen Zertifikat Speicher des aktuellen Benutzers.Install the certificate into the current user's personal certificate store. Das Markieren des Schlüssels als exportierbar ist optional.Marking the key as exportable is optional. Notieren Sie den Fingerabdruck des Zertifikats, der später in diesem Prozess verwendet wird.Note the certificate's thumbprint, which is used later in this process.
  3. Exportieren Sie das PKCS # 12-Archiv Zertifikat (. pfx) als ein-codiertes Zertifikat (. CER).Export the PKCS#12 archive (.pfx) certificate as a DER-encoded certificate (.cer).
  4. Registrieren Sie die APP bei Azure AD (App-Registrierungen).Register the app with Azure AD (App registrations).
  5. Laden Sie das der-codierte Zertifikat (. CER) in Azure AD hoch:Upload the DER-encoded certificate (.cer) to Azure AD:
    1. Wählen Sie die app in Azure AD aus.Select the app in Azure AD.
    2. Navigieren Sie zu Zertifikate & Geheimnissen.Navigate to Certificates & secrets.
    3. Wählen Sie Zertifikat hochladen aus, um das Zertifikat hochzuladen, das den öffentlichen Schlüssel enthält.Select Upload certificate to upload the certificate, which contains the public key. Ein CER-, PEM-oder CRT -Zertifikat ist akzeptabel.A .cer, .pem, or .crt certificate is acceptable.
  6. Speichern Sie den Key Vault-Namen, die Anwendungs-ID und den Zertifikat Fingerabdruck im appsettings.js der app in der Datei.Store the key vault name, Application ID, and certificate thumbprint in the app's appsettings.json file.
  7. Navigieren Sie in der Azure-Portal zu Schlüssel Tresoren .Navigate to Key vaults in the Azure portal.
  8. Wählen Sie den Schlüssel Tresor aus, den Sie im Abschnitt " Geheimnis Speicher in der Produktionsumgebung mit Azure Key Vault " erstellt haben.Select the key vault that you created in the Secret storage in the Production environment with Azure Key Vault section.
  9. Klicken Sie auf Zugriffsrichtlinien.Select Access policies.
  10. Wählen Sie Zugriffsrichtlinie hinzufügen aus.Select Add Access Policy.
  11. Öffnen Sie geheime Berechtigungen , und stellen Sie der APP die Berechtigungen Get und List bereit.Open Secret permissions and provide the app with Get and List permissions.
  12. Wählen Sie Prinzipal auswählen , und wählen Sie die registrierte App nach Name aus.Select Select principal and select the registered app by name. Wählen Sie die Schaltfläche Auswählen aus.Select the Select button.
  13. Klicken Sie auf OK.Select OK.
  14. Wählen Sie Speichern aus.Select Save.
  15. Stellen Sie die App bereit.Deploy the app.

Die Certificate Beispiel-APP erhält Ihre Konfigurationswerte aus IConfigurationRoot dem gleichen Namen wie der geheime Name:The Certificate sample app obtains its configuration values from IConfigurationRoot with the same name as the secret name:

  • Nicht hierarchische Werte: der Wert für SecretName wird mit abgerufen config["SecretName"] .Non-hierarchical values: The value for SecretName is obtained with config["SecretName"].
  • Hierarchische Werte (Abschnitte): Verwenden Sie : die Notation (Doppelpunkt) oder die GetSection Erweiterungsmethode.Hierarchical values (sections): Use : (colon) notation or the GetSection extension method. Verwenden Sie einen dieser Ansätze zum Abrufen des Konfigurations Werts:Use either of these approaches to obtain the configuration value:
    • config["Section:SecretName"]
    • config.GetSection("Section")["SecretName"]

Das X. 509-Zertifikat wird vom Betriebssystem verwaltet.The X.509 certificate is managed by the OS. Die App Ruft AddAzureKeyVault mit Werten auf, die vom appsettings.jsfür die Datei bereitgestellt werden: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 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(
                        $"https://{builtConfig["KeyVaultName"]}.vault.azure.net/",
                        builtConfig["AzureADApplicationId"],
                        certs.OfType<X509Certificate2>().Single());

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

Beispielwerte:Example values:

  • Key Vault-Name:contosovaultKey vault name: contosovault
  • Anwendungs-ID:627e911e-43cc-61d4-992e-12db9c81b413Application ID: 627e911e-43cc-61d4-992e-12db9c81b413
  • Zertifikat Fingerabdruck:fe14593dd66b2406c5269d742d04b6e1ab03adb1Certificate thumbprint: fe14593dd66b2406c5269d742d04b6e1ab03adb1

appsettings.json:appsettings.json:

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

Wenn Sie die app ausführen, werden auf einer Webseite die geladenen geheimen Werte angezeigt.When you run the app, a webpage shows the loaded secret values. In der Entwicklungsumgebung werden geheime Werte mit dem- _dev Suffix geladen.In the Development environment, secret values load with the _dev suffix. In der Produktionsumgebung werden die Werte mit dem- _prod Suffix geladen.In the Production environment, the values load with the _prod suffix.

Verwenden von verwalteten Identitäten für Azure-RessourcenUse Managed identities for Azure resources

Eine in Azure bereitgestellte App kann verwaltete Identitäten für Azure-Ressourcennutzen, die es der APP ermöglichen, sich mit Azure Key Vault zu authentifizieren, indem Sie Azure AD Authentifizierung ohne Anmelde Informationen (Anwendungs-ID und Kennwort/geheimer Client Schlüssel) verwenden, die in der APP gespeichert sind.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.

In der Beispiel-App werden verwaltete Identitäten für Azure-Ressourcen verwendet, wenn die- #define Anweisung am Anfang der Program.cs -Datei auf festgelegt ist 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.

Geben Sie den Tresor Namen in das appsettings.js der app in der Datei ein.Enter the vault name into the app's appsettings.json file. Die Beispiel-App erfordert keine Anwendungs-ID und kein Kennwort (geheimer Client Schlüssel), wenn Sie auf die-Version festgelegt Managed ist, sodass Sie diese Konfigurationseinträge ignorieren können.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. Die APP wird in Azure bereitgestellt, und Azure authentifiziert die APP für den Zugriff auf Azure Key Vault nur mithilfe des Tresor namens, der in der appsettings.js Datei gespeichert ist.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.

Stellen Sie die Beispiel-App für Azure App Service bereit.Deploy the sample app to Azure App Service.

Eine APP, die für Azure App Service bereitgestellt wird, wird automatisch bei Azure AD registriert, wenn der Dienst erstellt wird.An app deployed to Azure App Service is automatically registered with Azure AD when the service is created. Rufen Sie die Objekt-ID aus der Bereitstellung ab, um Sie im folgenden Befehl zu verwenden.Obtain the Object ID from the deployment for use in the following command. Die Objekt-ID wird in der Azure-Portal im Bereich der Identity App Service angezeigt.The Object ID is shown in the Azure portal on the Identity panel of the App Service.

Wenn Sie Azure CLI und die Objekt-ID der App verwenden, stellen Sie der APP die list get Berechtigungen und für den Zugriff auf den Schlüssel Tresor bereit: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

Starten Sie die APP mit Azure CLI, PowerShell oder der Azure-Portal neu.Restart the app using Azure CLI, PowerShell, or the Azure portal.

Die Beispiel-App:The sample app:

  • Erstellt eine Instanz der- AzureServiceTokenProvider Klasse ohne eine Verbindungs Zeichenfolge.Creates an instance of the AzureServiceTokenProvider class without a connection string. Wenn keine Verbindungs Zeichenfolge bereitgestellt wird, versucht der Anbieter, ein Zugriffs Token von verwalteten Identitäten für Azure-Ressourcen abzurufen.When a connection string isn't provided, the provider attempts to obtain an access token from Managed identities for Azure resources.
  • Ein neues KeyVaultClient wird mit dem AzureServiceTokenProvider instanztokenrückruf erstellt.A new KeyVaultClient is created with the AzureServiceTokenProvider instance token callback.
  • Die- KeyVaultClient Instanz wird mit einer Standard Implementierung von verwendet IKeyVaultSecretManager , die alle geheimen Werte lädt und doppelte Bindestriche ( -- ) durch Doppelpunkte ( : ) in Schlüsselnamen ersetzt.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 IHostBuilder CreateHostBuilder(string[] args) =>
    Host.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());
            }
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Beispiel Wert für Key Vault-Name:contosovaultKey vault name example value: contosovault

appsettings.json:appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

Wenn Sie die app ausführen, werden auf einer Webseite die geladenen geheimen Werte angezeigt.When you run the app, a webpage shows the loaded secret values. In der Entwicklungsumgebung verfügen geheime Werte über das- _dev Suffix, da Sie von Benutzer Geheimnissen bereitgestellt werden.In the Development environment, secret values have the _dev suffix because they're provided by User Secrets. In der Produktionsumgebung werden die Werte mit dem- _prod Suffix geladen, da Sie von Azure Key Vault bereitgestellt werden.In the Production environment, the values load with the _prod suffix because they're provided by Azure Key Vault.

Wenn Sie einen Access denied Fehler erhalten, vergewissern Sie sich, dass die APP mit Azure AD registriert wurde und Zugriff auf den Schlüssel Tresor hat.If you receive an Access denied error, confirm that the app is registered with Azure AD and provided access to the key vault. Vergewissern Sie sich, dass Sie den Dienst in Azure neu gestartet haben.Confirm that you've restarted the service in Azure.

Informationen zur Verwendung des Anbieters mit einer verwalteten Identität und einer Azure devops-Pipeline finden Sie unter Erstellen einer Azure Resource Manager Dienst Verbindung mit einem virtuellen Computer mit einer verwalteten Dienst Identität.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.

KonfigurationsoptionenConfiguration options

AddAzureKeyVaultkann akzeptieren AzureKeyVaultConfigurationOptions :AddAzureKeyVault can accept an AzureKeyVaultConfigurationOptions:

config.AddAzureKeyVault(
    new AzureKeyVaultConfigurationOptions()
    {
        ...
    });
EigenschaftProperty BESCHREIBUNGDescription
Client KeyVaultClient, der zum Abrufen von Werten verwendet werden soll.KeyVaultClient to use for retrieving values.
Manager IKeyVaultSecretManagerzum Steuern des geheimen Schlüssels verwendete Instanz.IKeyVaultSecretManager instance used to control secret loading.
ReloadInterval Timespan, um zwischen versuchen zu warten, den Schlüssel Tresor auf Änderungen abzufragen.Timespan to wait between attempts at polling the key vault for changes. Der Standardwert ist null (die Konfiguration wird nicht neu geladen).The default value is null (configuration isn't reloaded).
Vault Key Vault-URI.Key vault URI.

Schlüsselnamen Präfix verwendenUse a key name prefix

AddAzureKeyVaultstellt eine Überladung bereit, die eine Implementierung von akzeptiert IKeyVaultSecretManager , mit der Sie steuern können, wie Key Vault-Geheimnisse in Konfigurationsschlüssel konvertiert werden.AddAzureKeyVault provides an overload that accepts an implementation of IKeyVaultSecretManager, which allows you to control how key vault secrets are converted into configuration keys. Beispielsweise können Sie die-Schnittstelle implementieren, um geheime Werte basierend auf einem Präfix Wert zu laden, den Sie beim Starten der APP bereitstellen.For example, you can implement the interface to load secret values based on a prefix value you provide at app startup. So können Sie z. b. geheime Schlüssel basierend auf der Version der App laden.This allows you, for example, to load secrets based on the version of the app.

Warnung

Verwenden Sie keine Präfixe für Key Vault-Geheimnisse, um geheime Schlüssel für mehrere apps in demselben Schlüssel Tresor zu platzieren oder um Umwelt Geheimnisse (z. b. Entwicklungs -und Produktions Geheimnisse) in demselben Tresor zu platzieren.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. Es wird empfohlen, dass unterschiedliche apps und Entwicklungs-/Produktionsumgebungen separate Schlüssel Tresore verwenden, um App-Umgebungen für die höchste Sicherheitsstufe zu isolieren.We recommend that different apps and development/production environments use separate key vaults to isolate app environments for the highest level of security.

Im folgenden Beispiel wird ein geheimer Schlüssel im Schlüssel Tresor erstellt (und mit dem Geheimnis-Manager-Tool für die Entwicklungsumgebung) für 5000-AppSecret (Zeiträume sind in Key Vault-Geheimnis Namen nicht zulässig).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). Dieser geheime Schlüssel stellt einen geheimen App-Schlüssel für die Version 5.0.0.0 der APP dar.This secret represents an app secret for version 5.0.0.0 of the app. Bei einer anderen Version der APP, 5.1.0.0, wird dem Schlüssel Tresor ein geheimer Schlüssel (und mit dem Geheimnis-Manager-Tool) für hinzugefügt 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. Jede APP-Version lädt den Wert für die Versionierung mit Versions Angabe in die Konfiguration AppSecret , wobei die Version beim Laden des geheimen Schlüssels entfernt wird.Each app version loads its versioned secret value into its configuration as AppSecret, stripping off the version as it loads the secret.

AddAzureKeyVaultwird mit einem benutzerdefinierten aufgerufen IKeyVaultSecretManager :AddAzureKeyVault is called with a custom IKeyVaultSecretManager:

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

Die IKeyVaultSecretManager Implementierung reagiert auf die Versions Präfixe von Geheimnissen, um den richtigen geheimen Schlüssel in die Konfiguration zu laden:The IKeyVaultSecretManager implementation reacts to the version prefixes of secrets to load the proper secret into configuration:

  • Loadlädt ein Geheimnis, wenn sein Name mit dem Präfix beginnt.Load loads a secret when its name starts with the prefix. Andere Geheimnisse werden nicht geladen.Other secrets aren't loaded.
  • GetKey:GetKey:
    • Entfernt das Präfix aus dem Namen des geheimen Schlüssels.Removes the prefix from the secret name.
    • Ersetzt zwei Bindestriche in einem beliebigen Namen durch das-Zeichen KeyDelimiter , das das in der Konfiguration verwendete Trennzeichen (normalerweise ein Doppelpunkt) ist.Replaces two dashes in any name with the KeyDelimiter, which is the delimiter used in configuration (usually a colon). Azure Key Vault lässt keinen Doppelpunkt in geheimen Namen zu.Azure Key Vault doesn't allow a colon in secret names.
public class PrefixKeyVaultSecretManager : IKeyVaultSecretManager
{
    private readonly string _prefix;

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

    public bool Load(SecretItem secret)
    {
        return secret.Identifier.Name.StartsWith(_prefix);
    }

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

Die- Load Methode wird von einem Anbieter Algorithmus aufgerufen, der die geheimen Schlüssel des Tresors durchläuft, um diejenigen zu finden, die über das Versions Präfix verfügen.The Load method is called by a provider algorithm that iterates through the vault secrets to find the ones that have the version prefix. Wenn ein Versions Präfix mit gefunden wird Load , verwendet der Algorithmus die- GetKey Methode, um den Konfigurations Namen des geheimen namens zurückzugeben.When a version prefix is found with Load, the algorithm uses the GetKey method to return the configuration name of the secret name. Es entfernt das Versions Präfix aus dem Namen des Geheimnisses und gibt den restlichen geheimen Namen für das Laden in die Konfigurations Name-Wert-Paare der APP zurück.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.

Wenn dieser Ansatz implementiert ist:When this approach is implemented:

  1. Die in der Projektdatei der APP angegebene Version der app.The app's version specified in the app's project file. Im folgenden Beispiel wird die App-Version auf festgelegt 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. Vergewissern Sie sich, dass eine <UserSecretsId> Eigenschaft in der Projektdatei der app vorhanden ist, wobei {GUID} eine vom Benutzer bereitgestellte GUID ist: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>
    

    Speichern Sie die folgenden geheimen Schlüssel lokal mit dem Geheimnis-Manager-Tool: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. Geheime Schlüssel werden in Azure Key Vault mithilfe der folgenden Azure CLI Befehle gespeichert: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. Wenn die app ausgeführt wird, werden die geheimen Schlüssel Tresor-Schlüssel geladen.When the app is run, the key vault secrets are loaded. Der Zeichen folgen Schlüssel für 5000-AppSecret wird mit der in der Projektdatei der APP () angegebenen Version der APP abgeglichen 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. Die Version 5000 (mit dem Bindestrich) wird aus dem Schlüsselnamen entfernt.The version, 5000 (with the dash), is stripped from the key name. Während der gesamten APP wird beim Lesen der Konfiguration mit dem Schlüssel AppSecret der geheime Wert geladen.Throughout the app, reading configuration with the key AppSecret loads the secret value.

  6. Wenn die App-Version in der Projektdatei in geändert wird 5.1.0.0 und die APP erneut ausgeführt wird, wird der geheime Wert 5.1.0.0_secret_value_dev in der Entwicklungsumgebung und in der Produktionsumgebung zurückgegeben 5.1.0.0_secret_value_prod .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.

Hinweis

Sie können auch eine eigene KeyVaultClient Implementierung für bereitstellen AddAzureKeyVault .You can also provide your own KeyVaultClient implementation to AddAzureKeyVault. Ein benutzerdefinierter Client ermöglicht die gemeinsame Nutzung einer einzelnen Instanz des Clients in der gesamten app.A custom client permits sharing a single instance of the client across the app.

Binden eines Arrays an eine KlasseBind an array to a class

Der Anbieter ist in der Lage, Konfigurationswerte in ein Array für die Bindung an ein poco-Array zu lesen.The provider is capable of reading configuration values into an array for binding to a POCO array.

Beim Lesen aus einer Konfigurations Quelle, bei der Schlüssel Trennzeichen ( : Trennzeichen) enthalten können, wird ein numerisches Schlüssel Segment verwendet, um die Schlüssel zu unterscheiden, die ein Array bilden ( :0: , :1: , … :{n}: ).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}:). Weitere Informationen finden Sie unter Konfiguration: Binden eines Arrays an eine Klasse.For more information, see Configuration: Bind an array to a class.

Azure Key Vault Schlüssel können keinen Doppelpunkt als Trennzeichen verwenden.Azure Key Vault keys can't use a colon as a separator. Der in diesem Thema beschriebene Ansatz verwendet doppelte Bindestriche ( -- ) als Trennzeichen für hierarchische Werte (Abschnitte).The approach described in this topic uses double dashes (--) as a separator for hierarchical values (sections). Array Schlüssel werden in Azure Key Vault mit doppelten Bindestrichen und numerischen Schlüsselsegmenten ( --0-- , --1-- ,) gespeichert … --{n}-- .Array keys are stored in Azure Key Vault with double dashes and numeric key segments (--0--, --1--, … --{n}--).

Überprüfen Sie die folgende Konfiguration des seriprotokollierungs Anbieters, die von einer JSON-Datei bereitgestellt wirdExamine the following Serilog logging provider configuration provided by a JSON file. Im Array sind zwei Objektliterale definiert WriteTo , die zwei serilog- senkenreflektieren, die Ziele für die Protokollierungs Ausgabe beschreiben: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=="
      }
    }
  ]
}

Die in der vorangehenden JSON-Datei angezeigte Konfiguration wird in Azure Key Vault mithilfe von Double Dash ( -- )-Notation und numerischen Segmenten gespeichert:The configuration shown in the preceding JSON file is stored in Azure Key Vault using double dash (--) notation and numeric segments:

SchlüsselKey WertValue
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==

Geheimnisse erneut ladenReload secrets

Geheimnisse werden zwischengespeichert, bis IConfigurationRoot.Reload() aufgerufen wird.Secrets are cached until IConfigurationRoot.Reload() is called. Abgelaufene, deaktivierte und aktualisierte geheime Schlüssel im Schlüssel Tresor werden von der APP erst berücksichtigt, wenn der Reload ausgeführt wird.Expired, disabled, and updated secrets in the key vault are not respected by the app until Reload is executed.

Configuration.Reload();

Deaktivierte und abgelaufene GeheimnisseDisabled and expired secrets

Deaktivierte und abgelaufene Geheimnisse lösen einen aus KeyVaultErrorException .Disabled and expired secrets throw a KeyVaultErrorException. Um zu verhindern, dass die APP ausgelöst wird, stellen Sie die Konfiguration mithilfe eines anderen Konfigurations Anbieters bereit, oder aktualisieren Sie das deaktivierte oder abgelaufene Geheimnis.To prevent the app from throwing, provide the configuration using a different configuration provider or update the disabled or expired secret.

ProblembehandlungTroubleshoot

Wenn die APP die Konfiguration mit dem Anbieter nicht laden kann, wird eine Fehlermeldung in die ASP.net Core Protokollierungs Infrastrukturgeschrieben.When the app fails to load configuration using the provider, an error message is written to the ASP.NET Core Logging infrastructure. Die folgenden Bedingungen verhindern, dass die Konfiguration geladen wird:The following conditions will prevent configuration from loading:

  • Die APP oder das Zertifikat ist in Azure Active Directory nicht ordnungsgemäß konfiguriert.The app or certificate isn't configured correctly in Azure Active Directory.
  • Der Schlüssel Tresor ist nicht in Azure Key Vault vorhanden.The key vault doesn't exist in Azure Key Vault.
  • Die APP ist nicht autorisiert, auf den Schlüssel Tresor zuzugreifen.The app isn't authorized to access the key vault.
  • Die Zugriffs Richtlinie enthält nicht Get die List Berechtigungen und.The access policy doesn't include Get and List permissions.
  • Im Schlüssel Tresor werden die Konfigurationsdaten (Name/Wert-Paar) fälschlicherweise benannt, fehlen, sind deaktiviert oder abgelaufen.In the key vault, the configuration data (name-value pair) is incorrectly named, missing, disabled, or expired.
  • Die APP hat den falschen Schlüssel Tresor Namen ( KeyVaultName ), Azure AD Anwendungs-ID ( AzureADApplicationId ) oder Azure AD Zertifikat Fingerabdruck ( AzureADCertThumbprint ).The app has the wrong key vault name (KeyVaultName), Azure AD Application Id (AzureADApplicationId), or Azure AD certificate thumbprint (AzureADCertThumbprint).
  • Der Konfigurationsschlüssel (Name) ist in der APP falsch für den Wert, den Sie laden möchten.The configuration key (name) is incorrect in the app for the value you're trying to load.
  • Beim Hinzufügen der Zugriffs Richtlinie für die APP zum Schlüssel Tresor wurde die Richtlinie erstellt, aber die Schaltfläche Speichern wurde nicht in der Benutzeroberfläche für Zugriffsrichtlinien ausgewählt.When adding the access policy for the app to the key vault, the policy was created, but the Save button wasn't selected in the Access policies UI.

Weitere RessourcenAdditional resources

In diesem Dokument wird erläutert, wie Sie den Microsoft Azure Key Vault -Konfigurations Anbieter verwenden, um App-Konfigurationswerte aus Azure Key Vault geheimen Schlüsseln zu laden.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 ist ein cloudbasierter Dienst, der Ihnen hilft, kryptografische Schlüssel und Geheimnisse zu schützen, die von apps und Diensten verwendet werden.Azure Key Vault is a cloud-based service that assists in safeguarding cryptographic keys and secrets used by apps and services. Gängige Szenarien für die Verwendung von Azure Key Vault mit ASP.net Core-apps sind:Common scenarios for using Azure Key Vault with ASP.NET Core apps include:

  • Steuern des Zugriffs auf vertrauliche Konfigurationsdaten.Controlling access to sensitive configuration data.
  • Erfüllen der Anforderung für die Überprüfung der Hardware Sicherheitsmodule (HSM) von PPS 140-2 Level 2 bei der Speicherung von Konfigurationsdaten.Meeting the requirement for FIPS 140-2 Level 2 validated Hardware Security Modules (HSM's) when storing configuration data.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

PaketePackages

Fügen Sie einen Paket Verweis auf die Microsoft.Extensions.Config-urung hinzu. Azurekeyvault -Paket.Add a package reference to the Microsoft.Extensions.Configuration.AzureKeyVault package.

Beispiel-AppSample app

Die Beispiel-APP wird in einem von zwei Modi ausgeführt, die durch die- #define Anweisung am Anfang der Program.cs -Datei bestimmt werden:The sample app runs in either of two modes determined by the #define statement at the top of the Program.cs file:

  • Certificate: Veranschaulicht die Verwendung einer Azure Key Vault Client-ID und eines X. 509-Zertifikats für den Zugriff auf in Azure Key Vault gespeicherte Geheimnisse.Certificate: Demonstrates the use of an Azure Key Vault Client ID and X.509 certificate to access secrets stored in Azure Key Vault. Diese Version des Beispiels kann von einem beliebigen Speicherort aus ausgeführt werden, auf Azure App Service oder auf allen Hosts bereitgestellt werden, die eine ASP.net Core-App bereitstellen können.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: Veranschaulicht, wie verwaltete Identitäten für Azure-Ressourcen verwendet werden, um die APP für die Azure Key Vault mit Azure AD Authentifizierung ohne Anmelde Informationen zu authentifizieren, die im Code oder in der Konfiguration der APP gespeichert sind.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. Wenn Sie für die Authentifizierung verwaltete Identitäten verwenden, sind keine Azure AD Anwendungs-ID und kein Kennwort (geheimer Client Schlüssel) erforderlich.When using managed identities to authenticate, an Azure AD Application ID and Password (Client Secret) aren't required. Die Managed Version des Beispiels muss in Azure bereitgestellt werden.The Managed version of the sample must be deployed to Azure. Befolgen Sie die Anweisungen im Abschnitt Verwenden der verwalteten Identitäten für Azure-Ressourcen .Follow the guidance in the Use the Managed identities for Azure resources section.

Weitere Informationen zum Konfigurieren einer Beispiel-App mithilfe von Präprozessordirektiven ( #define ) finden Sie unter Einführung in ASP.NET Core .For more information on how to configure a sample app using preprocessor directives (#define), see Einführung in ASP.NET Core.

Speicherung von geheimen Schlüsseln in der EntwicklungsumgebungSecret storage in the Development environment

Legen Sie Geheimnisse mit dem Geheimnis-Manager-Toollokal fest.Set secrets locally using the Secret Manager tool. Wenn die Beispiel-App auf dem lokalen Computer in der Entwicklungsumgebung ausgeführt wird, werden Geheimnisse aus dem lokalen Speicher des geheimen Haupt Schlüssels geladen.When the sample app runs on the local machine in the Development environment, secrets are loaded from the local Secret Manager store.

Das Secret Manager-Tool erfordert eine <UserSecretsId> Eigenschaft in der Projektdatei der app.The Secret Manager tool requires a <UserSecretsId> property in the app's project file. Legen Sie den-Eigenschafts Wert ( {GUID} ) auf eine eindeutige GUID fest:Set the property value ({GUID}) to any unique GUID:

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

Geheimnisse werden als Name-Wert-Paare erstellt.Secrets are created as name-value pairs. Hierarchische Werte (Konfigurations Abschnitte) verwenden einen : (Doppelpunkt) als Trennzeichen in ASP.net Core Namen von Konfigurations Schlüsseln.Hierarchical values (configuration sections) use a : (colon) as a separator in ASP.NET Core configuration key names.

Der geheime Manager wird von einer Befehlsshell verwendet, die für den InhaltsStamm des Projekts geöffnet ist, wobei {SECRET NAME} der Name und {SECRET VALUE} der Wert ist: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}"

Führen Sie die folgenden Befehle in einer Befehlsshell aus dem Inhalts Stamm des Projekts aus, um die geheimen Schlüssel für die Beispiel-App festzulegen: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"

Wenn diese Geheimnisse in Azure Key Vault im geheimen Speicher in der Produktionsumgebung mit Azure Key Vault gespeichert werden, wird das _dev Suffix in geändert _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. Das-Suffix bietet einen visuellen Hinweis in der APP-Ausgabe, die die Quelle der Konfigurationswerte anzeigt.The suffix provides a visual cue in the app's output indicating the source of the configuration values.

Geheimer Speicher in der Produktionsumgebung mit Azure Key VaultSecret storage in the Production environment with Azure Key Vault

Die Anweisungen im Schnellstart: festlegen und Abrufen eines Geheimnisses aus Azure Key Vault mithilfe Azure CLI Themas werden hier zusammengefasst, um eine Azure Key Vault zu erstellen und Geheimnisse zu speichern, die von der Beispiel-App verwendet werden.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. Weitere Informationen finden Sie im Thema.Refer to the topic for further details.

  1. Öffnen Sie Azure Cloud Shell, indem Sie eine der folgenden Methoden in der Azure-Portalverwenden:Open Azure Cloud shell using any one of the following methods in the Azure portal:

    • Klicken Sie in der rechten oberen Ecke eines Codeblocks auf Ausprobieren.Select Try It in the upper-right corner of a code block. Verwenden Sie die Such Zeichenfolge "Azure CLI" im Textfeld.Use the search string "Azure CLI" in the text box.
    • Öffnen Sie Cloud Shell in Ihrem Browser mit der Schaltfläche Start Cloud Shell .Open Cloud Shell in your browser with the Launch Cloud Shell button.
    • Wählen Sie im Menü in der oberen rechten Ecke des Azure-Portal die Schaltfläche Cloud Shell aus.Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal.

    Weitere Informationen finden Sie unter Azure CLI und Übersicht über Azure Cloud Shell.For more information, see Azure CLI and Overview of Azure Cloud Shell.

  2. Wenn Sie nicht bereits authentifiziert sind, melden Sie sich mit dem az login Befehl an.If you aren't already authenticated, sign in with the az login command.

  3. Erstellen Sie eine Ressourcengruppe mit dem folgenden Befehl, wobei {RESOURCE GROUP NAME} der Name der Ressourcengruppe für die neue Ressourcengruppe und {LOCATION} die Azure-Region (Datacenter) ist: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. Erstellen Sie mit dem folgenden Befehl einen Schlüssel Tresor in der Ressourcengruppe, wobei {KEY VAULT NAME} der Name für den neuen Schlüssel Tresor und {LOCATION} die Azure-Region (Datacenter) ist: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. Erstellen Sie Geheimnisse im Schlüssel Tresor als Name-Wert-Paare.Create secrets in the key vault as name-value pairs.

    Azure Key Vault geheimen Namen sind auf alphanumerische Zeichen und Bindestriche beschränkt.Azure Key Vault secret names are limited to alphanumeric characters and dashes. Hierarchische Werte (Konfigurations Abschnitte) verwenden -- (zwei Bindestriche) als Trennzeichen.Hierarchical values (configuration sections) use -- (two dashes) as a separator. Doppelpunkte, die normalerweise verwendet werden, um einen Abschnitt von einem Unterschlüssel in ASP.net Core Konfigurationzu begrenzen, sind in Key Vault-Geheimnis Namen nicht zulässig.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. Aus diesem Grund werden zwei Bindestriche verwendet und für einen Doppelpunkt getauscht, wenn die geheimen Schlüssel in die Konfiguration der App geladen werden.Therefore, two dashes are used and swapped for a colon when the secrets are loaded into the app's configuration.

    Die folgenden geheimen Schlüssel sind für die Verwendung mit der Beispiel-App vorgesehen.The following secrets are for use with the sample app. Die Werte enthalten ein _prod Suffix, um Sie von den suffixwerten zu unterscheiden, die _dev in der Entwicklungsumgebung von Benutzer Geheimnissen geladen werden.The values include a _prod suffix to distinguish them from the _dev suffix values loaded in the Development environment from User Secrets. Ersetzen {KEY VAULT NAME} Sie durch den Namen des Schlüssel Tresors, den Sie im vorherigen Schritt erstellt haben: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"
    

Verwenden Sie die Anwendungs-ID und das X. 509-Zertifikat für nicht in Azure gehostete Apps.Use Application ID and X.509 certificate for non-Azure-hosted apps

Konfigurieren Sie Azure AD, Azure Key Vault und die APP für die Verwendung einer Azure Active Directory Anwendungs-ID und eines X. 509-Zertifikats, um sich bei einem Schlüssel Tresor zu authentifizieren, Wenn die APP außerhalb von Azure gehostet wird.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. Weitere Informationen finden Sie im Artikel Informationen zu Schlüsseln, Geheimnissen und Zertifikaten.For more information, see About keys, secrets, and certificates.

Hinweis

Obwohl die Verwendung einer Anwendungs-ID und eines X. 509-Zertifikats für in Azure gehostete Apps unterstützt wird, empfiehlt es sich, beim Hosten einer APP in Azure verwaltete Identitäten für Azure-Ressourcen zu verwenden.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. Für verwaltete Identitäten ist das Speichern eines Zertifikats in der APP oder in der Entwicklungsumgebung nicht erforderlich.Managed identities don't require storing a certificate in the app or in the development environment.

Die Beispiel-App verwendet eine Anwendungs-ID und ein X. 509-Zertifikat, wenn die- #define Anweisung am Anfang der Program.cs -Datei auf festgelegt ist 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. Erstellen Sie ein PKCS # 12-Archiv Zertifikat (. pfx).Create a PKCS#12 archive (.pfx) certificate. Optionen zum Erstellen von Zertifikaten sind Makecert unter Windows und OpenSSL.Options for creating certificates include MakeCert on Windows and OpenSSL.
  2. Installieren Sie das Zertifikat im persönlichen Zertifikat Speicher des aktuellen Benutzers.Install the certificate into the current user's personal certificate store. Das Markieren des Schlüssels als exportierbar ist optional.Marking the key as exportable is optional. Notieren Sie den Fingerabdruck des Zertifikats, der später in diesem Prozess verwendet wird.Note the certificate's thumbprint, which is used later in this process.
  3. Exportieren Sie das PKCS # 12-Archiv Zertifikat (. pfx) als ein-codiertes Zertifikat (. CER).Export the PKCS#12 archive (.pfx) certificate as a DER-encoded certificate (.cer).
  4. Registrieren Sie die APP bei Azure AD (App-Registrierungen).Register the app with Azure AD (App registrations).
  5. Laden Sie das der-codierte Zertifikat (. CER) in Azure AD hoch:Upload the DER-encoded certificate (.cer) to Azure AD:
    1. Wählen Sie die app in Azure AD aus.Select the app in Azure AD.
    2. Navigieren Sie zu Zertifikate & Geheimnissen.Navigate to Certificates & secrets.
    3. Wählen Sie Zertifikat hochladen aus, um das Zertifikat hochzuladen, das den öffentlichen Schlüssel enthält.Select Upload certificate to upload the certificate, which contains the public key. Ein CER-, PEM-oder CRT -Zertifikat ist akzeptabel.A .cer, .pem, or .crt certificate is acceptable.
  6. Speichern Sie den Key Vault-Namen, die Anwendungs-ID und den Zertifikat Fingerabdruck im appsettings.js der app in der Datei.Store the key vault name, Application ID, and certificate thumbprint in the app's appsettings.json file.
  7. Navigieren Sie in der Azure-Portal zu Schlüssel Tresoren .Navigate to Key vaults in the Azure portal.
  8. Wählen Sie den Schlüssel Tresor aus, den Sie im Abschnitt " Geheimnis Speicher in der Produktionsumgebung mit Azure Key Vault " erstellt haben.Select the key vault that you created in the Secret storage in the Production environment with Azure Key Vault section.
  9. Klicken Sie auf Zugriffsrichtlinien.Select Access policies.
  10. Wählen Sie Zugriffsrichtlinie hinzufügen aus.Select Add Access Policy.
  11. Öffnen Sie geheime Berechtigungen , und stellen Sie der APP die Berechtigungen Get und List bereit.Open Secret permissions and provide the app with Get and List permissions.
  12. Wählen Sie Prinzipal auswählen , und wählen Sie die registrierte App nach Name aus.Select Select principal and select the registered app by name. Wählen Sie die Schaltfläche Auswählen aus.Select the Select button.
  13. Klicken Sie auf OK.Select OK.
  14. Wählen Sie Speichern aus.Select Save.
  15. Stellen Sie die App bereit.Deploy the app.

Die Certificate Beispiel-APP erhält Ihre Konfigurationswerte aus IConfigurationRoot dem gleichen Namen wie der geheime Name:The Certificate sample app obtains its configuration values from IConfigurationRoot with the same name as the secret name:

  • Nicht hierarchische Werte: der Wert für SecretName wird mit abgerufen config["SecretName"] .Non-hierarchical values: The value for SecretName is obtained with config["SecretName"].
  • Hierarchische Werte (Abschnitte): Verwenden Sie : die Notation (Doppelpunkt) oder die GetSection Erweiterungsmethode.Hierarchical values (sections): Use : (colon) notation or the GetSection extension method. Verwenden Sie einen dieser Ansätze zum Abrufen des Konfigurations Werts:Use either of these approaches to obtain the configuration value:
    • config["Section:SecretName"]
    • config.GetSection("Section")["SecretName"]

Das X. 509-Zertifikat wird vom Betriebssystem verwaltet.The X.509 certificate is managed by the OS. Die App Ruft AddAzureKeyVault mit Werten auf, die vom appsettings.jsfür die Datei bereitgestellt werden: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(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>();

Beispielwerte:Example values:

  • Key Vault-Name:contosovaultKey vault name: contosovault
  • Anwendungs-ID:627e911e-43cc-61d4-992e-12db9c81b413Application ID: 627e911e-43cc-61d4-992e-12db9c81b413
  • Zertifikat Fingerabdruck:fe14593dd66b2406c5269d742d04b6e1ab03adb1Certificate thumbprint: fe14593dd66b2406c5269d742d04b6e1ab03adb1

appsettings.json:appsettings.json:

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

Wenn Sie die app ausführen, werden auf einer Webseite die geladenen geheimen Werte angezeigt.When you run the app, a webpage shows the loaded secret values. In der Entwicklungsumgebung werden geheime Werte mit dem- _dev Suffix geladen.In the Development environment, secret values load with the _dev suffix. In der Produktionsumgebung werden die Werte mit dem- _prod Suffix geladen.In the Production environment, the values load with the _prod suffix.

Verwenden von verwalteten Identitäten für Azure-RessourcenUse Managed identities for Azure resources

Eine in Azure bereitgestellte App kann verwaltete Identitäten für Azure-Ressourcennutzen, die es der APP ermöglichen, sich mit Azure Key Vault zu authentifizieren, indem Sie Azure AD Authentifizierung ohne Anmelde Informationen (Anwendungs-ID und Kennwort/geheimer Client Schlüssel) verwenden, die in der APP gespeichert sind.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.

In der Beispiel-App werden verwaltete Identitäten für Azure-Ressourcen verwendet, wenn die- #define Anweisung am Anfang der Program.cs -Datei auf festgelegt ist 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.

Geben Sie den Tresor Namen in das appsettings.js der app in der Datei ein.Enter the vault name into the app's appsettings.json file. Die Beispiel-App erfordert keine Anwendungs-ID und kein Kennwort (geheimer Client Schlüssel), wenn Sie auf die-Version festgelegt Managed ist, sodass Sie diese Konfigurationseinträge ignorieren können.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. Die APP wird in Azure bereitgestellt, und Azure authentifiziert die APP für den Zugriff auf Azure Key Vault nur mithilfe des Tresor namens, der in der appsettings.js Datei gespeichert ist.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.

Stellen Sie die Beispiel-App für Azure App Service bereit.Deploy the sample app to Azure App Service.

Eine APP, die für Azure App Service bereitgestellt wird, wird automatisch bei Azure AD registriert, wenn der Dienst erstellt wird.An app deployed to Azure App Service is automatically registered with Azure AD when the service is created. Rufen Sie die Objekt-ID aus der Bereitstellung ab, um Sie im folgenden Befehl zu verwenden.Obtain the Object ID from the deployment for use in the following command. Die Objekt-ID wird in der Azure-Portal im Bereich der Identity App Service angezeigt.The Object ID is shown in the Azure portal on the Identity panel of the App Service.

Wenn Sie Azure CLI und die Objekt-ID der App verwenden, stellen Sie der APP die list get Berechtigungen und für den Zugriff auf den Schlüssel Tresor bereit: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

Starten Sie die APP mit Azure CLI, PowerShell oder der Azure-Portal neu.Restart the app using Azure CLI, PowerShell, or the Azure portal.

Die Beispiel-App:The sample app:

  • Erstellt eine Instanz der- AzureServiceTokenProvider Klasse ohne eine Verbindungs Zeichenfolge.Creates an instance of the AzureServiceTokenProvider class without a connection string. Wenn keine Verbindungs Zeichenfolge bereitgestellt wird, versucht der Anbieter, ein Zugriffs Token von verwalteten Identitäten für Azure-Ressourcen abzurufen.When a connection string isn't provided, the provider attempts to obtain an access token from Managed identities for Azure resources.
  • Ein neues KeyVaultClient wird mit dem AzureServiceTokenProvider instanztokenrückruf erstellt.A new KeyVaultClient is created with the AzureServiceTokenProvider instance token callback.
  • Die- KeyVaultClient Instanz wird mit einer Standard Implementierung von verwendet IKeyVaultSecretManager , die alle geheimen Werte lädt und doppelte Bindestriche ( -- ) durch Doppelpunkte ( : ) in Schlüsselnamen ersetzt.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>();

Beispiel Wert für Key Vault-Name:contosovaultKey vault name example value: contosovault

appsettings.json:appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

Wenn Sie die app ausführen, werden auf einer Webseite die geladenen geheimen Werte angezeigt.When you run the app, a webpage shows the loaded secret values. In der Entwicklungsumgebung verfügen geheime Werte über das- _dev Suffix, da Sie von Benutzer Geheimnissen bereitgestellt werden.In the Development environment, secret values have the _dev suffix because they're provided by User Secrets. In der Produktionsumgebung werden die Werte mit dem- _prod Suffix geladen, da Sie von Azure Key Vault bereitgestellt werden.In the Production environment, the values load with the _prod suffix because they're provided by Azure Key Vault.

Wenn Sie einen Access denied Fehler erhalten, vergewissern Sie sich, dass die APP mit Azure AD registriert wurde und Zugriff auf den Schlüssel Tresor hat.If you receive an Access denied error, confirm that the app is registered with Azure AD and provided access to the key vault. Vergewissern Sie sich, dass Sie den Dienst in Azure neu gestartet haben.Confirm that you've restarted the service in Azure.

Informationen zur Verwendung des Anbieters mit einer verwalteten Identität und einer Azure devops-Pipeline finden Sie unter Erstellen einer Azure Resource Manager Dienst Verbindung mit einem virtuellen Computer mit einer verwalteten Dienst Identität.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.

Schlüsselnamen Präfix verwendenUse a key name prefix

AddAzureKeyVaultstellt eine Überladung bereit, die eine Implementierung von akzeptiert IKeyVaultSecretManager , mit der Sie steuern können, wie Key Vault-Geheimnisse in Konfigurationsschlüssel konvertiert werden.AddAzureKeyVault provides an overload that accepts an implementation of IKeyVaultSecretManager, which allows you to control how key vault secrets are converted into configuration keys. Beispielsweise können Sie die-Schnittstelle implementieren, um geheime Werte basierend auf einem Präfix Wert zu laden, den Sie beim Starten der APP bereitstellen.For example, you can implement the interface to load secret values based on a prefix value you provide at app startup. So können Sie z. b. geheime Schlüssel basierend auf der Version der App laden.This allows you, for example, to load secrets based on the version of the app.

Warnung

Verwenden Sie keine Präfixe für Key Vault-Geheimnisse, um geheime Schlüssel für mehrere apps in demselben Schlüssel Tresor zu platzieren oder um Umwelt Geheimnisse (z. b. Entwicklungs -und Produktions Geheimnisse) in demselben Tresor zu platzieren.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. Es wird empfohlen, dass unterschiedliche apps und Entwicklungs-/Produktionsumgebungen separate Schlüssel Tresore verwenden, um App-Umgebungen für die höchste Sicherheitsstufe zu isolieren.We recommend that different apps and development/production environments use separate key vaults to isolate app environments for the highest level of security.

Im folgenden Beispiel wird ein geheimer Schlüssel im Schlüssel Tresor erstellt (und mit dem Geheimnis-Manager-Tool für die Entwicklungsumgebung) für 5000-AppSecret (Zeiträume sind in Key Vault-Geheimnis Namen nicht zulässig).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). Dieser geheime Schlüssel stellt einen geheimen App-Schlüssel für die Version 5.0.0.0 der APP dar.This secret represents an app secret for version 5.0.0.0 of the app. Bei einer anderen Version der APP, 5.1.0.0, wird dem Schlüssel Tresor ein geheimer Schlüssel (und mit dem Geheimnis-Manager-Tool) für hinzugefügt 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. Jede APP-Version lädt den Wert für die Versionierung mit Versions Angabe in die Konfiguration AppSecret , wobei die Version beim Laden des geheimen Schlüssels entfernt wird.Each app version loads its versioned secret value into its configuration as AppSecret, stripping off the version as it loads the secret.

AddAzureKeyVaultwird mit einem benutzerdefinierten aufgerufen IKeyVaultSecretManager :AddAzureKeyVault is called with a custom IKeyVaultSecretManager:

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

Die IKeyVaultSecretManager Implementierung reagiert auf die Versions Präfixe von Geheimnissen, um den richtigen geheimen Schlüssel in die Konfiguration zu laden:The IKeyVaultSecretManager implementation reacts to the version prefixes of secrets to load the proper secret into configuration:

  • Loadlädt ein Geheimnis, wenn sein Name mit dem Präfix beginnt.Load loads a secret when its name starts with the prefix. Andere Geheimnisse werden nicht geladen.Other secrets aren't loaded.
  • GetKey:GetKey:
    • Entfernt das Präfix aus dem Namen des geheimen Schlüssels.Removes the prefix from the secret name.
    • Ersetzt zwei Bindestriche in einem beliebigen Namen durch das-Zeichen KeyDelimiter , das das in der Konfiguration verwendete Trennzeichen (normalerweise ein Doppelpunkt) ist.Replaces two dashes in any name with the KeyDelimiter, which is the delimiter used in configuration (usually a colon). Azure Key Vault lässt keinen Doppelpunkt in geheimen Namen zu.Azure Key Vault doesn't allow a colon in secret names.
public class PrefixKeyVaultSecretManager : IKeyVaultSecretManager
{
    private readonly string _prefix;

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

    public bool Load(SecretItem secret)
    {
        return secret.Identifier.Name.StartsWith(_prefix);
    }

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

Die- Load Methode wird von einem Anbieter Algorithmus aufgerufen, der die geheimen Schlüssel des Tresors durchläuft, um diejenigen zu finden, die über das Versions Präfix verfügen.The Load method is called by a provider algorithm that iterates through the vault secrets to find the ones that have the version prefix. Wenn ein Versions Präfix mit gefunden wird Load , verwendet der Algorithmus die- GetKey Methode, um den Konfigurations Namen des geheimen namens zurückzugeben.When a version prefix is found with Load, the algorithm uses the GetKey method to return the configuration name of the secret name. Es entfernt das Versions Präfix aus dem Namen des Geheimnisses und gibt den restlichen geheimen Namen für das Laden in die Konfigurations Name-Wert-Paare der APP zurück.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.

Wenn dieser Ansatz implementiert ist:When this approach is implemented:

  1. Die in der Projektdatei der APP angegebene Version der app.The app's version specified in the app's project file. Im folgenden Beispiel wird die App-Version auf festgelegt 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. Vergewissern Sie sich, dass eine <UserSecretsId> Eigenschaft in der Projektdatei der app vorhanden ist, wobei {GUID} eine vom Benutzer bereitgestellte GUID ist: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>
    

    Speichern Sie die folgenden geheimen Schlüssel lokal mit dem Geheimnis-Manager-Tool: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. Geheime Schlüssel werden in Azure Key Vault mithilfe der folgenden Azure CLI Befehle gespeichert: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. Wenn die app ausgeführt wird, werden die geheimen Schlüssel Tresor-Schlüssel geladen.When the app is run, the key vault secrets are loaded. Der Zeichen folgen Schlüssel für 5000-AppSecret wird mit der in der Projektdatei der APP () angegebenen Version der APP abgeglichen 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. Die Version 5000 (mit dem Bindestrich) wird aus dem Schlüsselnamen entfernt.The version, 5000 (with the dash), is stripped from the key name. Während der gesamten APP wird beim Lesen der Konfiguration mit dem Schlüssel AppSecret der geheime Wert geladen.Throughout the app, reading configuration with the key AppSecret loads the secret value.

  6. Wenn die App-Version in der Projektdatei in geändert wird 5.1.0.0 und die APP erneut ausgeführt wird, wird der geheime Wert 5.1.0.0_secret_value_dev in der Entwicklungsumgebung und in der Produktionsumgebung zurückgegeben 5.1.0.0_secret_value_prod .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.

Hinweis

Sie können auch eine eigene KeyVaultClient Implementierung für bereitstellen AddAzureKeyVault .You can also provide your own KeyVaultClient implementation to AddAzureKeyVault. Ein benutzerdefinierter Client ermöglicht die gemeinsame Nutzung einer einzelnen Instanz des Clients in der gesamten app.A custom client permits sharing a single instance of the client across the app.

Binden eines Arrays an eine KlasseBind an array to a class

Der Anbieter ist in der Lage, Konfigurationswerte in ein Array für die Bindung an ein poco-Array zu lesen.The provider is capable of reading configuration values into an array for binding to a POCO array.

Beim Lesen aus einer Konfigurations Quelle, bei der Schlüssel Trennzeichen ( : Trennzeichen) enthalten können, wird ein numerisches Schlüssel Segment verwendet, um die Schlüssel zu unterscheiden, die ein Array bilden ( :0: , :1: , … :{n}: ).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}:). Weitere Informationen finden Sie unter Konfiguration: Binden eines Arrays an eine Klasse.For more information, see Configuration: Bind an array to a class.

Azure Key Vault Schlüssel können keinen Doppelpunkt als Trennzeichen verwenden.Azure Key Vault keys can't use a colon as a separator. Der in diesem Thema beschriebene Ansatz verwendet doppelte Bindestriche ( -- ) als Trennzeichen für hierarchische Werte (Abschnitte).The approach described in this topic uses double dashes (--) as a separator for hierarchical values (sections). Array Schlüssel werden in Azure Key Vault mit doppelten Bindestrichen und numerischen Schlüsselsegmenten ( --0-- , --1-- ,) gespeichert … --{n}-- .Array keys are stored in Azure Key Vault with double dashes and numeric key segments (--0--, --1--, … --{n}--).

Überprüfen Sie die folgende Konfiguration des seriprotokollierungs Anbieters, die von einer JSON-Datei bereitgestellt wirdExamine the following Serilog logging provider configuration provided by a JSON file. Im Array sind zwei Objektliterale definiert WriteTo , die zwei serilog- senkenreflektieren, die Ziele für die Protokollierungs Ausgabe beschreiben: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=="
      }
    }
  ]
}

Die in der vorangehenden JSON-Datei angezeigte Konfiguration wird in Azure Key Vault mithilfe von Double Dash ( -- )-Notation und numerischen Segmenten gespeichert:The configuration shown in the preceding JSON file is stored in Azure Key Vault using double dash (--) notation and numeric segments:

SchlüsselKey WertValue
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==

Geheimnisse erneut ladenReload secrets

Geheimnisse werden zwischengespeichert, bis IConfigurationRoot.Reload() aufgerufen wird.Secrets are cached until IConfigurationRoot.Reload() is called. Abgelaufene, deaktivierte und aktualisierte geheime Schlüssel im Schlüssel Tresor werden von der APP erst berücksichtigt, wenn der Reload ausgeführt wird.Expired, disabled, and updated secrets in the key vault are not respected by the app until Reload is executed.

Configuration.Reload();

Deaktivierte und abgelaufene GeheimnisseDisabled and expired secrets

Deaktivierte und abgelaufene Geheimnisse lösen einen aus KeyVaultErrorException .Disabled and expired secrets throw a KeyVaultErrorException. Um zu verhindern, dass die APP ausgelöst wird, stellen Sie die Konfiguration mithilfe eines anderen Konfigurations Anbieters bereit, oder aktualisieren Sie das deaktivierte oder abgelaufene Geheimnis.To prevent the app from throwing, provide the configuration using a different configuration provider or update the disabled or expired secret.

ProblembehandlungTroubleshoot

Wenn die APP die Konfiguration mit dem Anbieter nicht laden kann, wird eine Fehlermeldung in die ASP.net Core Protokollierungs Infrastrukturgeschrieben.When the app fails to load configuration using the provider, an error message is written to the ASP.NET Core Logging infrastructure. Die folgenden Bedingungen verhindern, dass die Konfiguration geladen wird:The following conditions will prevent configuration from loading:

  • Die APP oder das Zertifikat ist in Azure Active Directory nicht ordnungsgemäß konfiguriert.The app or certificate isn't configured correctly in Azure Active Directory.
  • Der Schlüssel Tresor ist nicht in Azure Key Vault vorhanden.The key vault doesn't exist in Azure Key Vault.
  • Die APP ist nicht autorisiert, auf den Schlüssel Tresor zuzugreifen.The app isn't authorized to access the key vault.
  • Die Zugriffs Richtlinie enthält nicht Get die List Berechtigungen und.The access policy doesn't include Get and List permissions.
  • Im Schlüssel Tresor werden die Konfigurationsdaten (Name/Wert-Paar) fälschlicherweise benannt, fehlen, sind deaktiviert oder abgelaufen.In the key vault, the configuration data (name-value pair) is incorrectly named, missing, disabled, or expired.
  • Die APP hat den falschen Schlüssel Tresor Namen ( KeyVaultName ), Azure AD Anwendungs-ID ( AzureADApplicationId ) oder Azure AD Zertifikat Fingerabdruck ( AzureADCertThumbprint ).The app has the wrong key vault name (KeyVaultName), Azure AD Application Id (AzureADApplicationId), or Azure AD certificate thumbprint (AzureADCertThumbprint).
  • Der Konfigurationsschlüssel (Name) ist in der APP falsch für den Wert, den Sie laden möchten.The configuration key (name) is incorrect in the app for the value you're trying to load.
  • Beim Hinzufügen der Zugriffs Richtlinie für die APP zum Schlüssel Tresor wurde die Richtlinie erstellt, aber die Schaltfläche Speichern wurde nicht in der Benutzeroberfläche für Zugriffsrichtlinien ausgewählt.When adding the access policy for the app to the key vault, the policy was created, but the Save button wasn't selected in the Access policies UI.

Weitere RessourcenAdditional resources