Azure Key Vault-konfigurationsprovider i ASP.NET Core

2025-06-24

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:

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 att lagra autentiseringsuppgifter i appens kod eller konfiguration. 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 utvecklingsmiljön

Ange hemligheter lokalt med Secret Manager. När exempelappen körs på den lokala datorn i utvecklingsmiljö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 produktionsmiljö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 produktionsmiljö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.

Ö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.
Om du inte redan är autentiserad, logga in med kommandot az login.
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}
```
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}
```
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 innehåller ett _prod suffix för att skilja dem från _dev de suffixvärden som läses in i utvecklingsmiljö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.

Note

Även om användning av ett program-ID och X.509-certifikat stöds för appar som finns i Azure rekommenderas det inte. Använd i stället Hanterade identiteter för Azure-resurser när du är värd för en app i Azure. Hanterade identiteter kräver inte lagring av ett certifikat i appen eller i utvecklingsmiljön.

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

Skapa ett PKCS#12-arkivcertifikat (.pfx). Alternativen för att skapa certifikat är New-SelfSignedCertificate i Windows och OpenSSL.
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.
Exportera PKCS#12-arkivcertifikatet (.pfx) som ett DER-kodat certifikat (.cer).
Registrera appen med Microsoft Entra-ID (appregistreringar).
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 .
Lagra Key Vault-namnet, program-ID:t och certifikatets tumavtryck i appens appsettings.json fil.
Navigera till Key Vaults i Azure-portalen.
Välj det Nyckelvalv som du skapade i avsnittet Hemlig lagring i produktionsmiljön med Azure Key Vault .
Välj åtkomstprinciper.
Välj Lägg till åtkomstprincip.
Öppna hemliga behörigheter och ge appen behörighet att hämta och lista .
Välj Välj huvudnamn och välj den registrerade appen efter namn. Välj knappen Välj.
Välj OK.
Välj Spara.
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.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:

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. I utvecklingsmiljön läses hemliga värden in med suffixet _dev . I produktionsmiljön 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 appens kod eller konfiguration.

Exempelappen använder en systemtilldelad hanterad identitet när förprocessordirektivet #define högst upp i 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 appens objekt-ID som visas i Azure-portalen på Identity panelen i App Service.

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.

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:

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

Note

I föregående exempel används DefaultAzureCredential för att förenkla autentiseringen vid utveckling av appar som distribueras till Azure genom att kombinera autentiseringsuppgifter som används i Azure-värdmiljöer med autentiseringsuppgifter som används i lokal utveckling. När du flyttar till produktion är ett bättre alternativ till exempel ManagedIdentityCredential. Mer information finns i Autentisera Azure-hostade .NET-appar till Azure-resurser med en systemtilldelad hanterad identitet.

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

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:

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. I utvecklingsmiljön har hemliga värden suffixet _dev eftersom de tillhandahålls av Secret Manager. I produktionsmiljö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:

// 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:

Property	Description
Manager	KeyVaultSecretManager instans som används för att kontrollera inläsning av känslig information.
ReloadInterval	`TimeSpan` för att vänta mellan försök att kontrollera valvet efter ändringar. Standardvärdet är `null` (konfigurationen laddas inte om).

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.

Warning

Använd inte prefix på Key Vault-hemligheter för att:

Lägg hemligheter för flera appar i samma valv.
Placera miljöhemligheter (till exempel utvecklings- och produktionshemligheter ) i samma valv.

Olika appar och utvecklings-/produktionsmiljöer bör använda separata Key Vaults för att isolera appmiljöer för den högsta säkerhetsnivån.

