.NET Aspire Azure Key Vault integration

  • Artículo

In this article, you learn how to use the .NET Aspire Azure Key Vault integration. The Aspire.Azure.Key.Vault integration library is used to register a SecretClient in the DI container for connecting to Azure Key Vault. It also enables corresponding health checks, logging and telemetry.

Get started

To get started with the .NET Aspire Azure Key Vault integration, install the 📦 Aspire.Azure.Security.KeyVault NuGet package in the client-consuming project, i.e., the project for the application that uses the Azure Key Vault client.

dotnet add package Aspire.Azure.Security.KeyVault

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Example usage

THe following sections describe various example usages.

Add secrets to configuration

In the Program.cs file of your client-consuming project, call the AddAzureKeyVaultSecrets extension to add the secrets in the Azure Key Vault to the application's Configuration. The method takes a connection name parameter.

builder.Configuration.AddAzureKeyVaultSecrets("secrets");

You can then retrieve a secret through normal IConfiguration APIs. For example, to retrieve a secret from a service:

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

Use SecretClient

Alternatively, you can use a SecretClient to retrieve the secrets on demand. In the Program.cs file of your client-consuming project, call the AddAzureKeyVaultClient extension to register a SecretClient for use via the dependency injection container.

builder.AddAzureKeyVaultClient("secrets");

You can then retrieve the SecretClient instance using dependency injection. For example, to retrieve the client from a service:

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

App host usage

To add Azure Key Vault hosting support to your IDistributedApplicationBuilder, install the 📦 Aspire.Hosting.Azure.KeyVault) NuGet package in the [app host](xref:dotnet/aspire/app-host NuGet package in the app host project.

dotnet add package Aspire.Hosting.Azure.KeyVault

In your app host project, register the Azure Key Vault integration and consume the service using the following methods:

var builder = DistributedApplication.CreateBuilder(args);

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

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

The preceding code conditionally adds the Azure Key Vault resource to the project based on the execution context. If the app host is executing in publish mode, the resource is added otherwise the connection string to an existing resource is added.

Configuration

The .NET Aspire Azure Key Vault integration provides multiple options to configure the SecretClient based on the requirements and conventions of your project.

Use configuration providers

The .NET Aspire Azure Key Vault integration supports Microsoft.Extensions.Configuration. It loads the AzureSecurityKeyVaultSettings from appsettings.json or other configuration files using Aspire:Azure:Security:KeyVault key.

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

If you have set up your configurations in the Aspire:Azure:Security:KeyVault section of your appsettings.json file you can just call the method AddAzureKeyVaultSecrets without passing any parameters.

Use inline delegates

You can also pass the Action<AzureSecurityKeyVaultSettings> delegate to set up some or all the options inline, for example to set the VaultUri:

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

Tip

The AddAzureKeyVaultSecrets API name has caused a bit of confusion. The method is used to configure the SecretClient and not to add secrets to the configuration.

You can also set up the SecretClientOptions using Action<IAzureClientBuilder<SecretClient, SecretClientOptions>> delegate, the second parameter of the AddAzureKeyVaultSecrets method. For example to set the KeyClientOptions.DisableChallengeResourceVerification ID to identify the client:

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

Configuration options

The following configurable options are exposed through the AzureSecurityKeyVaultSettings class:

Name Description
VaultUri A URI to the vault on which the client operates. Appears as "DNS Name" in the Azure portal.
Credential The credential used to authenticate to the Azure Key Vault.
DisableHealthChecks A boolean value that indicates whether the Key Vault health check is disabled or not.
DisableTracing A boolean value that indicates whether the OpenTelemetry tracing is disabled or not.

Health checks

By default, .NET Aspire integrations enable health checks for all services. For more information, see .NET Aspire integrations overview.

The .NET Aspire Azure Key Vault integration includes the following health checks:

  • Adds the AzureKeyVaultSecretsHealthCheck health check, which attempts to connect to and query the Key Vault
  • Integrates with the /health HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic

Observability and telemetry

.NET Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. For more information about integration observability and telemetry, see .NET Aspire integrations overview. Depending on the backing service, some integrations may only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the Configuration section.

Logging

The .NET Aspire Azure Key Vault integration uses the following log categories:

  • Azure.Core
  • Azure.Identity

Tracing

The .NET Aspire Azure Key Vault integration will emit the following tracing activities using OpenTelemetry:

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

Metrics

The .NET Aspire Azure Key Vault integration currently does not support metrics by default due to limitations with the Azure SDK.

See also