Sdílet prostřednictvím

integrace .NET AspireAzure Key Vault

  • Článek

zahrnuje: integraci hostování a Client integraci

Azure Key Vault je cloudová služba pro bezpečné ukládání tajných kódů a přístup k nim. Integrace .NET AspireAzure Key Vault umožňuje připojení k Azure Key Vault instancím z aplikací .NET.

Integrace hostování

Integrační hostování Azure Key Vault modeluje jako typ AzureKeyVaultResource prostředek služby Key Vault. Pokud chcete získat přístup k tomuto typu a rozhraním API pro jejich vyjádření v rámci vašeho projektu hostitele aplikace , nainstalujte balíček NuGet 📦Aspire.Hosting.Azure.KeyVault.

dotnet add package Aspire.Hosting.Azure.KeyVault

Další informace najdete v tématu dotnet add package nebo Správa závislostí balíčků v .NET aplikacích.

Přidej Azure Key Vault prostředek

V projektu hostitele aplikace zavolejte AddAzureKeyVault v instanci tvůrce a přidejte prostředek Azure Key Vault:

var builder = DistributedApplication.CreateBuilder(args);

var keyVault = builder.AddAzureKeyVault("key-vault");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(keyVault);

// After adding all resources, run the app...

Metoda WithReference nakonfiguruje připojení v ExampleProject s názvem "key-vault".

Důležité

Ve výchozím nastavení AddAzureKeyVault konfiguruje vestavěnou roli správce služby Key Vault .

Spropitné

Když voláte AddAzureKeyVault, implicitně volá AddAzureProvisioning, což přidává podporu pro generování Azure prostředků dynamicky během spouštění aplikace. Aplikace musí nakonfigurovat příslušné předplatné a umístění. Pro více informací si přečtěte Místní zřizování: Konfigurace.

Vygenerované přidělování Bicep

Pokud jste nováčkem v Bicep, jedná se o specifický jazyk pro danou oblast k definování Azure prostředků. S .NET.NET Aspire nemusíte psát Bicep ručně, protože provisionovací API generují Bicep za vás. Když publikujete aplikaci, vygenerovaný soubor Bicep je součástí výstupu společně se souborem manifestu. Když přidáte prostředek Azure Key Vault, vygeneruje se následující Bicep:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalType string

param principalId string

resource key_vault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: take('keyvault-${uniqueString(resourceGroup().id)}', 24)
  location: location
  properties: {
    tenantId: tenant().tenantId
    sku: {
      family: 'A'
      name: 'standard'
    }
    enableRbacAuthorization: true
  }
  tags: {
    'aspire-resource-name': 'key-vault'
  }
}

resource key_vault_KeyVaultAdministrator 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(key_vault.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '00482a5a-887f-4fb3-b363-3b7fe8e74483'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '00482a5a-887f-4fb3-b363-3b7fe8e74483')
    principalType: principalType
  }
  scope: key_vault
}

output vaultUri string = key_vault.properties.vaultUri

Předchozí modul Bicep je modul, který zřídí prostředek Azure Key Vault s následujícími výchozími hodnotami.

  • location: Umístění skupiny prostředků.
  • principalId: Hlavní ID uživatele nebo služby 'principálu'.
  • principalType: Hlavní typ uživatele nebo služby principál.
  • key_vault: Prostředek Azure Key Vault:
    • name: Jedinečný název pro Azure Key Vault.
    • properties: Vlastnosti Azure Key Vault:
      • tenantId: ID nájemníka Azure Key Vault.
      • sku: Skladová položka Azure Key Vault:
        • family: Rodina SKU.
        • name: Název skladové položky.
      • enableRbacAuthorization: Logická hodnota, která označuje, jestli má Azure Key Vault povolenou autorizaci řízení přístupu na základě role (RBAC).
    • tags: Značky Azure Key Vault.
  • key_vault_KeyVaultAdministrator: Přiřazení role správce Azure Key Vault:
    • name: Jedinečný název pro přiřazení role.
    • properties: Vlastnosti přiřazení role:
      • principalId: Hlavní ID uživatele nebo servisního objektu.
      • roleDefinitionId: ID definice role správce Azure Key Vault.
      • principalType: Hlavní typ uživatele nebo služebního objektu.
    • scope: Rozsah přiřazení role.
  • output: Identifikátor URI Azure Key Vault.

