Använda Azure Key Vault konfigurationsprovider i ASP.NET Core

Den här artikeln beskriver hur du använder konfigurationsprovidern Azure Key Vault för att läsa in appkonfigurationsvärden från Key Vault hemligheter. Key Vault är en molnbaserad tjänst som hjälper till att skydda kryptografiska nycklar och hemligheter som används av appar och tjänster. Vanliga scenarier för att använda Key Vault med ASP.NET Core appar är:

• Kontrollera åtkomsten till känsliga konfigurationsdata.
• Uppfylla kravet på FIPS 140-2 Level 2-verifierade maskinvarusäkerhetsmoduler (HSM) när du lagrar konfigurationsdata.

Packages

Lägg till paketreferenser för följande paket:

• Azure.Extensions.AspNetCore.Configuration.Secrets
• Blått.Identity

Exempelapp

Exempelappen körs i något av två lägen som bestäms av #define förprocessordirektivet överst i filen Program.cs :

• Certificate: Visar hur du använder ett Key Vault klient-ID och X.509-certifikat för att komma åt hemligheter som lagras i en key vault. Du kan köra exemplet från valfri plats, oavsett om det distribueras till Azure App Service eller någon värd som kan hantera en ASP.NET Core app.

• Managed: Visar hur du använder hanterade identiteter för Azure-resurser. Den hanterade identiteten autentiserar appen mot Key Vault med Hanterade identiteter för Azure-resurser utan att lagra autentiseringsuppgifter i programkoden eller konfigurationen. Versionen Managed av exemplet måste distribueras till Azure. Följ riktlinjerna i avsnittet Använda hanterade identiteter för Azure-resurser .

Mer information om att konfigurera en exempelapp genom att använda #define finns i Preprocessordirektiv i exempelkod.

Visa eller ladda ned exempelkod (hur du laddar ned)

Hemlig lagring i utvecklingsmiljön

Ange hemligheter lokalt med hjälp av Secret Manager-verktyget. När exempelappen körs på den lokala datorn i Development miljön läses hemligheter in från det lokala lagringsarkivet för användarhemligheter.

Secret Manager kräver en <UserSecretsId> egenskap i programprojektfilen. Ange egenskapsvärdet ({GUID}) till ett unikt GUID:

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

Hemligheter skapas som namn/värde-par. Hierarkiska värden (konfigurationsavsnitt) använder kolon (:) som avgränsare i ASP.NET Core konfiguration nyckelnamn.

Secret Manager används i ett kommandogränssnitt (eller terminal) som öppnas för projektets innehållsrot, där {SECRET NAME} är namnet och {SECRET VALUE} är värdet:

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

Kör följande kommandon i ett kommandogränssnitt från projektets innehållsrot. Kommandona anger hemligheterna för exempelappen:

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

När dessa hemligheter lagras i Key Vault, enligt beskrivningen i avsnittet Secret storage i produktionsmiljön med Key Vault, ändras suffixet _dev till _prod. Suffixet innehåller en visuell referens i programmets utdata som anger källan till konfigurationsvärdena.

Hemlig lagring i produktionsmiljön med Key Vault

Skapa ett Azure nyckelvalv och lagra exempelprogramhemligheterna genom att slutföra följande steg. Mer information finns i Quickstart: Ange och hämta en hemlighet från Key Vault med Azure CLI.

1. Öppna Azure Cloud Shell med någon av följande metoder i portalen Azure:

   • Välj Prova på i det övre högra hörnet av ett kodblock. Använd söksträngen "Azure CLI" i textrutan.
   • Öppna Cloud Shell i webbläsaren med knappen Starta Cloud Shell .
   • Välj knappen Cloud Shell på menyn i det övre högra hörnet i Azure-portalen.

   Mer information finns i dokumentationen Azure CLI och Overview för Azure Cloud Shell.

2. Om du inte redan är autentiserad, logga in med kommandot az login.

3. Skapa en resursgrupp med följande kommando, där {RESOURCE GROUP NAME} är namnet på den nya resursgruppen och {LOCATION} är den Azure regionen:

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

4. Skapa ett Azure nyckelvalv i resursgruppen med följande kommando, där {KEY VAULT NAME} är namnet på det nya valvet och {LOCATION} är den Azure regionen:

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

