Dostawca konfiguracji usługi Azure Key Vault w usłudze ASP.NET Core

W tym artykule wyjaśniono, jak używać dostawcy konfiguracji usługi Azure Key Vault do ładowania wartości konfiguracji aplikacji z wpisów tajnych usługi Azure Key Vault. Azure Key Vault to oparta na chmurze usługa, która pomaga chronić klucze kryptograficzne i wpisy tajne używane przez aplikacje i usługi. Typowe scenariusze korzystania z usługi Azure Key Vault z aplikacjami platformy ASP.NET Core obejmują:

• Kontrolowanie dostępu do poufnych danych konfiguracji.
• Spełnianie wymagań fiPS 140-2 poziom 2 zweryfikowanych sprzętowych modułów zabezpieczeń (HSM) podczas przechowywania danych konfiguracji.

Pakiety

Dodaj odwołania do pakietów dla następujących pakietów:

• Azure.Extensions.AspNetCore.Configuration.Secrets
• AzureIdentity.

Przykładowa aplikacja

Przykładowa aplikacja jest uruchamiana w jednym z dwóch trybów określonych przez dyrektywę #define preprocesora w górnej części elementu Program.cs:

• Certificate: Demonstruje użycie identyfikatora klienta usługi Azure Key Vault i certyfikatu X.509 w celu uzyskania dostępu do wpisów tajnych przechowywanych w usłudze Azure Key Vault. Ten przykład można uruchomić z dowolnej lokalizacji, niezależnie od tego, czy wdrożono ją w usłudze aplikacja systemu Azure, czy na dowolnym hoście, który może obsługiwać aplikację ASP.NET Core.
• Managed: pokazuje, jak używać tożsamości zarządzanych dla zasobów platformy Azure. Zarządzana identity aplikacja uwierzytelnia aplikację w usłudze Azure Key Vault przy użyciu tożsamości zarządzanych dla zasobów platformy Azure bez przechowywania poświadczeń w kodzie lub konfiguracji aplikacji. Wersja Managed przykładu musi zostać wdrożona na platformie Azure. Postępuj zgodnie ze wskazówkami w sekcji Używanie tożsamości zarządzanych dla zasobów platformy Azure.