Vygenerovaný Bicep je výchozím bodem a můžete ho přizpůsobit tak, aby splňoval vaše konkrétní požadavky.

Přizpůsobení infrastruktury poskytování

Všechny resursy .NET AspireAzure jsou podtřídami typu AzureProvisioningResource. Tento typ umožňuje přizpůsobení vygenerovaného Bicep poskytnutím plynulého API pro konfiguraci prostředků Azure pomocí rozhraní ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Můžete například nakonfigurovat sku, RBAC, tagsatd. Následující příklad ukazuje, jak přizpůsobit zdroj Azure Key Vault:

builder.AddAzureKeyVault("key-vault")
    .ConfigureInfrastructure(infra =>
    {
        var keyVault = infra.GetProvisionableResources()
                            .OfType<KeyVaultService>()
                            .Single();

        keyVault.Properties.Sku = new()
        {
            Family = KeyVaultSkuFamily.A,
            Name = KeyVaultSkuName.Premium,
        };
        keyVault.Properties.EnableRbacAuthorization = true;
        keyVault.Tags.Add("ExampleKey", "Example value");
    });

Předchozí kód:

K dispozici je mnoho dalších možností konfigurace pro přizpůsobení prostředku služby Key Vault. Další informace najdete v tématu Azure.Provisioning.KeyVault a Azure. Přizpůsobení při zřizování.

Připojení k existující instanci Azure Key Vault

Možná máte existující instanci Azure Key Vault, ke které se chcete připojit. Místo vytváření nového prostředku Azure Key Vault můžete přidat připojovací řetězec do hostitelského prostředí aplikace. Pokud chcete přidat připojení k existujícímu prostředku Azure Key Vault, zavolejte metodu AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

var keyVault = builder.AddConnectionString("key-vault");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(keyVault);

// After adding all resources, run the app...

Poznámka:

Připojovací řetězce se používají k reprezentaci široké škály informací o připojení, včetně databázových připojení, zprostředkovatelů zpráv, identifikátorů URI koncových bodů a dalších služeb. V .NET.NET Aspire terminologii se výraz "připojovací řetězec" používá k reprezentaci jakéhokoli druhu informací o připojení.

Připojovací řetězec se konfiguruje v konfiguraci hostitele aplikace, obvykle v části Tajné kódy uživatelův části ConnectionStrings. Hostitel aplikace injektuje tento připojovací řetězec jako proměnnou prostředí například do všech závislých prostředků:

{
  "ConnectionStrings": {
    "key-vault": "https://{account_name}.vault.azure.net/"
  }
}

Závislý prostředek může přistupovat k vloženému připojovacímu řetězci voláním metody GetConnectionString a předáním názvu připojení jako parametru, v tomto případě "key-vault". API rozhraní GetConnectionString je zkratka pro IConfiguration.GetSection("ConnectionStrings")[name].

Client integrace

Chcete-li začít s integrací klienta .NET AspireAzure Key Vault, nainstalujte balíček NuGet 📦Aspire.Azure.Security.KeyVault do projektu, který klienta aktivně spotřebovává, což je projekt aplikace používající klienta Azure Key Vault.

dotnet add package Aspire.Azure.Security.KeyVault

Integrace klienta poskytuje dva způsoby přístupu k tajným kódům z Azure Key Vault:

  • Přidejte tajné kódy do konfigurace aplikace pomocí IConfiguration nebo vzoru IOptions<T>.
  • K načtení tajných kódů na vyžádání použijte SecretClient.

Přidání tajných kódů do konfigurace