5. Skapa hemligheter i valvet som namn/värde-par.

   Key Vault hemliga namn kan bestå av alfanumeriska tecken och bindestreck (-). Hierarkiska värden (konfigurationsavsnitt) använder två bindestreck eller bindestreck (--) som avgränsare. Tecknet kolon är inte tillåtet i Key Vault-hemlighetsnamn. Kolon avgränsar ett avsnitt från en undernyckel i ASP.NET Core-konfiguration. Tvåstreckssekvensen ersätts med ett kolon när hemligheterna läses in i programkonfigurationen.

   Följande hemligheter är till för användning med exempelappen. Värdena innehåller ett _prod suffix som skiljer dem från _dev de suffixvärden som läses in i Development miljön via Secret Manager. Ersätt {KEY VAULT NAME} med namnet på nyckelvalvet som du skapade tidigare:

   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"
   

Använda program-ID och X.509-certifikat för appar som inte finns i Azure

Konfigurera Key Vault och appen för att använda ett Microsoft Entra ID program-ID och X.509-certifikat för att autentisera till ett valv när appen finns utanför Azure. Mer information finns i Om nycklar, hemligheter och certifikat.

Exempelappen använder ett program-ID och X.509-certifikat när #define förprocessordirektivet överst i filen Program.cs anges till Certificate.

1. Skapa ett PKCS#12-arkivcertifikat (.pfx). Alternativen för att skapa certifikat är New-SelfSignedCertificate i Windows och OpenSSL.

2. Installera certifikatet i den aktuella användarens personliga certifikatarkiv. Det är valfritt att markera nyckeln som exporterbar. Observera certifikatets tumavtryck, som används senare i den här processen.

3. Exportera PKCS#12-arkivcertifikatet (.pfx) som ett DER-kodat certifikat (.cer).

4. Registrera appen med Microsoft Entra-ID (appregistreringar).

5. Ladda upp det DER-kodade certifikatet (.cer) till Microsoft Entra ID:

   1. Välj appen i Microsoft Entra-ID.
   2. Gå till Certifikat och hemligheter.
   3. Välj Ladda upp certifikat för att ladda upp certifikatet, som innehåller den offentliga nyckeln. Ett .cer-, .pem- eller .crt-certifikat är acceptabelt .

6. Lagra nyckelvalvets namn, program-ID och certifikatets tumavtryck i programmet appsettings.json filen.

7. I Azure-portalen går du till Key Vaults.

8. Välj det nyckelvalv som du skapade i avsnittet Secret i produktionsmiljön med Azure Key Vault.

9. Välj Åtkomstprinciper och välj sedan Lägg till åtkomstprincip.

10. Öppna hemliga behörigheter och ge appen behörighet att hämta och lista .

11. Välj Välj huvudnamn. Välj den registrerade appen efter namn och välj sedan Välj.

12. Välj OKoch välj sedan spara.

13. Distribuera appen.

Exempelappen Certificate hämtar sina konfigurationsvärden från IConfigurationRoot med samma namn som det hemliga namnet:

• Icke-hierarkiska värden: Värdet för SecretName hämtas med config["SecretName"].
• Hierarkiska värden (avsnitt): Använd kolon (:) notation eller GetSection -metoden. Använd någon av följande metoder för att hämta konfigurationsvärdet:
  • config["Section:SecretName"]
  • config.GetSection("Section")["SecretName"]

Operativsystemet hanterar X.509-certifikatet. Appen anropar AddAzureKeyVault metoden med värden som tillhandahålls av appsettings.json-filen :

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();

Exempelvärden:

• Namn på nyckelvalv: contosovault
• Applikations-ID: 00001111-aaaa-2222-bbbb-3333cccc4444
• Certifikatets tumavtryck: fe14593dd66b2406c5269d742d04b6e1ab03adb1

Värdena i appsettings.json-filen :

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

När du kör appen visar en webbsida de inlästa hemliga värdena. Development I miljön läses hemliga värden in med suffixet_dev. I denna Production miljö läses värdena in med suffixet _prod.

Använda hanterade identiteter för Azure-resurser

En app som distribueras till Azure kan dra nytta av hanterade identiteter för Azure-resurser. Med en hanterad identitet kan appen autentisera med Azure Key Vault med hjälp av Microsoft Entra ID autentisering utan att lagra autentiseringsuppgifter i programkoden eller konfigurationen.

Exempelappen använder en systemtilldelad hanterad identitet när #define förprocessordirektivet överst i filen Program.cs är inställt på Managed. Information om hur du skapar en hanterad identitet för en Azure App Service-app finns i Använda hanterade identiteter för App Service och Azure Functions. När den hanterade identiteten har skapats noterar du programobjekt-ID:t som visas i Azure-portalen på panelen Identity i App Service.