Aby uzyskać więcej informacji na temat konfigurowania przykładowej aplikacji przy użyciu dyrektyw preprocesora (#define), zobacz Omówienie ASP.NET Core.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Magazyn wpisów tajnych w środowisku programistycznym

Ustawianie wpisów tajnych lokalnie przy użyciu menedżera wpisów tajnych. Gdy przykładowa aplikacja jest uruchamiana na komputerze lokalnym w środowisku deweloperskim, wpisy tajne są ładowane z magazynu wpisów tajnych użytkownika lokalnego.

Menedżer wpisów tajnych wymaga <UserSecretsId> właściwości w pliku projektu aplikacji. Ustaw wartość właściwości ({GUID}) na dowolny unikatowy identyfikator GUID:

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

Wpisy tajne są tworzone jako pary nazwa-wartość. Wartości hierarchiczne (sekcje konfiguracji) używają : (dwukropka) jako separatora w nazwach kluczy konfiguracji ASP.NET Core.

Menedżer wpisów tajnych jest używany z powłoki poleceń otwartej do katalogu głównego zawartości projektu, gdzie {SECRET NAME} jest nazwą i {SECRET VALUE} jest wartością:

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

Wykonaj następujące polecenia w powłoce poleceń z katalogu głównego zawartości projektu, aby ustawić wpisy tajne dla przykładowej aplikacji:

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

Gdy te wpisy tajne są przechowywane w usłudze Azure Key Vault w magazynie wpisów tajnych w środowisku produkcyjnym za pomocą usługi Azure Key Vault , sufiks _dev zostanie zmieniony na _prod. Sufiks udostępnia wizualną wskazówkę w danych wyjściowych aplikacji wskazującą źródło wartości konfiguracji.

Magazyn wpisów tajnych w środowisku produkcyjnym za pomocą usługi Azure Key Vault

Wykonaj poniższe kroki, aby utworzyć usługę Azure Key Vault i zapisać w niej wpisy tajne przykładowej aplikacji. Aby uzyskać więcej informacji, zobacz Szybki start: ustawianie i pobieranie wpisu tajnego z usługi Azure Key Vault przy użyciu interfejsu wiersza polecenia platformy Azure.

1. Otwórz usługę Azure Cloud Shell przy użyciu dowolnej z następujących metod w witrynie Azure Portal:

   • Wybierz pozycję Wypróbuj w prawym górnym rogu bloku kodu. Użyj ciągu wyszukiwania "Interfejs wiersza polecenia platformy Azure" w polu tekstowym.
   • Otwórz usługę Cloud Shell w przeglądarce za pomocą przycisku Uruchom usługę Cloud Shell .
   • Wybierz przycisk Cloud Shell w menu w prawym górnym rogu witryny Azure Portal.

   Aby uzyskać więcej informacji, zobacz Interfejs wiersza polecenia platformy Azure i Omówienie usługi Azure Cloud Shell.

2. Jeśli jeszcze nie uwierzytelniono, zaloguj się przy użyciu az login polecenia .

3. Utwórz grupę zasobów za pomocą następującego polecenia, gdzie {RESOURCE GROUP NAME} jest nazwą nowej grupy zasobów i {LOCATION} jest regionem świadczenia usługi Azure:

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

4. Utwórz usługę Key Vault w grupie zasobów za pomocą następującego polecenia, gdzie {KEY VAULT NAME} jest nazwą nowego magazynu i {LOCATION} regionem świadczenia usługi Azure:

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

5. Utwórz wpisy tajne w magazynie jako pary name-value.

   Nazwy wpisów tajnych usługi Azure Key Vault są ograniczone do znaków alfanumerycznych i łączników. Wartości hierarchiczne (sekcje konfiguracji) używają -- (dwóch łączników) jako ogranicznika, ponieważ dwukropki nie są dozwolone w nazwach wpisów tajnych usługi Key Vault. Dwukropki rozdzielają sekcję z podklucza w konfiguracji ASP.NET Core. Sekwencja dwusuwowa jest zastępowana dwukropkiem, gdy wpisy tajne są ładowane do konfiguracji aplikacji.

   Następujące wpisy tajne służą do użycia z przykładową aplikacją. Wartości zawierają _prod sufiks, aby odróżnić je od wartości sufiksów _dev załadowanych w środowisku deweloperów z usługi Secret Manager. Zastąp {KEY VAULT NAME} ciąg nazwą magazynu kluczy utworzonego w poprzednim kroku:

   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"
   

Używanie identyfikatora aplikacji i certyfikatu X.509 dla aplikacji spoza platformy Azure

Skonfiguruj usługę Azure Key Vault i aplikację, aby korzystała z identyfikatora aplikacji Microsoft Entra ID i certyfikatu X.509 w celu uwierzytelniania w magazynie , gdy aplikacja jest hostowana poza platformą Azure. Aby uzyskać więcej informacji, zobacz Informacje o kluczach, wpisach tajnych i certyfikatach.

Uwaga

Chociaż używanie identyfikatora aplikacji i certyfikatu X.509 jest obsługiwane w przypadku aplikacji hostowanych na platformie Azure, nie jest zalecane. Zamiast tego użyj tożsamości zarządzanych dla zasobów platformy Azure podczas hostowania aplikacji na platformie Azure. Tożsamości zarządzane nie wymagają przechowywania certyfikatu w aplikacji ani w środowisku projektowym.

Przykładowa aplikacja używa identyfikatora aplikacji i certyfikatu X.509, gdy #define dyrektywa preprocesora w górnej części Program.cs elementu ma wartość Certificate.

1. Utwórz certyfikat archiwum PKCS#12 (pfx). Opcje tworzenia certyfikatów obejmują new-SelfSignedCertificate w systemach Windows i OpenSSL.
2. Zainstaluj certyfikat w osobistym magazynie certyfikatów bieżącego użytkownika. Oznaczanie klucza jako możliwego do wyeksportowania jest opcjonalne. Zanotuj odcisk palca certyfikatu, który jest używany w dalszej części tego procesu.
3. Wyeksportuj certyfikat archiwum PKCS#12 (pfx) jako certyfikat zakodowany w formacie DER (.cer).
4. Zarejestruj aplikację przy użyciu identyfikatora Entra firmy Microsoft (Rejestracje aplikacji).
5. Przekaż certyfikat zakodowany w formacie DER (.cer) do identyfikatora Entra firmy Microsoft:
   1. Wybierz aplikację w polu Microsoft Entra ID.
   2. Przejdź do pozycji Certyfikaty i wpisy tajne.
   3. Wybierz pozycję Przekaż certyfikat , aby przekazać certyfikat zawierający klucz publiczny. Akceptowalny jest certyfikat .cer, pem lub crt.
6. Zapisz nazwę usługi Key Vault, identyfikator aplikacji i odcisk palca certyfikatu w pliku aplikacji appsettings.json .
7. Przejdź do usługi Key Vault w witrynie Azure Portal.
8. Wybierz magazyn kluczy utworzony w magazynie wpisów tajnych w środowisku produkcyjnym za pomocą usługi Azure Key Vault .
9. Wybierz opcję Uzyskaj dostęp do zasad.
10. Wybierz opcję Dodaj zasady dostępu.
11. Otwórz uprawnienia wpisu tajnego i podaj aplikację z uprawnieniami Pobierz i Lista .
12. Wybierz pozycję Wybierz podmiot zabezpieczeń i wybierz zarejestrowaną aplikację według nazwy. Wybierz przycisk Wybierz.
13. Wybierz przycisk OK.
14. Wybierz pozycję Zapisz.
15. Wdróż aplikację.

Przykładowa Certificate aplikacja uzyskuje wartości konfiguracji z IConfigurationRoot tej samej nazwy co nazwa wpisu tajnego:

• Wartości nie hierarchiczne: wartość parametru SecretName jest uzyskiwana za pomocą config["SecretName"]polecenia .
• Wartości hierarchiczne (sekcje): użyj : notacji (dwukropka) lub GetSection metody . Użyj jednej z tych metod, aby uzyskać wartość konfiguracji:
  • config["Section:SecretName"]
  • config.GetSection("Section")["SecretName"]

Certyfikat X.509 jest zarządzany przez system operacyjny. Aplikacja wywołuje wywołania AddAzureKeyVault z wartościami dostarczonymi przez appsettings.json plik:

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

var builder = WebApplication.CreateBuilder(args);

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

    x509Store.Open(OpenFlags.ReadOnly);

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

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

var app = builder.Build();

Przykładowe wartości:

• Nazwa magazynu kluczy: contosovault
• Identyfikator aplikacji: 00001111-aaaa-2222-bbbb-3333cccc4444
• Odcisk palca certyfikatu: fe14593dd66b2406c5269d742d04b6e1ab03adb1

appsettings.json:

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

Po uruchomieniu aplikacji na stronie internetowej są wyświetlane załadowane wartości wpisów tajnych. W środowisku deweloperów wartości wpisów tajnych są ładowane z sufiksem _dev . W środowisku produkcyjnym wartości są ładowane z sufiksem _prod .

Korzystanie z tożsamości zarządzanych dla zasobów platformy Azure

Aplikacja wdrożona na platformie Azure może korzystać z tożsamości zarządzanych dla zasobów platformy Azure. Zarządzane identity umożliwia aplikacji uwierzytelnianie w usłudze Azure Key Vault przy użyciu uwierzytelniania identyfikatora Entra firmy Microsoft bez przechowywania poświadczeń w kodzie lub konfiguracji aplikacji.

Przykładowa aplikacja używa przypisanego przez system zarządzanego, gdy #define dyrektywa preprocesora w górnej części Program.cs elementu ma wartość Managed.identity Aby utworzyć zarządzaną identity aplikację usługi aplikacja systemu Azure Service, zobacz How to use managed identities for App Service and Azure Functions (Jak używać tożsamości zarządzanych dla usług App Service i Azure Functions). Po utworzeniu zarządzanego identity zanotuj identyfikator obiektu aplikacji wyświetlany w witrynie Azure Portal na Identity panelu usługi App Service.

Wprowadź nazwę magazynu w pliku aplikacji appsettings.json . Przykładowa aplikacja nie wymaga identyfikatora aplikacji i hasła (klucza tajnego Managed klienta) w przypadku ustawienia wersji, więc można zignorować te wpisy konfiguracji. Aplikacja jest wdrażana na platformie Azure, a platforma Azure uwierzytelnia aplikację w celu uzyskania dostępu do usługi Azure Key Vault tylko przy użyciu nazwy magazynu przechowywanego appsettings.json w pliku.

Wdróż przykładową aplikację w usłudze aplikacja systemu Azure Service.

Przy użyciu interfejsu wiersza polecenia platformy Azure i identyfikatora obiektu aplikacji podaj aplikację i list get uprawnienia dostępu do magazynu:

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

Uruchom ponownie aplikację przy użyciu interfejsu wiersza polecenia platformy Azure, programu PowerShell lub witryny Azure Portal.

Przykładowa aplikacja tworzy wystąpienie DefaultAzureCredential klasy. Poświadczenia próbują uzyskać token dostępu ze środowiska dla zasobów platformy Azure:

using Azure.Identity;

var builder = WebApplication.CreateBuilder(args);

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

Przykładowa wartość nazwy usługi Key Vault: contosovault

appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

W przypadku aplikacji korzystających z zarządzanego identityprzez użytkownika skonfiguruj zarządzany identyfikator klienta zarządzanego identityprzy użyciu jednej z następujących metod:

1. Ustaw zmienną środowiskową AZURE_CLIENT_ID.

2. DefaultAzureCredentialOptions.ManagedIdentityClientId Ustaw właściwość podczas wywoływania elementu AddAzureKeyVault:

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

Po uruchomieniu aplikacji na stronie internetowej są wyświetlane załadowane wartości wpisów tajnych. W środowisku deweloperów wartości wpisów tajnych mają sufiks _dev , ponieważ są one udostępniane przez menedżera wpisów tajnych. W środowisku produkcyjnym wartości są ładowane z sufiksem, ponieważ są one udostępniane przez usługę _prod Azure Key Vault.

Jeśli wystąpi Access denied błąd, upewnij się, że aplikacja jest zarejestrowana w identyfikatorze Microsoft Entra ID i zapewnia dostęp do magazynu. Upewnij się, że usługa została uruchomiona ponownie na platformie Azure.

Aby uzyskać informacje na temat korzystania z dostawcy z usługą zarządzaną identity i usługą Azure Pipelines, zobacz Create an Azure Resource Manager service connection to a VM with a managed service (Tworzenie połączenia usługi Azure Resource Manager z maszyną wirtualną za pomocą usługi identityzarządzanej).

Opcje konfiguracji

AddAzureKeyVault może zaakceptować AzureKeyVaultConfigurationOptions obiekt:

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

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

Obiekt AzureKeyVaultConfigurationOptions zawiera następujące właściwości:

Właściwości	opis
Manager	KeyVaultSecretManager wystąpienie używane do kontrolowania ładowania wpisów tajnych.
ReloadInterval	TimeSpan poczekać między próbami sondowania magazynu pod kątem zmian. Wartość domyślna to null (konfiguracja nie jest ponownie ładowana).

Używanie prefiksu nazwy klucza

AddAzureKeyVault Zapewnia przeciążenie, które akceptuje implementację KeyVaultSecretManagerprogramu , co pozwala kontrolować sposób konwertowania wpisów tajnych usługi Key Vault na klucze konfiguracji. Na przykład można zaimplementować interfejs w celu załadowania wartości wpisów tajnych na podstawie wartości prefiksu podanej podczas uruchamiania aplikacji. Ta technika umożliwia na przykład ładowanie wpisów tajnych na podstawie wersji aplikacji.

Ostrzeżenie

Nie używaj prefiksów wpisów tajnych usługi Key Vault do:

• Umieść wpisy tajne dla wielu aplikacji w tym samym magazynie.
• Umieść wpisy tajne środowiska (na przykład programowanie i wpisy tajne produkcji ) w tym samym magazynie.

Różne aplikacje i środowiska programistyczne/produkcyjne powinny używać oddzielnych magazynów Key Vault do izolowania środowisk aplikacji dla najwyższego poziomu zabezpieczeń.

W poniższym przykładzie wpis tajny jest ustanawiany w usłudze Key Vault (i przy użyciu menedżera wpisów tajnych dla środowiska deweloperskiego) dla 5000-AppSecret (okresy nie są dozwolone w nazwach wpisów tajnych usługi Key Vault). Ten wpis tajny reprezentuje wpis tajny aplikacji dla wersji 5.0.0.0 aplikacji. W przypadku innej wersji aplikacji 5.1.0.0 wpis tajny jest dodawany do magazynu (i przy użyciu menedżera wpisów tajnych) dla programu 5100-AppSecret. Każda wersja aplikacji ładuje jego wersję wartości wpisu tajnego do konfiguracji jako AppSecret, usuwając wersję podczas ładowania wpisu tajnego.

AddAzureKeyVault jest wywoływana z implementacją niestandardową KeyVaultSecretManager :

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

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

Implementacja reaguje na prefiksy wersji wpisów tajnych, aby załadować odpowiedni wpis tajny do konfiguracji:

• Load ładuje wpis tajny, gdy jego nazwa zaczyna się od prefiksu. Inne wpisy tajne nie są ładowane.
• GetKey:
  • Usuwa prefiks z nazwy wpisu tajnego.
  • Zamienia dwa kreski w dowolnej nazwie na KeyDelimiter, czyli ogranicznik używany w konfiguracji (zwykle dwukropek). Usługa Azure Key Vault nie zezwala na dwukropek w nazwach wpisów tajnych.

public class SamplePrefixKeyVaultSecretManager : KeyVaultSecretManager
{
    private readonly string _prefix;

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

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

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

Metoda Load jest wywoływana przez algorytm dostawcy, który iteruje za pośrednictwem wpisów tajnych magazynu, aby znaleźć prefiksowane wpisy tajne wersji. W przypadku znalezienia Loadprefiksu wersji za pomocą algorytmu GetKey metoda zwraca nazwę konfiguracji nazwy wpisu tajnego. Usuwa prefiks wersji z nazwy wpisu tajnego. Nazwa rest wpisu tajnego jest zwracana do ładowania do par nazwa-wartość konfiguracji aplikacji.

Po zaimplementowaniu tego podejścia:

1. Wersja aplikacji określona w pliku projektu aplikacji. W poniższym przykładzie wersja aplikacji jest ustawiona na wartość 5.0.0.0:

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

2. Upewnij się, że <UserSecretsId> właściwość znajduje się w pliku projektu aplikacji, gdzie {GUID} jest dostarczany przez użytkownika identyfikator GUID:

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

   Zapisz następujące wpisy tajne lokalnie za pomocą menedżera wpisów tajnych:

   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. Wpisy tajne są zapisywane w usłudze Azure Key Vault przy użyciu następujących poleceń interfejsu wiersza polecenia platformy Azure:

   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 uruchomieniu aplikacji są ładowane wpisy tajne usługi Key Vault. Wpis tajny ciągu dla 5000-AppSecret elementu jest zgodny z wersją aplikacji określoną w pliku projektu aplikacji (5.0.0.0).

5. Wersja 5000 (z kreską) jest usuwana z nazwy klucza. W całej aplikacji odczyt konfiguracji z kluczem AppSecret ładuje wartość wpisu tajnego.

6. Jeśli wersja aplikacji zostanie zmieniona w pliku projektu na 5.1.0.0 i aplikacja zostanie uruchomiona ponownie, zwracana wartość wpisu tajnego znajduje 5.1.0.0_secret_value_dev się w środowisku deweloperskim i 5.1.0.0_secret_value_prod w środowisku produkcyjnym.

Uwaga

Możesz również udostępnić własną SecretClient implementację do usługi AddAzureKeyVault. Niestandardowy klient zezwala na udostępnianie pojedynczego wystąpienia klienta w aplikacji.

Wiązanie tablicy z klasą

Dostawca może odczytywać wartości konfiguracji w tablicy w celu powiązania z tablicą POCO.

Podczas odczytywania ze źródła konfiguracji, które umożliwia kluczom zawieranie separatorów dwukropka (:), segment klucza liczbowego służy do rozróżniania kluczy tworzących tablicę (:0:, :1:, ... :{n}:). Aby uzyskać więcej informacji, zobacz Configuration: Bind an array to a class (Konfiguracja: wiązanie tablicy z klasą).

Klucze usługi Azure Key Vault nie mogą używać dwukropka jako separatora. Metoda opisana w tym artykule używa podwójnych kresków (--) jako separatora wartości hierarchicznych (sekcji). Klucze tablic są przechowywane w usłudze Azure Key Vault z podwójnymi kreskami i segmentami kluczy liczbowych (--0--, --1--, ... --{n}--).

Zapoznaj się z następującą konfiguracją dostawcy rejestrowania serilog dostarczoną przez plik JSON. Istnieją dwa literały obiektów zdefiniowane w tablicyWriteTo, które odzwierciedlają dwa ujścia Serilog, które opisują lokalizacje docelowe dla danych wyjściowych rejestrowania:

"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=="
      }
    }
  ]
}