V souboru Program.cs ve vašem projektu, který využívá klienta, zavolejte metodu rozšíření AddAzureKeyVaultSecrets na IConfiguration a přidejte tajemství jako součást konfigurace vaší aplikace. Metoda přebírá parametr názvu připojení.

builder.Configuration.AddAzureKeyVaultSecrets(connectionName: "key-vault");

Poznámka:

Název rozhraní API AddAzureKeyVaultSecrets způsobil trochu nejasnosti. Metoda se používá ke konfiguraci SecretClient na základě daného názvu připojení a se nepoužívá k přidání tajných kódů do konfigurace.

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku Azure Key Vault do hostitelského projektu aplikace. Další informace naleznete v části Přidání Azure Key Vault prostředků.

Poté můžete načíst hodnotu konfigurace založenou na tajných klíčích prostřednictvím běžných rozhraní API IConfiguration nebo dokonce pomocí připojení k typově silným třídám se vzorem možností . Pokud chcete načíst tajemství z ukázkové třídy služby zaregistrované v kontejneru injektáže závislostí, zvažte následující fragmenty kódu.

Načtení instance IConfiguration

public class ExampleService(IConfiguration configuration)
{
    // Use configuration...
    private string _secretValue = configuration["SecretKey"];
}

Předchozí příklad předpokládá, že jste také zaregistrovali instanci IConfiguration pro injektáž závislostí. Další informace naleznete v tématu Injektáž závislostí v .NET.

Načtení instance IOptions<T>

public class ExampleService(IOptions<SecretOptions> options)
{
    // Use options...
    private string _secretValue = options.Value.SecretKey;
}

Předchozí příklad předpokládá, že jste nakonfigurovali třídu SecretOptions pro použití se vzorem možností. Další informace naleznete v části Možnosti vzoru v .NET.

Další parametry rozhraní API AddAzureKeyVaultSecrets jsou volitelně k dispozici pro následující scénáře:

  • Action<AzureSecurityKeyVaultSettings>? configureSettings: Chcete-li nastavit některé nebo všechny možnosti přímo v textu.
  • Action<SecretClientOptions>? configureClientOptions: Nastavit SecretClientOptions inline.
  • AzureKeyVaultConfigurationOptions? options: Nakonfigurovat AzureKeyVaultConfigurationOptions vloženě.

Přidejte tajného klienta Azure

Případně můžete použít SecretClient přímo k načtení tajných kódů na vyžádání. To vyžaduje trochu jiné rozhraní API pro registraci.

V souboru Program.cs projektu, který využívá klienta, zavolejte rozšíření AddAzureKeyVaultClient instance IHostApplicationBuilder a zaregistrujte SecretClient pro použití prostřednictvím kontejneru injektáže závislostí.

builder.AddAzureKeyVaultClient(connectionName: "key-vault");

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku Azure Key Vault do hostitelského projektu aplikace. Další informace naleznete v části Přidání Azure Key Vault prostředků.

Po přidání SecretClient do tvůrce můžete získat instanci SecretClient pomocí injektáže závislostí. Pokud například chcete získat klienta z příkladové služby, definujte ho jako parametr konstruktoru a ujistěte se, že je třída ExampleService zaregistrovaná v kontejneru injektáži závislostí.

public class ExampleService(SecretClient client)
{
    // Use client...
}

Další informace o injektáži závislostí najdete v tématu .NET injektáž závislostí.

Přidejte klienta Azure Key Vault s klíčem

Mohou nastat situace, kdy chcete zaregistrovat více instancí SecretClient s různými názvy připojení. Pokud chcete zaregistrovat klíčované klienty Azure Key Vault, zavolejte metodu AddKeyedAzureKeyVaultClient:

builder.AddKeyedAzureKeyVaultClient(name: "feature-toggles");
builder.AddKeyedAzureKeyVaultClient(name: "admin-portal");

Potom můžete získat instance SecretClient pomocí dependency injection. Například pro získání klienta z ukázkové služby:

