Zprostředkovatel konfigurace služby Azure Key Vault v ASP.NET Core

Článek
11/06/2024

Tento článek vysvětluje, jak pomocí zprostředkovatele konfigurace služby Azure Key Vault načíst hodnoty konfigurace aplikace z tajných kódů služby Azure Key Vault. Azure Key Vault je cloudová služba, která pomáhá chránit kryptografické klíče a tajné kódy používané aplikacemi a službami. Mezi běžné scénáře použití služby Azure Key Vault s aplikacemi ASP.NET Core patří:

Řízení přístupu k citlivým konfiguračním datům
Při ukládání konfiguračních dat splňuje požadavek na ověření modulů hardwarového zabezpečení (HSM) pro FIPS 140-2 Level 2.

Balíčky

Přidejte odkazy na balíčky pro následující balíčky:

Ukázková aplikace

Ukázková aplikace se spouští v některém ze dvou režimů určených direktivou #define preprocesoru v horní části Program.cs:

Certificate: Ukazuje použití ID klienta služby Azure Key Vault a certifikátu X.509 pro přístup k tajným kódům uloženým ve službě Azure Key Vault. Tuto ukázku je možné spustit z libovolného umístění bez ohledu na to, jestli se nasadí do služby Aplikace Azure Service nebo z libovolného hostitele, který může obsluhovat aplikaci ASP.NET Core.
Managed: Ukazuje, jak používat spravované identity pro prostředky Azure. Spravovaná aplikace identity ověří ve službě Azure Key Vault pomocí spravovaných identit pro prostředky Azure bez uložení přihlašovacích údajů v kódu nebo konfiguraci aplikace. Verze Managed ukázky se musí nasadit do Azure. Postupujte podle pokynů v části Použití spravovaných identit pro prostředky Azure.