Ange namnet på nyckelvalvet i programmet appsettings.json filen. Exempelappen kräver inte något program-ID och lösenord (klienthemlighet) när den är inställd på Managed versionen, så du kan ignorera dessa konfigurationsposter. Appen distribueras till Azure och Azure autentiserar appen för att komma åt Key Vault endast med hjälp av valvnamnet som lagras i filen appsettings.json.

Distribuera exempelappen till Azure App Service.

Med hjälp av Azure CLI och appens objekt-ID ger du appen behörigheten list och get för åtkomst till nyckelvalvet:

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

Starta appen med hjälp av Azure CLI, Azure PowerShell eller Azure-portalen.

Exempelappen skapar en instans av DefaultAzureCredential klassen. Autentiseringsuppgifterna försöker hämta en åtkomsttoken från miljön för Azure-resurser:

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());
}

Exempelnamn för nyckelvalvet: contosovault

Värdet för namnet i filen appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

För appar som använder en användartilldelad hanterad identitet konfigurerar du den hanterade identitetens klient-ID med någon av följande metoder:

• AZURE_CLIENT_ID Ange miljövariabeln.

• Ange egenskapen DefaultAzureCredentialOptions.ManagedIdentityClientId när du anropar AddAzureKeyVault metoden:

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

När du kör appen visar en webbsida de inlästa hemliga värdena. Development I miljön har hemliga värden suffixet _dev eftersom de tillhandahålls av Secret Manager. Production I miljön läses värdena in med suffixet _prod eftersom de tillhandahålls av Azure Key Vault.

Om du får ett Access denied-fel kontrollerar du att appen är registrerad med Microsoft Entra ID och har åtkomst till valvet. Bekräfta att du startade om tjänsten i Azure.

Information om hur du använder providern med en hanterad identitet och Azure-pipelines finns i Anslut till Azure med en Azure Resource Manager tjänstanslutning.

Konfigurationsalternativ

Metoden AddAzureKeyVault kan acceptera ett AzureKeyVaultConfigurationOptions objekt:

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

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

Objektet AzureKeyVaultConfigurationOptions innehåller följande egenskaper:

Använd ett nyckelnamnsprefix

Metoden AddAzureKeyVault ger en överlagring som accepterar en implementering av KeyVaultSecretManager, vilket gör att du kan styra hur Key Vault hemligheter konverteras till konfigurationsnycklar. Du kan till exempel implementera gränssnittet för att läsa in hemliga värden baserat på ett prefixvärde som du anger vid appstart. Med den här tekniken kan du till exempel läsa in hemligheter baserat på appens version.

I följande exempel upprättas en hemlighet i Key Vault (genom att använda Secret Manager för miljön Development) för 5000-AppSecret (perioder tillåts inte i Key Vault hemliga namn). Den här hemligheten representerar en apphemlighet för version 5.0.0.0 av appen. För en annan version av appen, 5.1.0.0, läggs ett hemligt värde till i samma nyckelvalv (med hjälp av Secret Manager) för 5100-AppSecret. Varje appversion läser in sitt versionshemlighetsvärde i konfigurationen som AppSecretoch tar bort versionen när den läser in hemligheten.

Metoden AddAzureKeyVault anropas med en anpassad implementering av KeyVaultSecretManager:

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

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

Implementeringen reagerar på versionsprefixen för hemligheter för att läsa in rätt hemlighet i konfigurationen:

• Metoden Load läser in en hemlighet när dess namn börjar med prefixet. Andra hemligheter laddas inte.
• Metoden GetKey :
  • Tar bort prefixet från det hemliga namnet.
  • Ersätter två bindestreck (--) i valfritt namn med KeyDelimiter. Den här avgränsare (vanligtvis ett kolon :) används i konfigurationen eftersom Key Vault inte tillåter ett kolon (:) i hemliga namn.

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);
}

En provideralgoritm anropar metoden Load och itererar igenom nyckelvalvshemligheterna för att hitta de versionsprefixade hemligheterna. När ett versionsprefix hittas med Loadanvänder algoritmen GetKey metoden för att returnera konfigurationsnamnet för det hemliga namnet. Det tar bort versionsprefixet från hemlighetens namn. Resten av det hemliga namnet returneras för inläsning till programkonfigurationens namn/värde-par.

Slutför följande steg när du implementerar den här metoden:

1. Ange programversionen i programprojektfilen. I följande exempel är programversionen inställd på 5.0.0.0:

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

