Get started with the Azure Key Vault integration

Azure Key Vault helps safeguard cryptographic keys and secrets used by cloud applications and services. The Aspire Azure Key Vault integration enables you to connect to existing Azure Key Vault instances.

In this introduction, you'll see how to install and use the Aspire Azure Key Vault integrations in a simple configuration. If you already have this knowledge, see Azure Key Vault Hosting integration for full reference details.

Note

To follow this guide, you must have created an Aspire solution to work with. To learn how to do that, see Build your first Aspire app.

Set up hosting integration

To begin, install the Aspire Azure Key Vault Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure Key Vault resources from your Aspire hosting projects:

Install the NuGet package

dotnet add package Aspire.Hosting.Azure.KeyVault

Next, in the AppHost project, create an Azure Key Vault resource and pass it to the consuming client projects:

var builder = DistributedApplication.CreateBuilder(args);
  
var keyVault = builder.AddAzureKeyVault("key-vault");
  
builder.AddProject<Projects.ExampleProject>()
    .WithReference(keyVault);
  
// After adding all resources, run the app...
  
builder.Build().Run();

The preceding code adds an Azure Key Vault resource named key-vault to the AppHost project. The WithReference method passes the connection information to the ExampleProject project.

Caution

When you call AddAzureKeyVault, it implicitly calls AddAzureProvisioning—which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see Local provisioning: Configuration.

Tip

This is the simplest implementation of Azure Key Vault resources in the AppHost. There are many more options you can choose from to address your requirements. For full details, see Azure Key Vault Hosting integration.

Set up client integration

To use Azure Key Vault from your client applications, install the Aspire Azure Key Vault client integration in your client project:

Install the NuGet package

dotnet add package Aspire.Azure.Security.KeyVault

The client integration provides two ways to access secrets from Azure Key Vault:

Add secrets to app configuration, using either the IConfiguration or the IOptions<T> pattern.
Use a SecretClient to retrieve secrets on demand.

Add secrets to configuration

In the Program.cs file of your client-consuming project, call the AddAzureKeyVaultSecrets extension method on the IConfiguration to add the secrets as part of your app's configuration:

builder.Configuration.AddAzureKeyVaultSecrets(connectionName: "key-vault");

Tip

The connectionName parameter must match the name used when adding the Azure Key Vault resource in the AppHost project.

You can then retrieve a secret-based configuration value through the normal IConfiguration APIs, or by binding to strongly-typed classes with the options pattern.

Add an Azure Secret client

Alternatively, you can use the SecretClient directly to retrieve the secrets on demand:

builder.AddAzureKeyVaultClient(connectionName: "key-vault");

Use injected Azure Key Vault properties

In the AppHost, when you used the WithReference method to pass an Azure Key Vault resource to a consuming client project, Aspire injects several configuration properties that you can use in the consuming project.

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Uri property of a resource called keyvault becomes KEYVAULT_URI.

Use the GetValue() method to obtain these environment variables in consuming projects:

string vaultUri = builder.Configuration.GetValue<string>("KEYVAULT_URI");

Tip

The full set of properties that Aspire injects is available in the client integration documentation. For more information, see Properties of the Azure Key Vault resources.

Use Azure Key Vault resources in client code

After adding the SecretClient to the builder, you can get the SecretClient instance using dependency injection:

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

For full details on using the client integration, see Azure Key Vault Client integration.