Freigeben über

.NET Aspire Azure Key Vault-Integration

  • Artikel

In diesem Artikel erfahren Sie, wie Sie die .NET AspireAzure Key Vault Integration verwenden. Die Integrationsbibliothek Aspire.Azure.Key.Vault wird verwendet, um ein SecretClient im DI-Container zu registrieren und eine Verbindung mit Azure Key Vaultherzustellen. Außerdem ermöglicht es entsprechende Gesundheitsprüfungen, Protokollierung und Telemetrie.

Loslegen

Um mit der .NET AspireAzure Key Vault-Integration zu beginnen, installieren Sie das 📦Aspire.Azure. Security.KeyVault NuGet-Paket im Projekt, das clientnutzt, d. h. das Projekt, das die Anwendung enthält, die die Azure Key Vaultclientverwendet.

dotnet add package Aspire.Azure.Security.KeyVault

Weitere Informationen finden Sie unter dotnet add package oder Verwalten von Paketabhängigkeiten in .NET-Anwendungen.

Beispielverwendung

In den folgenden Abschnitten werden verschiedene Beispielverwendungen beschrieben.

Hinzufügen von Geheimnissen zur Konfiguration

Rufen Sie in der Datei Program.cs Ihres client-verbrauchenden Projekts die AddAzureKeyVaultSecrets-Erweiterung auf, um die Geheimnisse im Azure Key Vault zur Konfiguration der Anwendung zu ergänzen. Die Methode verwendet einen Verbindungsnamenparameter.

builder.Configuration.AddAzureKeyVaultSecrets("secrets");

Anschließend können Sie einen geheimen Schlüssel über normale IConfiguration-APIs abrufen. Um z. B. ein Geheimnis aus einem Dienst abzurufen:

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

Verwenden Sie SecretClient

Alternativ können Sie eine SecretClient verwenden, um die geheimen Schlüssel bei Bedarf abzurufen. Rufen Sie in der Datei Program.cs Ihres client-nutzenden Projekts die AddAzureKeyVaultClient-Erweiterung auf, um ein SecretClient für die Verwendung über den Dependency Injection Container zu registrieren.

builder.AddAzureKeyVaultClient("secrets");

Anschließend können Sie die SecretClient-Instanz mithilfe der Dependency Injection abrufen. So rufen Sie beispielsweise die client von einem Dienst ab:

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

Nutzung des App-Hosts

Um die Azure Key Vault Hosting-Unterstützung zu Ihrem IDistributedApplicationBuilderhinzuzufügen, installieren Sie das 📦Aspire.Hosting.Azure.KeyVault. NuGet-Paket im App-Host--Projekt.

dotnet add package Aspire.Hosting.Azure.KeyVault

Registrieren Sie in Ihrem App-Hostprojekt die Azure Key Vault Integration, und nutzen Sie den Dienst mithilfe der folgenden Methoden:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Der vorstehende Code fügt bedingt die Ressource Azure Key Vault dem Projekt hinzu, basierend auf dem Ausführungskontext. Wenn der App-Host im Veröffentlichungsmodus ausgeführt wird, wird die Ressource hinzugefügt, ansonsten die Verbindungszeichenfolge zu einer vorhandenen Ressource.

Konfiguration

Die .NET AspireAzure Key Vault-Integration bietet mehrere Optionen zum Konfigurieren der SecretClient basierend auf den Anforderungen und Konventionen Ihres Projekts.

Konfigurationsanbieter verwenden

Die .NET AspireAzure Key Vault-Integration unterstützt Microsoft.Extensions.Configuration. Sie lädt die AzureSecurityKeyVaultSettings aus appsettings.json oder anderen Konfigurationsdateien mithilfe des Aspire:Azure:Security:KeyVault Schlüssels.

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

Wenn Sie Ihre Konfigurationen im Abschnitt Aspire:Azure:Security:KeyVault Ihrer appsettings.json Datei eingerichtet haben, können Sie die Methode einfach AddAzureKeyVaultSecrets aufrufen, ohne Parameter zu übergeben.

Verwenden von Inlinedelegaten

Sie können auch den Action<AzureSecurityKeyVaultSettings> Delegat übergeben, um einige oder alle Optionen inline einzurichten, z. B. um die VaultUrifestzulegen:

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

Tipp

Der AddAzureKeyVaultSecrets API-Name hat ein wenig Verwirrung verursacht. Die Methode wird verwendet, um SecretClient zu konfigurieren und keine Geheimnisse zur Konfiguration hinzuzufügen.

Sie können die SecretClientOptions auch mithilfe des Action<IAzureClientBuilder<SecretClient, SecretClientOptions>>-Delegaten, dem zweiten Parameter der AddAzureKeyVaultSecrets-Methode, einrichten. Um beispielsweise die KeyClientOptions.DisableChallengeResourceVerification-ID festzulegen, um die clientzu identifizieren:

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

Konfigurationsoptionen

Die folgenden konfigurierbaren Optionen werden über die AzureSecurityKeyVaultSettings Klasse verfügbar gemacht:

Name Beschreibung
VaultUri Ein URI zum Tresor, auf dem die client ausgeführt wird. Wird im Azure Portal als „DNS-Name“ angezeigt.
Credential Die Anmeldeinformationen, die für die Authentifizierung bei der Azure Key Vaultverwendet werden.
DisableHealthChecks Ein boolescher Wert, der angibt, ob die Key Vault-Integritätsprüfung deaktiviert ist oder nicht.
DisableTracing Ein boolescher Wert, der angibt, ob die OpenTelemetry Ablaufverfolgung deaktiviert ist oder nicht.

Gesundheitschecks

Standardmäßig aktivieren Integrationen .NET.NET Aspire Integritätsprüfungen für alle Dienste. Weitere Informationen finden Sie unter .NET.NET Aspire Integrationsübersicht.

Die .NET AspireAzure Key Vault Integration umfasst die folgenden Integritätsprüfungen:

  • Fügt den AzureKeyVaultSecretsHealthCheck-Gesundheits-Check hinzu, der versucht, eine Verbindung zum und eine Abfrage des Key Vault herzustellen.
  • Integriert sich in den /health HTTP-Endpunkt, der angibt, dass alle registrierten Integritätsprüfungen bestehen müssen, damit die App als bereit angesehen wird, um Datenverkehr anzunehmen.

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als den Säulen der Observabilitybezeichnet werden. Weitere Informationen zur Integrationsobservierbarkeit und Telemetrie finden Sie unter der Übersicht zu .NET.NET Aspire Integrationen. Abhängig vom Sicherungsdienst unterstützen einige Integrationen möglicherweise nur einige dieser Features. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetrie-Features können auch mithilfe der Techniken deaktiviert werden, die im Abschnitt Configuration dargestellt werden.

Protokollierung

Die .NET AspireAzure Key Vault-Integration verwendet die folgenden Protokollkategorien:

  • Azure.Core
  • Azure.Identity

Nachverfolgung

Die Integration von .NET AspireAzure Key Vault gibt die folgenden Tracing-Aktivitäten mithilfe von OpenTelemetryaus:

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

Metriken

Die .NET AspireAzure Key Vault-Integration unterstützt aufgrund von Einschränkungen mit dem Azure SDK derzeit Metriken nicht standardmäßig.

Siehe auch