2. Bekräfta att egenskapen <UserSecretsId> har definierats i programprojektfilen, där {GUID} är ett användardefinierat GUID:

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

   Spara följande hemligheter lokalt med Secret Manager:

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

3. Spara hemligheterna i Azure Key Vault med hjälp av följande Azure CLI kommandon:

   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"
   

Processen slutför följande uppgifter:

• När appen körs läser implementationen in hemligheterna i nyckelvalvet. Stränghemligheten för 5000-AppSecret matchas med den programversion som anges i appens projektfil (5.0.0.0).

• Versionen ( 5000 med strecket) tas bort från nyckelnamnet. I hela appen läser läsningskonfigurationen med nyckeln AppSecret in det hemliga värdet.

• Om programversionen ändras i projektfilen till 5.1.0.0 och appen körs igen finns 5.1.0.0_secret_value_dev det hemliga värdet som returneras i Development miljön och 5.1.0.0_secret_value_prod i Production.

Binda en matris till en klass

Providern kan läsa konfigurationsvärden i en matris för bindning till en POCO-matris.

När du läser från en konfigurationskälla som gör att nycklar kan innehålla kolonavgränsare (:) används ett numeriskt nyckelsegment för att skilja mellan de nycklar som utgör en matris (:0:, :1:, ... :{n}:). Mer information finns i Konfiguration: Binda en matris till en klass.

Key Vault nycklar kan inte använda kolon (:) som avgränsare. Metoden som beskrivs i den här artikeln använder dubbla bindestreck (--) som avgränsare för hierarkiska värden (avsnitt). Matrisnycklar lagras i Key Vault med dubbla bindestreck och numeriska nyckelsegment (--0--, --1--, ... --{n}--).

Granska följande konfiguration av Serilog-loggningsprovidern som anges i en JSON-fil. Det finns två objektliteraler som definierats i matrisen WriteTo och som återspeglar två Serilog-mottagare, vilka beskriver mål för loggningsutdata.

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

Konfigurationen i JSON-filen lagras i Key Vault med hjälp av dubbel bindestreck (--) notation och numeriska segment:

Ladda om hemligheter

Som standard cachelagrar konfigurationsprovidern hemligheter för programmets livslängd. Appen ignorerar hemligheter som senare inaktiveras eller uppdateras i nyckelvalvet.

Om du vill läsa in hemligheter igen anropar du IConfigurationRoot.Reload metoden:

config.Reload();

Om du vill uppdatera hemligheter med jämna mellanrum vid ett angivet intervall, anger du AzureKeyVaultConfigurationOptions.ReloadInterval-egenskapen. Mer information finns i Konfigurationsalternativ.

Inaktiverade och utgångna hemligheter

Utgångna hemligheter ingår som standard i konfigurationsprovidern. Om du vill exkludera värden för dessa hemligheter i appkonfigurationen uppdaterar du den förfallna hemligheten eller anger konfigurationen med hjälp av en anpassad konfigurationsprovider:

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

Skicka den här anpassade KeyVaultSecretManager providern till metoden AddAzureKeyVault:

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

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

Inaktiverade hemligheter kan inte hämtas från Key Vault och ingår aldrig.

Felsöka problem med konfigurationsbelastning

När appen inte kan läsa in konfigurationen med hjälp av providern skrivs ett felmeddelande till ASP.NET Core loggningsinfrastruktur.

Följande villkor kan förhindra att konfigurationen läses in:

• Appen eller certifikatet är inte korrekt konfigurerat i Microsoft Entra-ID.
• Valvet finns inte i Azure Key Vault.
• Appen har inte behörighet att komma åt valvet.
• Åtkomstprincipen innehåller inte Get och List behörigheter.
• I valvet är konfigurationsdata (namn/värde-par) felaktigt namngivna, saknade eller inaktiverade.
• Appen har fel Key Vault-namn (KeyVaultName), Microsoft Entra ID-applikations-ID (AzureADApplicationId), Microsoft Entra ID-certifikatets tumavtryck (AzureADCertThumbprint) eller Microsoft Entra ID-katalog-ID (AzureADDirectoryId).
• När Key Vaults åtkomstprincip läggs till för appen skapas principen, men användaren valde inte Spara i dialogrutan Åtkomstprinciper.

Relaterat innehåll

• Visa eller ladda ned exempelkod (hur du laddar ned)
• Konfiguration i ASP.NET Core
• Dokumentation om Azure Key Vault
• Importera HSM-skyddade nycklar till Azure Key Vault
• Quickstart: Azure Key Vault hemligt klientbibliotek för .NET
• Självstudie: Använda Azure Key Vault med en virtuell dator i .NET