Konfiguracja pokazana w poprzednim pliku JSON jest przechowywana w usłudze Azure Key Vault przy użyciu notacji podwójnej kreski (--) i segmentów liczbowych:

Key	Wartość
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==

Ponowne ładowanie wpisów tajnych

Domyślnie wpisy tajne są buforowane przez dostawcę konfiguracji dla okresu istnienia aplikacji. Wpisy tajne, które zostały następnie wyłączone lub zaktualizowane w magazynie, są ignorowane przez aplikację.

Aby ponownie załadować wpisy tajne, wywołaj metodę IConfigurationRoot.Reload:

config.Reload();

Aby okresowo ponownie ładować wpisy tajne, w określonym interwale ustaw AzureKeyVaultConfigurationOptions.ReloadInterval właściwość . Aby uzyskać więcej informacji, zobacz Opcje konfiguracji.

Wyłączone i wygasłe wpisy tajne

Wygasłe wpisy tajne są domyślnie dołączane do dostawcy konfiguracji. Aby wykluczyć wartości tych wpisów tajnych w konfiguracji aplikacji, zaktualizuj wygasły wpis tajny lub podaj konfigurację przy użyciu niestandardowego dostawcy konfiguracji:

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

Przekaż ten niestandardowy KeyVaultSecretManager element do :AddAzureKeyVault

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

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

