Udostępnij za pośrednictwem

integracja .NET AspireAzure Key Vault

  • Artykuł

Z tego artykułu dowiesz się, jak korzystać z integracji .NET AspireAzure Key Vault. Biblioteka integracji Aspire.Azure.Key.Vault służy do rejestrowania SecretClient w kontenerze DI na potrzeby nawiązywania połączenia z Azure Key Vault. Umożliwia również odpowiednie kontrole kondycji, rejestrowanie i dane telemetryczne.

Zacznij

Aby rozpocząć pracę z integracją .NET AspireAzure Key Vault, zainstaluj pakiet NuGet 📦Aspire.Azure.Security.KeyVault w projekcie korzystającym z client, tj. w projekcie aplikacji, która korzysta z Azure Key Vaultclient.

dotnet add package Aspire.Azure.Security.KeyVault

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzaj zależnościami pakietów w aplikacjach .NET.

Przykładowe użycie

W poniższych sekcjach opisano różne przykładowe użycie.

Dodawanie sekretów do konfiguracji

W pliku Program.cs projektu clientkorzystającego z wywołaj rozszerzenie AddAzureKeyVaultSecrets, aby dodać tajne dane w Azure Key Vault do konfiguracji aplikacji. Metoda przyjmuje parametr nazwy połączenia.

builder.Configuration.AddAzureKeyVaultSecrets("secrets");

Następnie możesz pobrać tajną wiadomość za pomocą standardowych API IConfiguration. Aby na przykład pobrać sekret z usługi:

public class ExampleService(IConfiguration configuration)
{
    string secretValue = configuration["secretKey"];
    // Use secretValue ...
}

Użyj SecretClient

Alternatywnie, możesz użyć SecretClient, aby pobrać tajemnice na żądanie. W pliku Program.cs dla projektu korzystającego z client, wywołaj rozszerzenie AddAzureKeyVaultClient, aby zarejestrować SecretClient do użycia za pośrednictwem kontenera wstrzykiwania zależności.

builder.AddAzureKeyVaultClient("secrets");

Następnie można uzyskać dostęp do wystąpienia SecretClient za pomocą wstrzykiwania zależności. Aby na przykład pobrać client z usługi:

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

Użycie hosta aplikacji

Aby dodać obsługę hostingu do , zainstaluj . Gościnność.. KeyVault pakiet NuGet w projekcie hosta aplikacji .

dotnet add package Aspire.Hosting.Azure.KeyVault

W projekcie hosta aplikacji zarejestruj integrację Azure Key Vault i użyj usługi przy użyciu następujących metod:

var builder = DistributedApplication.CreateBuilder(args);

var secrets = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureKeyVault("secrets")
    : builder.AddConnectionString("secrets");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(secrets)

Powyższy kod warunkowo dodaje zasób Azure Key Vault do projektu na podstawie kontekstu wykonywania. Jeśli host aplikacji jest wykonywany w trybie publikowania, zasób zostanie dodany, w przeciwnym razie parametry połączenia do istniejącego zasobu zostaną dodane.

Konfiguracja

Integracja .NET AspireAzure Key Vault oferuje wiele opcji konfigurowania SecretClient na podstawie wymagań i konwencji projektu.

Korzystanie z dostawców konfiguracji

Integracja .NET AspireAzure Key Vault obsługuje Microsoft.Extensions.Configuration. Ładuje AzureSecurityKeyVaultSettings z appsettings.json lub z innych plików konfiguracyjnych przy użyciu klucza Aspire:Azure:Security:KeyVault.

{
  "Aspire": {
    "Azure": {
      "Security": {
        "KeyVault": {
          "VaultUri": "YOUR_VAULT_URI",
          "DisableHealthChecks": false,
          "DisableTracing": true,
          "ClientOptions": {
            "DisableChallengeResourceVerification": true
          }
        }
      }
    }
  }
}

Jeśli konfiguracje zostały skonfigurowane w sekcji Aspire:Azure:Security:KeyVault pliku appsettings.json, możesz po prostu wywołać metodę AddAzureKeyVaultSecrets bez przekazywania żadnych parametrów.

Używanie delegatów wbudowanych

Możesz również przekazać delegata Action<AzureSecurityKeyVaultSettings>, aby skonfigurować niektóre lub wszystkie opcje w linii, na przykład w celu ustawienia VaultUri:

builder.AddAzureKeyVaultSecrets(
    "secrets",
    static settings => settings.VaultUri = new Uri("YOUR_VAULTURI"));

Napiwek

Nazwa interfejsu API AddAzureKeyVaultSecrets spowodowała nieco zamieszanie. Metoda służy do konfigurowania SecretClient, a nie do dodawania tajnych danych do konfiguracji.

Można również skonfigurować SecretClientOptions przy użyciu delegata Action<IAzureClientBuilder<SecretClient, SecretClientOptions>>, drugiego parametru metody AddAzureKeyVaultSecrets. Aby na przykład ustawić identyfikator KeyClientOptions.DisableChallengeResourceVerification w celu zidentyfikowania client:

builder.AddAzureKeyVaultSecrets(
    "secrets",
    static clientBuilder =>
        clientBuilder.ConfigureOptions(
            static options => options.DisableChallengeResourceVerification = true))

Opcje konfiguracji

Następujące konfigurowalne opcje są udostępniane za pośrednictwem klasy AzureSecurityKeyVaultSettings:

Nazwa Opis
VaultUri Identyfikator URI do magazynu, na którym działa client. Jest wyświetlana jako "Nazwa DNS" w portalu Azure.
Credential Poświadczenie używane do uwierzytelniania w Azure Key Vault.
DisableHealthChecks Wartość logiczna wskazująca, czy sprawdzanie kondycji usługi Key Vault jest wyłączone, czy nie.
DisableTracing Wartość logiczna wskazująca, czy śledzenie OpenTelemetry jest wyłączone, czy nie.

Kontrole kondycji

Domyślnie .NET.NET Aspire integracje umożliwiają sprawdzanie kondycji dla wszystkich usług. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

Integracja .NET AspireAzure Key Vault obejmuje następujące kontrole kondycji:

  • Dodaje kontrolę kondycji AzureKeyVaultSecretsHealthCheck, która próbuje nawiązać połączenie z usługą Key Vault i wykonywać zapytania dotyczące tej usługi.
  • Integruje się z punktem końcowym HTTP /health, który określa, że wszystkie zarejestrowane kontrole kondycji muszą zostać pomyślnie zaliczone, aby aplikacja była uznana za gotową do przyjmowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie konfigurują rejestrowanie, śledzenie i metryki, które są czasami nazywane filarami obserwowalności. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji .

Rejestrowanie

Integracja .NET AspireAzure Key Vault używa następujących kategorii dzienników:

  • Azure.Core
  • Azure.Identity

Śledzenie

Integracja .NET AspireAzure Key Vault spowoduje emitowanie następujących działań śledzenia przy użyciu OpenTelemetry:

  • "Azure.Security.KeyVault.Secrets.SecretClient"

Metryki

Integracja .NET AspireAzure Key Vault obecnie nie obsługuje metryk domyślnie z powodu ograniczeń SDK Azure.

Zobacz też