Další informace o konfiguraci ukázkové aplikace pomocí direktiv preprocesoru (#define) najdete v tématu Přehled ASP.NET Core.

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Úložiště tajných kódů ve vývojovém prostředí

Místní nastavení tajných kódů pomocí Správce tajných kódů Když ukázková aplikace běží na místním počítači ve vývojovém prostředí, tajné kódy se načtou z místního úložiště tajných kódů uživatelů.

Správce tajných kódů vyžaduje <UserSecretsId> vlastnost v souboru projektu aplikace. Nastavte hodnotu vlastnosti ({GUID}) na libovolný jedinečný identifikátor GUID:

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

Tajné kódy se vytvářejí jako páry název-hodnota. Hierarchické hodnoty (oddíly konfigurace) používají : (dvojtečku) jako oddělovač v názvech konfiguračních klíčů ASP.NET Core.

Správce tajných kódů se používá z příkazového prostředí otevřeného v kořenovém adresáři obsahu projektu, kde {SECRET NAME} je název a {SECRET VALUE}hodnota:

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

Spuštěním následujících příkazů v příkazovém prostředí z kořenového adresáře obsahu projektu nastavte tajné kódy pro ukázkovou aplikaci:

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

Pokud jsou tyto tajné kódy uložené ve službě Azure Key Vault v úložišti tajných kódů v produkčním prostředí s částí Azure Key Vault , _dev přípona se změní na _prod. Přípona poskytuje vizuální upozornění ve výstupu aplikace označující zdroj hodnot konfigurace.

Úložiště tajných kódů v produkčním prostředí se službou Azure Key Vault

Pomocí následujících kroků vytvořte službu Azure Key Vault a uložte do ní tajné kódy ukázkové aplikace. Další informace najdete v tématu Rychlý start: Nastavení a načtení tajného kódu ze služby Azure Key Vault pomocí Azure CLI.

Otevřete Azure Cloud Shell pomocí některé z následujících metod na webu Azure Portal:
- Zvolte Vyzkoušet v pravém horním rohu bloku kódu. V textovém poli použijte hledaný řetězec Azure CLI.
- V prohlížeči otevřete Cloud Shell pomocí tlačítka Spustit Cloud Shell .
- V nabídce v pravém horním rohu webu Azure Portal vyberte tlačítko Cloud Shell.
Další informace najdete v tématu Azure CLI a přehled služby Azure Cloud Shell.
Pokud ještě nejste ověřeni, přihlaste se pomocí az login příkazu.
Vytvořte skupinu prostředků pomocí následujícího příkazu, kde {RESOURCE GROUP NAME} je název nové skupiny prostředků a {LOCATION} oblast Azure:
```
az group create --name "{RESOURCE GROUP NAME}" --location {LOCATION}
```
Ve skupině prostředků vytvořte službu Key Vault pomocí následujícího příkazu, kde {KEY VAULT NAME} je název nového trezoru a {LOCATION} oblast Azure:
```
az keyvault create --name {KEY VAULT NAME} --resource-group "{RESOURCE GROUP NAME}" --location {LOCATION}
```
Vytvořte v trezoru tajné kódy jako páry název-hodnota.

Názvy tajných kódů služby Azure Key Vault jsou omezené na alfanumerické znaky a pomlčky. Hierarchické hodnoty (oddíly konfigurace) používají -- (dvě pomlčky) jako oddělovač, protože dvojtečky nejsou povolené v názvech tajných kódů služby Key Vault. Dvojtečky odděluje oddíl od podklíče v konfiguraci ASP.NET Core. Dvoumlčka se nahradí dvojtečkou, když se tajné kódy načtou do konfigurace aplikace.

Následující tajné kódy se používají s ukázkovou aplikací. Mezi hodnoty patří _prod přípona, která je odlišuje od _dev hodnot přípon načtených ve vývojovém prostředí z nástroje Secret Manager. Nahraďte {KEY VAULT NAME} názvem služby Key Vault, který jste vytvořili v předchozím 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"
```

Použití ID aplikace a certifikátu X.509 pro aplikace hostované mimo Azure

Nakonfigurujte Azure Key Vault a aplikaci tak, aby používaly ID aplikace Microsoft Entra ID a certifikát X.509 k ověření v trezoru , když je aplikace hostovaná mimo Azure. Další informace najdete v tématu O klíčích, tajných klíčích a certifikátech.

Poznámka:

I když je použití ID aplikace a certifikátu X.509 podporované pro aplikace hostované v Azure, nedoporučuje se. Místo toho při hostování aplikace v Azure používejte spravované identity pro prostředky Azure. Spravované identity nevyžadují uložení certifikátu v aplikaci nebo ve vývojovém prostředí.

Ukázková aplikace používá ID aplikace a certifikát X.509, pokud #define je direktiva preprocesoru v horní části Program.cs nastavena na Certificate.

Vytvořte archivní certifikát PKCS#12 (.pfx). Možnosti vytváření certifikátů zahrnují New-SelfSignedCertificate ve Windows a OpenSSL.
Nainstalujte certifikát do osobního úložiště certifikátů aktuálního uživatele. Označení klíče jako exportovatelného je volitelné. Poznamenejte si kryptografický otisk certifikátu, který se používá později v tomto procesu.
Exportujte certifikát PKCS#12 archivu (.pfx) jako certifikát s kódováním DER (.cer).
Zaregistrujte aplikaci pomocí Microsoft Entra ID (Registrace aplikací).
Nahrajte certifikát s kódováním DER (.cer) do MICROSOFT Entra ID:
1. Vyberte aplikaci v Microsoft Entra ID.
2. Přejděte na Certifikáty a tajné kódy.
3. Vyberte Nahrát certifikát a nahrajte certifikát, který obsahuje veřejný klíč. Certifikát .cer, .pem nebo .crt je přijatelný.
Do souboru aplikace appsettings.json uložte název služby Key Vault, ID aplikace a kryptografický otisk certifikátu.
Na webu Azure Portal přejděte ke službě Key Vault.
V části Azure Key Vault vyberte službu Key Vault, kterou jste vytvořili v úložišti tajných kódů v produkčním prostředí.
Vyberte Zásady přístupu.
Vyberte Přidat zásady přístupu.
Otevřete oprávnění tajného kódu a poskytněte aplikaci oprávnění Získat a vypsat .
Vyberte objekt zabezpečení a vyberte zaregistrovanou aplikaci podle názvu. Zvolte tlačítko Vybrat.
Vyberte OK.
Zvolte Uložit.
Nasaďte aplikaci.

Ukázková Certificate aplikace získá své konfigurační hodnoty se IConfigurationRoot stejným názvem jako název tajného kódu:

Ne hierarchické hodnoty: Hodnota pro SecretName je získána pomocí config["SecretName"].
Hierarchické hodnoty (oddíly): Použijte : (dvojtečka) notaci nebo metodu GetSection . K získání hodnoty konfigurace použijte některý z těchto přístupů:
- config["Section:SecretName"]
- config.GetSection("Section")["SecretName"]

Certifikát X.509 spravuje operační systém. Aplikace volá AddAzureKeyVault hodnoty zadané souborem appsettings.json :


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

Ukázkové hodnoty:

Název služby Key Vault: contosovault
ID aplikace: 00001111-aaaa-2222-bbbb-3333cccc4444
Kryptografický otisk certifikátu: fe14593dd66b2406c5269d742d04b6e1ab03adb1

appsettings.json:

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

Při spuštění aplikace se na webové stránce zobrazí načtené tajné hodnoty. Ve vývojovém prostředí se tajné hodnoty načítají s příponou _dev . V produkčním prostředí se hodnoty načítají s příponou _prod .

Použití spravovaných identit pro prostředky Azure

Aplikace nasazená do Azure může využívat spravované identity pro prostředky Azure. Spravovaná identity aplikace umožňuje ověřování pomocí služby Azure Key Vault pomocí ověřování Microsoft Entra ID bez uložení přihlašovacích údajů v kódu nebo konfiguraci aplikace.

Ukázková aplikace používá spravovanou správu identity přiřazenou systémem, když #define je direktiva preprocesoru v horní části Program.cs nastavena na Managedhodnotu . Pokud chcete vytvořit spravovanou identity aplikaci Aplikace Azure Service, přečtěte si téma Použití spravovaných identit pro App Service a Azure Functions. Po vytvoření spravovaného identity objektu si poznamenejte ID objektu aplikace zobrazené na webu Azure Portal na Identity panelu služby App Service.

Do souboru aplikace zadejte název trezoru appsettings.json . Ukázková aplikace nevyžaduje ID aplikace a heslo (tajný klíč klienta) při nastavení verze Managed , takže tyto položky konfigurace můžete ignorovat. Aplikace se nasadí do Azure a Azure ji ověří pro přístup ke službě Azure Key Vault jenom pomocí názvu trezoru uloženého appsettings.json v souboru.

Nasaďte ukázkovou aplikaci do služby Aplikace Azure Service.

Pomocí Azure CLI a ID objektu aplikace zadejte aplikaci a list get oprávnění pro přístup k trezoru:

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

Restartujte aplikaci pomocí Azure CLI, PowerShellu nebo webu Azure Portal.

Ukázková aplikace vytvoří instanci DefaultAzureCredential třídy. Přihlašovací údaje se pokusí získat přístupový token z prostředí pro prostředky 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());
}

Příklad hodnoty názvu služby Key Vault: contosovault

appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

Pro aplikace, které používají spravované uživatelem identity, nakonfigurujte ID spravovaného identityklienta pomocí jednoho z následujících přístupů:

Nastavte proměnnou prostředí AZURE_CLIENT_ID.

DefaultAzureCredentialOptions.ManagedIdentityClientId Nastavte vlastnost při voláníAddAzureKeyVault:

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

Při spuštění aplikace se na webové stránce zobrazí načtené tajné hodnoty. Ve vývojovém prostředí mají tajné hodnoty příponu _dev , protože je poskytuje Secret Manager. V produkčním prostředí se hodnoty načítají s příponou _prod , protože je poskytuje Služba Azure Key Vault.

Pokud se zobrazí Access denied chyba, ověřte, že je aplikace zaregistrovaná pomocí ID Microsoft Entra a že poskytuje přístup k trezoru. Potvrďte, že jste službu restartovali v Azure.

Informace o použití poskytovatele se spravovanými identity službami a Azure Pipelines najdete v tématu Vytvoření připojení služby Azure Resource Manager k virtuálnímu počítači se spravovanou službou identity.

Možnosti konfigurace

AddAzureKeyVault může přijmout AzureKeyVaultConfigurationOptions objekt:

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

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

Objekt AzureKeyVaultConfigurationOptions obsahuje následující vlastnosti:

Vlastnost	Popis
Manager	KeyVaultSecretManager instance použitá k řízení načítání tajných kódů.
ReloadInterval	`TimeSpan` počkat mezi pokusy při dotazování trezoru na změny. Výchozí hodnota je `null` (konfigurace se znovu nenačte).

Použití předpony názvu klíče

AddAzureKeyVault poskytuje přetížení, které přijímá implementaci KeyVaultSecretManager, což umožňuje řídit, jak se tajné kódy Key Vault převádějí na konfigurační klíče. Můžete například implementovat rozhraní pro načtení tajných hodnot na základě hodnoty předpony, kterou zadáte při spuštění aplikace. Tato technika vám například umožňuje načíst tajné kódy na základě verze aplikace.

Upozorňující

Nepoužívejte předpony u tajných kódů služby Key Vault k:

Tajné kódy pro více aplikací umístěte do stejného trezoru.
Umístěte tajné kódy prostředí (například vývoj a produkční tajné kódy) do stejného trezoru.

Různé aplikace a vývojová/produkční prostředí by měly používat samostatné trezory klíčů k izolaci aplikačních prostředí pro nejvyšší úroveň zabezpečení.

V následujícím příkladu se tajný kód vytvoří ve službě Key Vault (a pomocí Správce tajných kódů pro vývojové prostředí) pro 5000-AppSecret (období nejsou povolená v názvech tajných kódů služby Key Vault). Tento tajný kód představuje tajný kód aplikace pro verzi 5.0.0.0 aplikace. Pro jinou verzi aplikace 5.1.0.0 se do trezoru (a pomocí Správce tajných kódů) přidá tajný kód pro 5100-AppSecret. Každá verze aplikace načte svou hodnotu tajného kódu verze do své konfigurace, protože AppSecretodebírá verzi při načítání tajného kódu.

AddAzureKeyVault se volá s vlastní KeyVaultSecretManager implementací:

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

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

Implementace reaguje na předpony verzí tajných kódů za účelem načtení správného tajného kódu do konfigurace:

Load načte tajný kód, když jeho název začíná předponou. Jiné tajné kódy se nenačtou.
GetKey:
- Odebere předponu z názvu tajného kódu.
- Nahradí dvě pomlčky v libovolném názvu znakem KeyDelimiter, což je oddělovač použitý v konfiguraci (obvykle dvojtečka). Azure Key Vault neumožňuje dvojtečku v názvech tajných kódů.

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 je volána algoritmem zprostředkovatele, který iteruje prostřednictvím tajných kódů trezoru a vyhledá tajné kódy s předponou verze. Pokud je nalezena Loadpředpona verze , algoritmus používá GetKey metodu k vrácení názvu konfigurace názvu tajného kódu. Odebere předponu verze z názvu tajného kódu. Název rest tajného kódu se vrátí pro načtení do párů název-hodnota konfigurace aplikace.

Při implementaci tohoto přístupu:

Verze aplikace zadaná v souboru projektu aplikace. V následujícím příkladu je verze aplikace nastavená na 5.0.0.0:
```
<PropertyGroup>
  <Version>5.0.0.0</Version>
</PropertyGroup>
```

Ověřte, že <UserSecretsId> se vlastnost nachází v souboru projektu aplikace, kde {GUID} je identifikátor GUID zadaný uživatelem:

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

Pomocí Správce tajných kódů uložte následující tajné kódy místně:

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"

Tajné kódy se ukládají ve službě Azure Key Vault pomocí následujících příkazů Azure CLI:

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"

Při spuštění aplikace se načtou tajné kódy služby Key Vault. Tajný klíč 5000-AppSecret řetězce se shoduje s verzí aplikace zadanou v souboru projektu aplikace (5.0.0.0).
5000 Verze (s pomlčkou) je z názvu klíče odebrána. V celé aplikaci se při čtení konfigurace s klíčem načte hodnota tajného klíče AppSecret .
Pokud se v souboru 5.1.0.0 projektu změní verze aplikace a aplikace se spustí znovu, vrátí 5.1.0.0_secret_value_dev se vrácená hodnota tajného kódu ve vývojovém prostředí a 5.1.0.0_secret_value_prod v produkčním prostředí.

Poznámka:

Můžete také poskytnout vlastní SecretClient implementaci pro AddAzureKeyVault. Vlastní klient umožňuje sdílet jednu instanci klienta v rámci aplikace.

Vytvoření vazby pole ke třídě

Zprostředkovatel může číst konfigurační hodnoty do pole pro vazbu na pole POCO.

Při čtení ze zdroje konfigurace, který umožňuje klíčům obsahovat oddělovače dvojtečky (:) je použit číselný segment klíče k rozlišení klíčů, které tvoří pole (:0:, :1:... :{n}:). Další informace naleznete v tématu Konfigurace: Vytvoření vazby pole ke třídě.

Klíče služby Azure Key Vault nemůžou jako oddělovač používat dvojtečku. Přístup popsaný v tomto článku používá dvojité pomlčky (--) jako oddělovač pro hierarchické hodnoty (oddíly). Klíče pole jsou uloženy ve službě Azure Key Vault s dvojitými pomlčkami a číselnými segmenty klíčů (--0--, ... --1----{n}--).

Prozkoumejte následující konfiguraci zprostředkovatele protokolování Serilog , kterou poskytuje soubor JSON. V poli jsou definovány WriteTo dva literály objektů, které odrážejí dvě jímky Serilog, které popisují cíle pro protokolování výstupu:

"Serilog": {
  "WriteTo": [
    {
      "Name": "AzureTableStorage",
      "Args": {
        "storageTableName": "logs",
        "connectionString": "DefaultEnd...ountKey=Eby8...GMGw=="
      }
    },
    {
      "Name": "AzureDocumentDB",
      "Args": {
        "endpointUrl": "https://contoso.documents.azure.com:443",
        "authorizationKey": "Eby8...GMGw=="
      }
    }
  ]
}

Konfigurace zobrazená v předchozím souboru JSON je uložená ve službě Azure Key Vault pomocí dvoumlčky (--) notace a číselných segmentů:

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

Opětovné načtení tajných kódů

Ve výchozím nastavení jsou tajné kódy uložené v mezipaměti poskytovatelem konfigurace po celou dobu života aplikace. Aplikace následně zakázala nebo aktualizovala tajné kódy v trezoru.

Pokud chcete znovu načíst tajné kódy, zavolejte IConfigurationRoot.Reload:

config.Reload();

Chcete-li znovu načíst tajné kódy pravidelně, v zadaném intervalu AzureKeyVaultConfigurationOptions.ReloadInterval nastavte vlastnost. Další informace naleznete v tématu Možnosti konfigurace.

Zakázané a prošlé tajné kódy

Tajné kódy s vypršenou platností jsou ve výchozím nastavení součástí zprostředkovatele konfigurace. Pokud chcete vyloučit hodnoty těchto tajných kódů v konfiguraci aplikace, aktualizujte tajný klíč s vypršenou platností nebo zadejte konfiguraci pomocí vlastního zprostředkovatele konfigurace:

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

Předejte tuto vlastní:KeyVaultSecretManager AddAzureKeyVault

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

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

Zakázané tajné kódy nelze načíst ze služby Key Vault a nikdy se nezahrnou.

Odstraňování potíží

Pokud se aplikaci nepodaří načíst konfiguraci pomocí zprostředkovatele, zapíše se chybová zpráva do infrastruktury protokolování jádra ASP.NET. Následující podmínky zabrání načtení konfigurace:

Aplikace nebo certifikát nejsou správně nakonfigurované v ID Microsoft Entra.
Trezor ve službě Azure Key Vault neexistuje.
Aplikace nemá oprávnění pro přístup k trezoru.
Zásady přístupu nezahrnují Get a List oprávnění.
V trezoru jsou konfigurační data (pár name-value) nesprávně pojmenována, chybí nebo zakázána.
Aplikace má nesprávný název služby Key Vault (KeyVaultName), ID aplikace Microsoft Entra ID (AzureADApplicationId) nebo kryptografický otisk certifikátu Microsoft Entra ID (AzureADCertThumbprint) nebo ID adresáře Microsoft Entra ID (AzureADDirectoryId).
Při přidávání zásad přístupu ke službě Key Vault pro aplikaci se zásady vytvořily, ale v uživatelském rozhraní zásad přístupu nebylo vybráno tlačítko Uložit.

Další materiály

Řízení přístupu k citlivým konfiguračním datům
Při ukládání konfiguračních dat splňuje požadavek na ověření modulů hardwarového zabezpečení (HSM) pro FIPS 140-2 Level 2.

Balíčky

Přidejte odkazy na balíčky pro následující balíčky:

Ukázková aplikace

Ukázková aplikace se spouští v některém ze dvou režimů určených direktivou #define preprocesoru v horní části Program.cs:

Certificate: Ukazuje použití ID klienta služby Azure Key Vault a certifikátu X.509 pro přístup k tajným kódům uloženým ve službě Azure Key Vault. Tuto ukázku je možné spustit z libovolného umístění bez ohledu na to, jestli se nasadí do služby Aplikace Azure Service nebo z libovolného hostitele, který může obsluhovat aplikaci ASP.NET Core.
Managed: Ukazuje, jak používat spravované identity pro prostředky Azure. Spravovaná aplikace identity ověří ve službě Azure Key Vault pomocí spravovaných identit pro prostředky Azure bez přihlašovacích údajů uložených v kódu nebo konfiguraci aplikace. Při ověřování spravovaných identit se nevyžadují spravované identity pro ID aplikace prostředků Azure a heslo (tajný klíč klienta). Verze Managed ukázky se musí nasadit do Azure. Postupujte podle pokynů v části Použití spravovaných identit pro prostředky Azure.

Další informace o konfiguraci ukázkové aplikace pomocí direktiv preprocesoru (#define) najdete v tématu Přehled ASP.NET Core.

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Úložiště tajných kódů ve vývojovém prostředí

Správce tajných kódů vyžaduje <UserSecretsId> vlastnost v souboru projektu aplikace. Nastavte hodnotu vlastnosti ({GUID}) na libovolný jedinečný identifikátor GUID:

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

Tajné kódy se vytvářejí jako páry název-hodnota. Hierarchické hodnoty (oddíly konfigurace) používají : (dvojtečku) jako oddělovač v názvech konfiguračních klíčů ASP.NET Core.

Správce tajných kódů se používá z příkazového prostředí otevřeného v kořenovém adresáři obsahu projektu, kde {SECRET NAME} je název a {SECRET VALUE}hodnota:

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

Spuštěním následujících příkazů v příkazovém prostředí z kořenového adresáře obsahu projektu nastavte tajné kódy pro ukázkovou aplikaci:

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

Úložiště tajných kódů v produkčním prostředí se službou Azure Key Vault

Otevřete Azure Cloud Shell pomocí některé z následujících metod na webu Azure Portal:
- Zvolte Vyzkoušet v pravém horním rohu bloku kódu. V textovém poli použijte hledaný řetězec Azure CLI.
- V prohlížeči otevřete Cloud Shell pomocí tlačítka Spustit Cloud Shell .
- V nabídce v pravém horním rohu webu Azure Portal vyberte tlačítko Cloud Shell.
Další informace najdete v tématu Azure CLI a přehled služby Azure Cloud Shell.
Pokud ještě nejste ověřeni, přihlaste se pomocí az login příkazu.
Vytvořte skupinu prostředků pomocí následujícího příkazu, kde {RESOURCE GROUP NAME} je název nové skupiny prostředků a {LOCATION} oblast Azure:
```
az group create --name "{RESOURCE GROUP NAME}" --location {LOCATION}
```
Ve skupině prostředků vytvořte službu Key Vault pomocí následujícího příkazu, kde {KEY VAULT NAME} je název nového trezoru a {LOCATION} oblast Azure:
```
az keyvault create --name {KEY VAULT NAME} --resource-group "{RESOURCE GROUP NAME}" --location {LOCATION}
```
Vytvořte v trezoru tajné kódy jako páry název-hodnota.

Názvy tajných kódů služby Azure Key Vault jsou omezené na alfanumerické znaky a pomlčky. Hierarchické hodnoty (oddíly konfigurace) používají -- (dvě pomlčky) jako oddělovač, protože dvojtečky nejsou povolené v názvech tajných kódů služby Key Vault. Dvojtečky odděluje oddíl od podklíče v konfiguraci ASP.NET Core. Dvoumlčka se nahradí dvojtečkou, když se tajné kódy načtou do konfigurace aplikace.

Následující tajné kódy se používají s ukázkovou aplikací. Mezi hodnoty patří _prod přípona, která je odlišuje od _dev hodnot přípon načtených ve vývojovém prostředí z nástroje Secret Manager. Nahraďte {KEY VAULT NAME} názvem služby Key Vault, který jste vytvořili v předchozím 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"
```

Použití ID aplikace a certifikátu X.509 pro aplikace hostované mimo Azure

Poznámka:

Ukázková aplikace používá ID aplikace a certifikát X.509, pokud #define je direktiva preprocesoru v horní části Program.cs nastavena na Certificate.

Vytvořte archivní certifikát PKCS#12 (.pfx). Možnosti vytváření certifikátů zahrnují New-SelfSignedCertificate ve Windows a OpenSSL.
Nainstalujte certifikát do osobního úložiště certifikátů aktuálního uživatele. Označení klíče jako exportovatelného je volitelné. Poznamenejte si kryptografický otisk certifikátu, který se používá později v tomto procesu.
Exportujte certifikát PKCS#12 archivu (.pfx) jako certifikát s kódováním DER (.cer).
Zaregistrujte aplikaci pomocí Microsoft Entra ID (Registrace aplikací).
Nahrajte certifikát s kódováním DER (.cer) do MICROSOFT Entra ID:
1. Vyberte aplikaci v Microsoft Entra ID.
2. Přejděte na Certifikáty a tajné kódy.
3. Vyberte Nahrát certifikát a nahrajte certifikát, který obsahuje veřejný klíč. Certifikát .cer, .pem nebo .crt je přijatelný.
Do souboru aplikace appsettings.json uložte název služby Key Vault, ID aplikace a kryptografický otisk certifikátu.
Na webu Azure Portal přejděte ke službě Key Vault.
V části Azure Key Vault vyberte službu Key Vault, kterou jste vytvořili v úložišti tajných kódů v produkčním prostředí.
Vyberte Zásady přístupu.
Vyberte Přidat zásady přístupu.
Otevřete oprávnění tajného kódu a poskytněte aplikaci oprávnění Získat a vypsat .
Vyberte objekt zabezpečení a vyberte zaregistrovanou aplikaci podle názvu. Zvolte tlačítko Vybrat.
Vyberte OK.
Zvolte Uložit.
Nasaďte aplikaci.

Ukázková Certificate aplikace získá své konfigurační hodnoty se IConfigurationRoot stejným názvem jako název tajného kódu:

Ne hierarchické hodnoty: Hodnota pro SecretName je získána pomocí config["SecretName"].
Hierarchické hodnoty (oddíly): Použijte : (dvojtečka) notaci nebo metodu GetSection . K získání hodnoty konfigurace použijte některý z těchto přístupů:
- config["Section:SecretName"]
- config.GetSection("Section")["SecretName"]

Certifikát X.509 spravuje operační systém. Aplikace volá AddAzureKeyVault hodnoty zadané souborem appsettings.json :

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

Ukázkové hodnoty:

Název služby Key Vault: contosovault
ID aplikace: 00001111-aaaa-2222-bbbb-3333cccc4444
Kryptografický otisk certifikátu: fe14593dd66b2406c5269d742d04b6e1ab03adb1

appsettings.json:

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

Použití spravovaných identit pro prostředky Azure

Aplikace nasazená do Azure může využívat spravované identity pro prostředky Azure. Spravovaná identity umožňuje aplikaci ověřovat se službou Azure Key Vault pomocí ověřování Microsoft Entra ID bez přihlašovacích údajů (ID aplikace a hesla nebo tajného klíče klienta) uložených v aplikaci.

Ukázková aplikace používá spravované identity pro prostředky Azure, když #define je na začátku nastavené Manageddirektivy preprocesoru Program.cs .

Nasaďte ukázkovou aplikaci do služby Aplikace Azure Service.

Aplikace nasazená do služby Aplikace Azure Service se při vytvoření služby automaticky zaregistruje s ID Microsoft Entra. Získejte ID objektu z nasazení pro použití v následujícím příkazu. ID objektu se zobrazuje na webu Azure Portal na Identity panelu služby App Service.

Pomocí Azure CLI a ID objektu aplikace zadejte aplikaci a list get oprávnění pro přístup k trezoru:

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

Restartujte aplikaci pomocí Azure CLI, PowerShellu nebo webu Azure Portal.

Ukázková aplikace:

Vytvoří instanci objektu DefaultAzureCredential třídy. Přihlašovací údaje se pokusí získat přístupový token z prostředí pro prostředky Azure.
Vytvoří se DefaultAzureCredential nová SecretClient instance.
Instance SecretClient se používá s KeyVaultSecretManager instancí, která načte tajné hodnoty a nahrazuje dvojité pomlčky (--) dvojtečkami (:) v názvech klíčů.

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

Příklad hodnoty názvu služby Key Vault: contosovault

appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

Pokud se zobrazí Access denied chyba, ověřte, že je aplikace zaregistrovaná pomocí ID Microsoft Entra a že poskytuje přístup k trezoru. Potvrďte, že jste službu restartovali v Azure.

Možnosti konfigurace

AddAzureKeyVault může přijmout AzureKeyVaultConfigurationOptions objekt:

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

Objekt AzureKeyVaultConfigurationOptions obsahuje následující vlastnosti.

Vlastnost	Popis
Manager	KeyVaultSecretManager instance použitá k řízení načítání tajných kódů.
ReloadInterval	`TimeSpan` počkat mezi pokusy při dotazování trezoru na změny. Výchozí hodnota je `null` (konfigurace se znovu nenačte).

Použití předpony názvu klíče

Upozorňující

Nepoužívejte předpony u tajných kódů služby Key Vault k:

Tajné kódy pro více aplikací umístěte do stejného trezoru.
Umístěte tajné kódy prostředí (například vývoj a produkční tajné kódy) do stejného trezoru.

Různé aplikace a vývojová/produkční prostředí by měly používat samostatné trezory klíčů k izolaci aplikačních prostředí pro nejvyšší úroveň zabezpečení.

AddAzureKeyVault se volá s vlastní KeyVaultSecretManager implementací:

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

Implementace reaguje na předpony verzí tajných kódů za účelem načtení správného tajného kódu do konfigurace:

Load načte tajný kód, když jeho název začíná předponou. Jiné tajné kódy se nenačtou.
GetKey:
- Odebere předponu z názvu tajného kódu.
- Nahradí dvě pomlčky v libovolném názvu znakem KeyDelimiter, což je oddělovač použitý v konfiguraci (obvykle dvojtečka). Azure Key Vault neumožňuje dvojtečku v názvech tajných kódů.

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

Při implementaci tohoto přístupu:

Verze aplikace zadaná v souboru projektu aplikace. V následujícím příkladu je verze aplikace nastavená na 5.0.0.0:
```
<PropertyGroup>
  <Version>5.0.0.0</Version>
</PropertyGroup>
```

Ověřte, že <UserSecretsId> se vlastnost nachází v souboru projektu aplikace, kde {GUID} je identifikátor GUID zadaný uživatelem:

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

Pomocí Správce tajných kódů uložte následující tajné kódy místně:

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"

Tajné kódy se ukládají ve službě Azure Key Vault pomocí následujících příkazů Azure CLI:

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"

Při spuštění aplikace se načtou tajné kódy služby Key Vault. Tajný klíč 5000-AppSecret řetězce se shoduje s verzí aplikace zadanou v souboru projektu aplikace (5.0.0.0).
5000 Verze (s pomlčkou) je z názvu klíče odebrána. V celé aplikaci se při čtení konfigurace s klíčem načte hodnota tajného klíče AppSecret .
Pokud se v souboru 5.1.0.0 projektu změní verze aplikace a aplikace se spustí znovu, vrátí 5.1.0.0_secret_value_dev se vrácená hodnota tajného kódu ve vývojovém prostředí a 5.1.0.0_secret_value_prod v produkčním prostředí.

Poznámka:

Můžete také poskytnout vlastní SecretClient implementaci pro AddAzureKeyVault. Vlastní klient umožňuje sdílet jednu instanci klienta v rámci aplikace.

Vytvoření vazby pole ke třídě

Zprostředkovatel může číst konfigurační hodnoty do pole pro vazbu na pole POCO.

"Serilog": {
  "WriteTo": [
    {
      "Name": "AzureTableStorage",
      "Args": {
        "storageTableName": "logs",
        "connectionString": "DefaultEnd...ountKey=Eby8...GMGw=="
      }
    },
    {
      "Name": "AzureDocumentDB",
      "Args": {
        "endpointUrl": "https://contoso.documents.azure.com:443",
        "authorizationKey": "Eby8...GMGw=="
      }
    }
  ]
}

Konfigurace zobrazená v předchozím souboru JSON je uložená ve službě Azure Key Vault pomocí dvoumlčky (--) notace a číselných segmentů:

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

Opětovné načtení tajných kódů

Tajné kódy se ukládají do mezipaměti, dokud IConfigurationRoot.Reload se nevolají. Aplikace následně zakáže nebo aktualizuje tajné kódy v trezoru, dokud Reload se nespustí.

Configuration.Reload();

Zakázané a prošlé tajné kódy

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

Předejte tuto vlastní:KeyVaultSecretManager AddAzureKeyVault

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

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

Zakázané tajné kódy nelze načíst ze služby Key Vault a nikdy se nezahrnou.

Odstraňování potíží

Aplikace nebo certifikát nejsou správně nakonfigurované v ID Microsoft Entra.
Trezor ve službě Azure Key Vault neexistuje.
Aplikace nemá oprávnění pro přístup k trezoru.
Zásady přístupu nezahrnují Get a List oprávnění.
V trezoru jsou konfigurační data (pár name-value) nesprávně pojmenována, chybí nebo zakázána.
Aplikace má nesprávný název služby Key Vault (KeyVaultName), ID aplikace Microsoft Entra ID (AzureADApplicationId) nebo kryptografický otisk certifikátu Microsoft Entra ID (AzureADCertThumbprint) nebo ID adresáře Microsoft Entra ID (AzureADDirectoryId).
Při přidávání zásad přístupu ke službě Key Vault pro aplikaci se zásady vytvořily, ale v uživatelském rozhraní zásad přístupu nebylo vybráno tlačítko Uložit.

Sdílet prostřednictvím

Zprostředkovatel konfigurace služby Azure Key Vault v ASP.NET Core

Balíčky

Ukázková aplikace

Úložiště tajných kódů ve vývojovém prostředí

Úložiště tajných kódů v produkčním prostředí se službou Azure Key Vault

Použití ID aplikace a certifikátu X.509 pro aplikace hostované mimo Azure

Použití spravovaných identit pro prostředky Azure

Možnosti konfigurace

Použití předpony názvu klíče

Vytvoření vazby pole ke třídě

Opětovné načtení tajných kódů

Zakázané a prošlé tajné kódy

Odstraňování potíží

Další materiály

Balíčky

Ukázková aplikace

Úložiště tajných kódů ve vývojovém prostředí

Úložiště tajných kódů v produkčním prostředí se službou Azure Key Vault

Použití ID aplikace a certifikátu X.509 pro aplikace hostované mimo Azure

Použití spravovaných identit pro prostředky Azure

Možnosti konfigurace

Použití předpony názvu klíče

Vytvoření vazby pole ke třídě

Opětovné načtení tajných kódů

Zakázané a prošlé tajné kódy

Odstraňování potíží

Další materiály

Další materiály