Wyłączone wpisy tajne nie mogą być pobierane z usługi Key Vault i nigdy nie są uwzględniane.

Rozwiązywanie problemów

Gdy aplikacja nie może załadować konfiguracji przy użyciu dostawcy, zostanie zapisany komunikat o błędzie w infrastrukturze rejestrowania podstawowego ASP.NET. Następujące warunki uniemożliwią ładowanie konfiguracji:

• Aplikacja lub certyfikat nie są poprawnie skonfigurowane w identyfikatorze Entra firmy Microsoft.
• Magazyn nie istnieje w usłudze Azure Key Vault.
• Aplikacja nie jest autoryzowana do uzyskiwania dostępu do magazynu.
• Zasady dostępu nie obejmują Get uprawnień i List .
• W magazynie dane konfiguracji (para name-value) są niepoprawnie nazwane, brakujące lub wyłączone.
• Aplikacja ma nieprawidłową nazwę magazynu kluczy (KeyVaultName), identyfikator aplikacji Microsoft Entra ID (AzureADApplicationId) lub odcisk palca certyfikatu Entra ID firmy Microsoft (AzureADCertThumbprint) lub identyfikator katalogu Entra ID firmy Microsoft (AzureADDirectoryId).
• Podczas dodawania zasad dostępu usługi Key Vault dla aplikacji utworzono zasady, ale przycisk Zapisz nie został wybrany w interfejsie użytkownika zasad dostępu.

Dodatkowe zasoby

• Wyświetl lub pobierz przykładowy kod (jak pobrać)
• Konfiguracja w programie ASP.NET Core
• Microsoft Azure: Dokumentacja usługi Key Vault
• Jak wygenerować i przenieść klucze chronione przez moduł HSM dla usługi Azure Key Vault
• Szybki start: ustawianie i pobieranie wpisu tajnego z usługi Azure Key Vault przy użyciu aplikacji internetowej platformy .NET
• Samouczek: jak używać usługi Azure Key Vault z maszyną wirtualną platformy Azure z systemem Windows na platformie .NET