Condividi tramite

integrazione di .NET AspireAzure Key Vault

  • Articolo

Questo articolo illustra come usare l'integrazione .NET AspireAzure Key Vault. La libreria di integrazione Aspire.Azure.Key.Vault viene utilizzata per registrare un SecretClient nel contenitore DI per la connessione a Azure Key Vault. Abilita anche i controlli sanitari, la registrazione dei log e i dati di telemetria corrispondenti.

Inizia

Per iniziare a utilizzare l'integrazione di .NET AspireAzure Key Vault, installare il pacchetto NuGet 📦Aspire.Azure.Security.KeyVault nel progetto di consumo client, ovvero il progetto per l'applicazione che utilizza il Azure Key Vaultclient.

dotnet add package Aspire.Azure.Security.KeyVault

Per ulteriori informazioni, vedere dotnet add package oppure Gestisci le dipendenze dei pacchetti nelle applicazioni .NET.

Esempio di utilizzo

Le sezioni seguenti descrivono vari utilizzi di esempio.

Aggiungere segreti alla configurazione

Nel file Program.cs del tuo progetto che consuma client, chiamare l'estensione AddAzureKeyVaultSecrets per aggiungere i segreti nel Azure Key Vault alla configurazione dell'applicazione. Il metodo accetta un parametro del nome di connessione.

builder.Configuration.AddAzureKeyVaultSecrets("secrets");

È quindi possibile recuperare un segreto tramite le NORMALI API di IConfiguration. Ad esempio, per recuperare un segreto da un servizio:

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

Usare SecretClient

In alternativa, è possibile usare un SecretClient per recuperare i segreti su richiesta. Nel file Program.cs del progetto che consuma client, chiamare l'estensione AddAzureKeyVaultClient per registrare un SecretClient da usare tramite il contenitore di iniezione delle dipendenze.

builder.AddAzureKeyVaultClient("secrets");

È quindi possibile recuperare l'istanza di SecretClient usando l'inserimento delle dipendenze. Ad esempio, per recuperare il client da un servizio:

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

Utilizzo dell'host dell'app

Per aggiungere supporto per l'hosting al , installare il . Ospitare.. KeyVault pacchetto NuGet nel progetto host dell'app .

dotnet add package Aspire.Hosting.Azure.KeyVault

Nel progetto host dell'app, registra l'integrazione Azure Key Vault e utilizza il servizio con i metodi seguenti:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Il codice precedente aggiunge in modo condizionale la risorsa Azure Key Vault al progetto in base al contesto di esecuzione. Se l'host dell'app è in esecuzione in modalità di pubblicazione, la risorsa viene aggiunta; altrimenti viene aggiunta la stringa di connessione a una risorsa esistente.

Configurazione

L'integrazione .NET AspireAzure Key Vault offre più opzioni per configurare l'SecretClient in base ai requisiti e alle convenzioni del progetto.

Usare i Provider di Configurazione

L'integrazione .NET AspireAzure Key Vault supporta Microsoft.Extensions.Configuration. Carica il AzureSecurityKeyVaultSettings da appsettings.json o da altri file di configurazione usando la chiave Aspire:Azure:Security:KeyVault.

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

Se sono state configurate le configurazioni nella sezione Aspire:Azure:Security:KeyVault del file di appsettings.json, è sufficiente chiamare il metodo AddAzureKeyVaultSecrets senza passare alcun parametro.

Usare delegati inline

È anche possibile passare il delegato Action<AzureSecurityKeyVaultSettings> per configurare alcune o tutte le opzioni direttamente, ad esempio per definire il VaultUri:

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

Consiglio

Il nome dell'API AddAzureKeyVaultSecrets ha causato un po' di confusione. Il metodo viene usato per configurare il SecretClient e non per aggiungere segreti alla configurazione.

È anche possibile configurare il SecretClientOptions usando il delegato Action<IAzureClientBuilder<SecretClient, SecretClientOptions>>, il secondo parametro del metodo AddAzureKeyVaultSecrets. Ad esempio, per impostare l'ID KeyClientOptions.DisableChallengeResourceVerification per identificare il client:

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

Opzioni di configurazione

Le opzioni configurabili seguenti vengono esposte tramite la classe AzureSecurityKeyVaultSettings:

Nome Descrizione
VaultUri Un URI per il vault su cui opera il client. Viene visualizzato come "Nome DNS" nel portale di Azure.
Credential La credenziale usata per eseguire l'autenticazione al Azure Key Vault.
DisableHealthChecks Valore booleano che indica se la verifica dello stato del Key Vault è disabilitata o meno.
DisableTracing Valore booleano che indica se la traccia OpenTelemetry è disabilitata o meno.

Controlli di salute

Per impostazione predefinita, le integrazioni di .NET.NET Aspire abilitano controlli dello stato di salute per tutti i servizi. Per altre informazioni, vedere panoramica delle integrazioni .NET.NET Aspire.

L'integrazione .NET AspireAzure Key Vault include le verifiche dello stato di salute seguenti:

  • Aggiunge il controllo di integrità AzureKeyVaultSecretsHealthCheck, che prova a connettersi ed eseguire query sul Key Vault
  • Si integra con l'endpoint HTTP /health, che specifica che tutti i controlli di integrità registrati devono essere passati affinché l'app sia considerata pronta ad accettare il traffico

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente i log, il tracciamento e le metriche, talvolta noti come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione .NET AspireAzure Key Vault usa le categorie di log seguenti:

  • Azure.Core
  • Azure.Identity

Tracciamento

L'integrazione .NET AspireAzure Key Vault genererà le attività di traccia seguenti usando OpenTelemetry:

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

Metriche

L'integrazione .NET AspireAzure Key Vault attualmente non supporta le metriche per impostazione predefinita a causa di limitazioni con Azure SDK.

Vedere anche