Edit

.NET Aspire Azure Key Vault component

  • Article

In this article, you learn how to use the .NET Aspire Azure Key Vault component. The Aspire.Azure.Key.Vault component 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 component, install the Aspire.Azure.Security.KeyVault NuGet package.

dotnet add package Aspire.Azure.Security.KeyVault --prerelease

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

Example usage

In the Program.cs file of your component-consuming project, call the AddAzureKeyVaultSecrets extension to register a SecretClient for use via the dependency injection container.

builder.AddAzureKeyVaultSecrets("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.

dotnet add package Aspire.Hosting.Azure.KeyVault --prerelease

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

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

// Service consumption
builder.AddProject<Projects.ExampleProject>()
       .WithReference(secrets)

Configuration

The .NET Aspire Azure Key Vault component 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 component 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",
          "HealthChecks": true,
          "Tracing": false,
          "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 Namespace:

builder.AddAzureKeyVaultSecrets(
    "secrets",
    static settings => settings.ServiceUri = new Uri("YOUR_SERVICEURI"));

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))

Named instances

If you want to add more than one SecretClient you can use named instances. Load the named configuration section from the json config by calling the AddAzureKeyVaultSecrets method and passing in the INSTANCE_NAME.

builder.AddAzureKeyVaultSecrets("INSTANCE_NAME");

The corresponding configuration JSON is defined as follows:

{
  "Aspire": {
    "Azure": {
      "Security": {
        "KeyVault": {
          "INSTANCE_NAME": {
            "VaultUri": "YOUR_VAULT_URI",
            "HealthChecks": true,
            "Tracing": false,
            "ClientOptions": {
              "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.
HealthChecks A boolean value that indicates whether the Key Vault health check is enabled or not.
Tracing A boolean value that indicates whether the OpenTelemetry tracing is enabled or not.

Health checks

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

The .NET Aspire Azure Key Vault component 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 components automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. For more information about component observability and telemetry, see .NET Aspire components overview. Depending on the backing service, some components may only support some of these features. For example, some components 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 component uses the following log categories:

  • Azure.Core
  • Azure.Identity

Tracing

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

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

Metrics

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

See also