I följande exempel upprättas en hemlighet i Key Vault (och använder Secret Manager för utvecklingsmiljö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:

// 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:

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

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:

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>
```

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"

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"

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).
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 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 utvecklingsmiljön och 5.1.0.0_secret_value_prod i Produktion.

Note

Du kan också ange din egen SecretClient implementering för AddAzureKeyVault. En anpassad klient tillåter delning av en enda instans av klienten i appen.

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.

Key	Value
`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==`

Läsa in hemligheter igen

Som standard cachelagras hemligheter av konfigurationsprovidern för appens livslängd. Hemligheter som senare har inaktiverats eller uppdaterats i valvet ignoreras av appen.

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

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

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.

Note

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

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:

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 utvecklingsmiljön

Ange hemligheter lokalt med Secret Manager. När exempelappen körs på den lokala datorn i utvecklingsmiljö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"

Hemlig lagring i produktionsmiljön med Azure Key Vault

Ö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.
Om du inte redan är autentiserad, logga in med kommandot az login.
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}
```
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}
```
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 innehåller ett _prod suffix för att skilja dem från _dev de suffixvärden som läses in i utvecklingsmiljö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

Note

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

Skapa ett PKCS#12-arkivcertifikat (.pfx). Alternativen för att skapa certifikat är New-SelfSignedCertificate i Windows och OpenSSL.
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.
Exportera PKCS#12-arkivcertifikatet (.pfx) som ett DER-kodat certifikat (.cer).
Registrera appen med Microsoft Entra-ID (appregistreringar).
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 .
Lagra Key Vault-namnet, program-ID:t och certifikatets tumavtryck i appens appsettings.json fil.
Navigera till Key Vaults i Azure-portalen.
Välj det Nyckelvalv som du skapade i avsnittet Hemlig lagring i produktionsmiljön med Azure Key Vault .
Välj åtkomstprinciper.
Välj Lägg till åtkomstprincip.
Öppna hemliga behörigheter och ge appen behörighet att hämta och lista .
Välj Välj huvudnamn och välj den registrerade appen efter namn. Välj knappen Välj.
Välj OK.
Välj Spara.
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. I utvecklingsmiljön läses hemliga värden in med suffixet _dev . I produktionsmiljön 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.

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

Note

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

appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

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.

Konfigurationsalternativ

AddAzureKeyVault kan acceptera ett AzureKeyVaultConfigurationOptions objekt:

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

Note

Objektet AzureKeyVaultConfigurationOptions innehåller följande egenskaper.

Property	Description
Manager	KeyVaultSecretManager instans som används för att kontrollera inläsning av känslig information.
ReloadInterval	`TimeSpan` för att vänta mellan försök att kontrollera valvet efter ändringar. Standardvärdet är `null` (konfigurationen laddas inte om).

Använd ett nyckelnamnsprefix

Warning

Använd inte prefix på Key Vault-hemligheter för att:

Lägg hemligheter för flera appar i samma valv.
Placera miljöhemligheter (till exempel utvecklings- och produktionshemligheter ) i samma valv.

Olika appar och utvecklings-/produktionsmiljöer bör använda separata Key Vaults för att isolera appmiljöer för den högsta säkerhetsnivån.

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

När den här metoden implementeras:

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>
```

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"

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"

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).
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 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 utvecklingsmiljön och 5.1.0.0_secret_value_prod i Produktion.

Note

Du kan också ange din egen SecretClient implementering för AddAzureKeyVault. En anpassad klient tillåter delning av en enda instans av klienten i appen.

Binda en matris till en klass

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

"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.

Key	Value
`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==`

Läsa in hemligheter igen

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

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.

Note

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

Feedback

Var den här sidan till hjälp?

Dela via

Azure Key Vault-konfigurationsprovider i ASP.NET Core

Packages

Exempelapp

Hemlig lagring i utvecklingsmiljön

Hemlig lagring i produktionsmiljön med Azure Key Vault

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

Använda hanterade identiteter för Azure-resurser

Konfigurationsalternativ

Använd ett nyckelnamnsprefix

Binda en matris till en klass

Läsa in hemligheter igen

Inaktiverade och utgångna hemligheter

Troubleshoot

Ytterligare resurser

Packages

Exempelapp

Hemlig lagring i utvecklingsmiljön

Hemlig lagring i produktionsmiljön med Azure Key Vault

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

Använda hanterade identiteter för Azure-resurser

Konfigurationsalternativ

Använd ett nyckelnamnsprefix

Binda en matris till en klass

Läsa in hemligheter igen

Inaktiverade och utgångna hemligheter

Troubleshoot

Ytterligare resurser

Feedback

Ytterligare resurser