Den här artikeln beskriver hur du använder Azure Key Vault-konfigurationsprovidern för att läsa in appkonfigurationsvärden från Azure Key Vault-hemligheter. Azure Key Vault är en molnbaserad tjänst som hjälper till att skydda kryptografiska nycklar och hemligheter som används av appar och tjänster. Vanliga scenarier för att använda Azure Key Vault med ASP.NET Core-appar är:

• Kontrollera åtkomsten till känsliga konfigurationsdata.
• Uppfylla kravet på FIPS 140-2 Level 2-verifierade maskinvarusäkerhetsmoduler (HSM) när du lagrar konfigurationsdata.

Packages

Lägg till paketreferenser för följande paket:

• Azure.Extensions.AspNetCore.Configuration.Secrets
• Blått.Identity

Exempelapp

Exempelappen körs i något av två lägen som bestäms av #define förprocessordirektivet överst Program.csi :

• Certificate: Visar hur du använder ett Azure Key Vault-klient-ID och X.509-certifikat för att få åtkomst till hemligheter som lagras i Azure Key Vault. Det här exemplet kan köras från valfri plats, oavsett om det distribueras till Azure App Service eller någon värd som kan hantera en ASP.NET Core-app.
• Managed: Visar hur du använder hanterade identiteter för Azure-resurser. Den hanterade identiteten autentiserar appen till Azure Key Vault med hanterade identiteter för Azure-resurser utan autentiseringsuppgifter som lagras i appens kod eller konfiguration. När du använder hanterade identiteter för att autentisera krävs inte några hanterade identiteter för Azure-resursappens ID och lösenord (klienthemlighet). Versionen Managed av exemplet måste distribueras till Azure. Följ riktlinjerna i avsnittet Använda hanterade identiteter för Azure-resurser .