public class ExampleService(
    [FromKeyedServices("feature-toggles")] SecretClient featureTogglesClient,
    [FromKeyedServices("admin-portal")] SecretClient adminPortalClient)
{
    // Use clients...
}

Další informace o klíčových službách najdete v tématu .NET injektáž závislostí: klíčové služby.

Konfigurace

Integrace .NET AspireAzure Key Vault poskytuje několik možností konfigurace SecretClient na základě požadavků a konvencí projektu.

Použití zprostředkovatelů konfigurace

Integrace .NET AspireAzure Key Vault podporuje Microsoft.Extensions.Configuration. Načte AzureSecurityKeyVaultSettings z appsettings.json nebo jiných konfiguračních souborů pomocí klíče Aspire:Azure:Security:KeyVault.

{
  "Aspire": {
    "Azure": {
      "Security": {
        "KeyVault": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

Kompletní schéma integrace klienta Azure Key VaultJSON naleznete viz Aspire.Azure. Security.KeyVault/ConfigurationSchema.json.

Pokud jste nastavili konfigurace v části Aspire:Azure:Security:KeyVault souboru appsettings.json, stačí zavolat metodu AddAzureKeyVaultSecrets bez předání parametrů.

Použití vložených delegátů

Můžete také předat delegáta Action<AzureSecurityKeyVaultSettings> k nastavení některých nebo všech možností in-line, například pro nastavení AzureSecurityKeyVaultSettings.VaultUri:

builder.AddAzureKeyVaultSecrets(
    connectionName: "key-vault",
    configureSettings: settings => settings.VaultUri = new Uri("KEY_VAULT_URI"));

Můžete také nastavit SecretClientOptions pomocí Action<SecretClientOptions> delegáta, což je volitelný parametr metody AddAzureKeyVaultSecrets. Pokud chcete například nastavit ID KeyClientOptions.DisableChallengeResourceVerification pro identifikaci klienta:

builder.AddAzureKeyVaultSecrets(
    connectionName: "key-vault",
    configureClientOptions: options => options.DisableChallengeResourceVerification = true))

Možnosti konfigurace

Prostřednictvím třídy AzureSecurityKeyVaultSettings jsou zpřístupněny následující konfigurovatelné možnosti:

Jméno Popis
AzureSecurityKeyVaultSettings.Credential Přihlašovací údaje použité pro autentizaci k Azure Key Vault.
AzureSecurityKeyVaultSettings.DisableHealthChecks Logická hodnota označující, jestli je kontrola stavu služby Key Vault zakázaná nebo ne.
AzureSecurityKeyVaultSettings.DisableTracing Logická hodnota označující, jestli je trasování OpenTelemetry zakázané nebo ne.
AzureSecurityKeyVaultSettings.VaultUri Identifikátor URI trezoru, na kterém klient pracuje. Na portálu Azure se zobrazí jako název DNS.

Client testy stavu integrace

Ve výchozím nastavení mají .NET.NET Aspireklientské integracekontroly stavu povoleny pro všechny služby. Podobně mnoho hosting integrací také umožňuje koncové body kontroly stavu. Další informace najdete tady:

Integrace .NET AspireAzure Key Vault zahrnuje následující kontroly stavu:

  • Přidá kontrolu stavu AzureKeyVaultSecretsHealthCheck, která se pokusí připojit ke službě Key Vault a dotazovat se na ni.
  • Integruje se s koncovým bodem HTTP /health, který určuje, že všechny registrované zdravotní kontroly musí být úspěšné, aby byla aplikace považována za připravenou pro přijímání provozu.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace protokolování, trasování a metrik, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET AspireAzure Key Vault používá následující kategorie protokolů:

  • Azure.Core
  • Azure.Identity

Trasování

Integrace .NET AspireAzure Key Vault bude pomocí OpenTelemetryemitovat následující aktivity trasování:

  • Azure.Security.KeyVault.Secrets.SecretClient

Metriky

Integrace .NET AspireAzure Key Vault v současné době nepodporuje metriky ve výchozím nastavení z důvodu omezení sady Azure SDK.

Viz také