Mer information om hur du konfigurerar en exempelapp med hjälp av förprocessordirektiv (#define) finns i Översikt över ASP.NET Core.

Visa eller ladda ned exempelkod (hur du laddar ned)

Hemlig lagring i Development miljön

Ange hemligheter lokalt med Secret Manager. När exempelappen körs på den lokala datorn i Development miljön läses hemligheter in från det lokala lagringsarkivet för användarhemligheter.

Secret Manager kräver en <UserSecretsId> egenskap i appens projektfil. Ange egenskapsvärdet ({GUID}) till ett unikt GUID:

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

Hemligheter skapas som namn/värde-par. Hierarkiska värden (konfigurationsavsnitt) använder ett : (kolon) som avgränsare i ASP.NET Nyckelnamn för kärnkonfiguration .

Secret Manager används från ett kommandogränssnitt som öppnas till projektets innehållsrot, där {SECRET NAME} är namnet och {SECRET VALUE} är värdet:

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

Kör följande kommandon i ett kommandogränssnitt från projektets innehållsrot för att ange hemligheterna för exempelappen:

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

När dessa hemligheter lagras i Azure Key Vault i avsnittet Hemlig lagring i Production miljön med Azure Key Vault ändras suffixet _dev till _prod. Suffixet innehåller en visuell referens i appens utdata som anger källan till konfigurationsvärdena.

Hemlig lagring i Production miljön med Azure Key Vault

Utför följande steg för att skapa ett Azure Key Vault och lagra exempelappens hemligheter i den. Mer information finns i Snabbstart: Ange och hämta en hemlighet från Azure Key Vault med hjälp av Azure CLI.

1. Öppna Azure Cloud Shell med någon av följande metoder i Azure-portalen:

   • Välj Prova på i det övre högra hörnet av ett kodblock. Använd söksträngen "Azure CLI" i textrutan.
   • Öppna Cloud Shell i webbläsaren med knappen Starta Cloud Shell .
   • Välj knappen Cloud Shell på menyn i det övre högra hörnet i Azure-portalen.

   Mer information finns i Azure CLI och Översikt över Azure Cloud Shell.

2. Om du inte redan är autentiserad, logga in med kommandot az login.

3. Skapa en resursgrupp med följande kommando, där {RESOURCE GROUP NAME} är den nya resursgruppens namn och {LOCATION} är Azure-regionen:

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

4. Skapa ett Key Vault i resursgruppen med följande kommando, där {KEY VAULT NAME} är det nya valvets namn och {LOCATION} är Azure-regionen:

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

5. Skapa hemligheter i valvet som namn/värde-par.

   Azure Key Vault-hemliga namn är begränsade till alfanumeriska tecken och bindestreck. Hierarkiska värden (konfigurationsavsnitt) använder -- (två bindestreck) som avgränsare, eftersom kolon inte tillåts i Key Vault-hemliga namn. Kolon avgränsar ett avsnitt från en undernyckel i ASP.NET Core-konfiguration. Tvåstreckssekvensen ersätts med ett kolon när hemligheterna läses in i appens konfiguration.

   Följande hemligheter är till för användning med exempelappen. Värdena inkluderar ett _prod-suffix för att skilja dem från _dev-suffixvärdena som laddas in i Development-miljön från Secret Manager. Ersätt {KEY VAULT NAME} med namnet på nyckelvalvet som du skapade i föregående steg:

   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"
   

Använda program-ID och X.509-certifikat för appar som inte finns i Azure

Konfigurera Azure Key Vault och appen för att använda ett Microsoft Entra-ID-program-ID och X.509-certifikat för att autentisera till ett valv när appen finns utanför Azure. Mer information finns i Om nycklar, hemligheter och certifikat.

Exempelappen använder ett applikations-ID och X.509-certifikat när förprocessordirektivet #define överst i Program.cs är inställt på Certificate.

1. Skapa ett PKCS#12-arkivcertifikat (.pfx). Alternativen för att skapa certifikat är New-SelfSignedCertificate i Windows och OpenSSL.
2. Installera certifikatet i den aktuella användarens personliga certifikatarkiv. Det är valfritt att markera nyckeln som exporterbar. Observera certifikatets tumavtryck, som används senare i den här processen.
3. Exportera PKCS#12-arkivcertifikatet (.pfx) som ett DER-kodat certifikat (.cer).
4. Registrera appen med Microsoft Entra-ID (appregistreringar).
5. Ladda upp det DER-kodade certifikatet (.cer) till Microsoft Entra-ID:
   1. Välj appen i Microsoft Entra-ID.
   2. Gå till Certifikat och hemligheter.
   3. Välj Ladda upp certifikat för att ladda upp certifikatet, som innehåller den offentliga nyckeln. Ett .cer-, .pem- eller .crt-certifikat är acceptabelt .
6. Lagra Key Vault-namnet, program-ID:t och certifikatets tumavtryck i appens appsettings.json fil.
7. Navigera till Key Vaults i Azure-portalen.
8. Välj det Nyckelvalv som du skapade i avsnittet Hemlig lagring i Production miljön med Azure Key Vault .
9. Välj åtkomstprinciper.
10. Välj Lägg till åtkomstprincip.
11. Öppna hemliga behörigheter och ge appen behörighet att hämta och lista .
12. Välj Välj huvudnamn och välj den registrerade appen efter namn. Välj knappen Välj.
13. Välj OK.
14. Välj Spara.
15. Distribuera appen.

Exempelappen Certificate hämtar sina konfigurationsvärden från IConfigurationRoot med samma namn som det hemliga namnet:

• Icke-hierarkiska värden: Värdet för SecretName hämtas med config["SecretName"].
• Hierarkiska värden (avsnitt): Använd : (kolon) notation eller GetSection metoden. Använd någon av dessa metoder för att hämta konfigurationsvärdet:
  • config["Section:SecretName"]
  • config.GetSection("Section")["SecretName"]

X.509-certifikatet hanteras av operativsystemet. Appen anropar AddAzureKeyVault med värden som tillhandahålls av appsettings.json filen:

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

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

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

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

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

Exempelvärden:

• Key Vault-namn: contosovault
• Applikations-ID: 00001111-aaaa-2222-bbbb-3333cccc4444
• Certifikatets tumavtryck: fe14593dd66b2406c5269d742d04b6e1ab03adb1

appsettings.json:

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

När du kör appen visar en webbsida de inlästa hemliga värdena. Development I miljön läses hemliga värden in med suffixet_dev. I denna Production miljö läses värdena in med suffixet _prod.

Använda hanterade identiteter för Azure-resurser

En app som distribueras till Azure kan dra nytta av hanterade identiteter för Azure-resurser. Med en hanterad identitet kan appen autentisera med Azure Key Vault med hjälp av Microsoft Entra ID-autentisering utan autentiseringsuppgifter (program-ID och lösenord/klienthemlighet) som lagras i appen.

Exempelappen använder hanterade identiteter för Azure-resurser när förprocessordirektivet #define överst i Program.cs är inställt på Managed.

Ange valvnamnet i appens appsettings.json fil. Exempelappen kräver inte något program-ID och lösenord (klienthemlighet) när den är inställd på Managed versionen, så du kan ignorera dessa konfigurationsposter. Appen distribueras till Azure och Azure autentiserar appen för åtkomst till Azure Key Vault endast med valvnamnet som lagras i appsettings.json filen.

Distribuera exempelappen till Azure App Service.

En app som distribueras till Azure App Service registreras automatiskt med Microsoft Entra-ID när tjänsten skapas. Hämta objekt-ID:t från distributionen för användning i följande kommando. Objekt-ID visas i Azure-portalen på panelen Identity i App Service.

Använd Azure CLI och appens objekt-ID och ge appen listget behörighet att komma åt valvet:

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

Starta om appen med Hjälp av Azure CLI, PowerShell eller Azure-portalen.

Exempelappen:

• Skapar en instans av DefaultAzureCredential klassen. Autentiseringsuppgifterna försöker hämta en åtkomsttoken från miljön för Azure-resurser.
• En ny SecretClient skapas med instansen DefaultAzureCredential .
• Instansen SecretClient används med en KeyVaultSecretManager instans som läser in hemliga värden och ersätter dubbelstreck (--) med kolon (:) i nyckelnamn.

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

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

Exempelvärde för Key Vault-namn: contosovault

appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

När du kör appen visar en webbsida de inlästa hemliga värdena. Development I miljön har hemliga värden suffixet _dev eftersom de tillhandahålls av Secret Manager. Production I miljön läses värdena in med suffixet _prod eftersom de tillhandahålls av Azure Key Vault.

Om du får ett Access denied fel kontrollerar du att appen är registrerad med Microsoft Entra-ID och har gett åtkomst till valvet. Bekräfta att du har startat om tjänsten i Azure.

Information om hur du använder providern med en hanterad identitet och Azure-pipelines finns i Skapa en Azure Resource Manager-tjänstanslutning till en virtuell dator med en hanterad tjänstidentitet.

Konfigurationsalternativ

AddAzureKeyVault kan acceptera ett AzureKeyVaultConfigurationOptions objekt:

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

Objektet AzureKeyVaultConfigurationOptions innehåller följande egenskaper.

Använd ett nyckelnamnsprefix

AddAzureKeyVault tillhandahåller en överlagring som accepterar en implementering av KeyVaultSecretManager, som gör att du kan styra hur Key Vault-hemligheter konverteras till konfigurationsnycklar. Du kan till exempel implementera gränssnittet för att läsa in hemliga värden baserat på ett prefixvärde som du anger vid appstart. Med den här tekniken kan du till exempel läsa in hemligheter baserat på appens version.

I följande exempel upprättas en hemlighet i Key Vault (och använder Secret Manager för Development miljön) för 5000-AppSecret (perioder tillåts inte i Key Vault-hemliga namn). Den här hemligheten representerar en apphemlighet för version 5.0.0.0 av appen. I version 5.1.0.0 av en annan version av appen läggs en hemlighet till i valvet med hjälp av Secret Manager för 5100-AppSecret. Varje appversion läser in sitt versionshemlighetsvärde i konfigurationen som AppSecretoch tar bort versionen när den läser in hemligheten.

AddAzureKeyVault anropas med en anpassad KeyVaultSecretManager-implementering:

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

Implementeringen reagerar på versionsprefixen för hemligheter för att läsa in rätt hemlighet i konfigurationen:

• Load läser in en hemlighet när namnet börjar med prefixet. Andra hemligheter laddas inte.
• GetKey:
  • Tar bort prefixet från det hemliga namnet.
  • Ersätter två bindestreck i valfritt namn med KeyDelimiter, som är avgränsare som används i konfigurationen (vanligtvis ett kolon). Azure Key Vault tillåter inte ett kolon i hemliga namn.

public class PrefixKeyVaultSecretManager : KeyVaultSecretManager
{
    private readonly string _prefix;

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

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

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

Metoden Load anropas av en leverantörsalgoritm som itererar genom valvets hemligheter för att hitta hemligheter med versionsprefix. När ett versionsprefix hittas med Loadanvänder algoritmen GetKey metoden för att returnera konfigurationsnamnet för det hemliga namnet. Det tar bort versionsprefixet från hemlighetens namn. Resten av det hemliga namnet returneras för inläsning i appens konfigurationsnamn/värde-par.

När den här metoden implementeras:

1. Appens version som anges i appens projektfil. I följande exempel är appens version inställd på 5.0.0.0:

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

2. Bekräfta att en <UserSecretsId> egenskap finns i appens projektfil, där {GUID} är ett användardefinerat GUID:

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

   Spara följande hemligheter lokalt med Secret Manager:

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

3. Hemligheter sparas i Azure Key Vault med hjälp av följande Azure CLI-kommandon:

   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. När appen körs läses Key Vault-hemligheterna in. Stränghemligheten för 5000-AppSecret matchas med appens version som anges i appens projektfil (5.0.0.0).

5. Versionen ( 5000 med strecket) tas bort från nyckelnamnet. I hela appen läser läsningskonfigurationen med nyckeln AppSecret in det hemliga värdet.

6. Om appens version ändras i projektfilen till 5.1.0.0 och appen körs igen är 5.1.0.0_secret_value_dev det hemliga värdet som returneras i Development miljön och 5.1.0.0_secret_value_prod i Production.

Binda en matris till en klass

Providern kan läsa konfigurationsvärden i en matris för bindning till en POCO-matris.

När du läser från en konfigurationskälla som gör att nycklar kan innehålla kolonavgränsare (:) används ett numeriskt nyckelsegment för att skilja mellan de nycklar som utgör en matris (:0:, :1:, ... :{n}:). Mer information finns i Konfiguration: Binda en matris till en klass.

Azure Key Vault-nycklar kan inte använda ett kolon som avgränsare. Metoden som beskrivs i den här artikeln använder dubbla bindestreck (--) som avgränsare för hierarkiska värden (avsnitt). Matrisnycklar lagras i Azure Key Vault med dubbla bindestreck och numeriska nyckelsegment (--0--, , --1--... --{n}--).

Granska följande konfiguration av Serilog-loggningsprovidern som tillhandahålls av en JSON-fil. Det finns två objektliteraler som definierats i matrisen WriteTo och som återspeglar två Serilog-mottagare, vilka beskriver mål för loggningsutdata.

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

Konfigurationen som visas i den föregående JSON-filen lagras i Azure Key Vault med notationen med dubbla bindestreck (--) och numeriska segment.

Ladda om hemligheter

Hemligheter cachelagras tills det IConfigurationRoot.Reload anropas. Därefter kommer inaktiverade eller uppdaterade hemligheter i valvet inte att respekteras av appen förrän Reload körs.

Configuration.Reload();

Inaktiverade och utgångna hemligheter

Utgångna hemligheter ingår som standard i konfigurationsprovidern. Om du vill exkludera värden för dessa hemligheter i appkonfigurationen uppdaterar du hemligheten som har upphört att gälla eller anger konfigurationen med hjälp av en anpassad konfigurationsprovider:

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

Skicka denna anpassade KeyVaultSecretManager till AddAzureKeyVault:

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

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

Inaktiverade hemligheter kan inte hämtas från Key Vault och ingår aldrig.

Troubleshoot

När appen inte kan läsa in konfigurationen med providern skrivs ett felmeddelande till ASP.NET Core Logging-infrastrukturen. Följande villkor förhindrar att konfigurationen läses in:

• Appen eller certifikatet är inte korrekt konfigurerat i Microsoft Entra-ID.
• Valvet finns inte i Azure Key Vault.
• Appen har inte behörighet att komma åt valvet.
• Åtkomstprincipen innehåller inte Get och List behörigheter.
• I valvet är konfigurationsdata (namn/värde-par) felaktigt namngivna, saknade eller inaktiverade.
• Appen har fel Key Vault-namn (KeyVaultName), Microsoft Entra ID-program-ID (AzureADApplicationId), Microsoft Entra ID-certifikattumavtryck (AzureADCertThumbprint), eller Microsoft Entra ID-katalog-ID (AzureADDirectoryId).
• När du lade till Key Vault-åtkomstprincipen för appen skapades principen, men knappen Spara valdes inte i användargränssnittet för åtkomstprinciper .

Ytterligare resurser

• Visa eller ladda ned exempelkod (hur du laddar ned)
• Konfiguration i ASP.NET Core
• Microsoft Azure: Dokumentation om Key Vault
• Så här genererar och överför du HSM-skyddade nycklar för Azure Key Vault
• Snabbstart: Ange och hämta en hemlighet från Azure Key Vault med hjälp av en .NET-webbapp
• Självstudie: Använda Azure Key Vault med Azure Windows Virtual Machine i .NET