Azure Key Vault Emulator

To consume the emulator in your application, you can either use the helper library or configure the standard Azure SDK clients manually.

Option 1: Using AzureKeyVaultEmulator.Client (Recommended)

Install the client package:

dotnet add package AzureKeyVaultEmulator.Client

Then inject the clients in your Program.cs. The library automatically retrieves the vaultUri from your connection strings (e.g., the one provided by Aspire).

var vaultUri = builder.Configuration.GetConnectionString("keyvault") ?? string.Empty;

// Basic implementation (Secrets only)
builder.Services.AddAzureKeyVaultEmulator(vaultUri);

// Or specify required services
builder.Services.AddAzureKeyVaultEmulator(vaultUri, secrets: true, keys: true, certificates: false);

Option 2: Manual Configuration (No extra dependency)

If you prefer not to add the client library, you must manually configure ClientOptions to allow the use of localhost instead of a valid Azure domain.

var vaultUri = builder.Configuration.GetConnectionString("keyvault") ?? string.Empty;

// Disable verification to allow emulated URIs
var options = new SecretClientOptions { DisableChallengeResourceVerification = true };

builder.Services.AddTransient(s => new SecretClient(
    new Uri(vaultUri), 
    new DefaultAzureCredential(), 
    options));

dotnet add package AzureKeyVaultEmulator.Client

// In Program.cs
var vaultUri = builder.Configuration.GetConnectionString("keyvault") ?? string.Empty;
builder.Services.AddAzureKeyVaultEmulator(vaultUri, secrets: true, keys: true, certificates: true);

When using .NET Aspire, the AzureKeyVaultEmulator.Aspire.Hosting library handles SSL certificate creation and installation automatically. On the first run, you will be prompted to install a localhost certificate; click Yes to install it to your local user trusted authority store.

To customize the emulator behavior, you can provide a configuration section (e.g., via User Secrets) or pass a KeyVaultEmulatorOptions object to the RunAsEmulator method.

// Using a configuration section from User Secrets
var keyVault = builder
    .AddAzureKeyVault("myLocalKeyVault")
    .RunAsEmulator(configSectionName: "KeyVaultEmulator");

// OR passing options directly as an object
var keyVault = builder
    .AddAzureKeyVault(AspireConstants.EmulatorServiceName)
    .RunAsEmulator(new KeyVaultEmulatorOptions
    {
        Persist = true,
        Port = 4997,
        LocalCertificatePath = "C:/Users/MyName/keyvaultemulator/certs",
        LoadCertificatesIntoTrustStore = false,
        ShouldGenerateCertificates = false,
        Lifetime = ContainerLifetime.Persistent,
        ForceCleanupOnShutdown = false,
        UseDotnetDevCerts = false
    });

The AzureKeyVaultEmulatorContainer class allows you to spin up an instance of the Azure Key Vault Emulator using TestContainers. You can start the container and then retrieve pre-configured Azure SDK clients (KeyClient, SecretClient, or CertificateClient) that are automatically pointed to the emulator instance.

To use it, instantiate the container, call await container.StartAsync(), and then use one of the Get...Client() methods to obtain a client for your application logic.

using AzureKeyVaultEmulator.TestContainers;

// Create container with certificate directory and persistence
await using var container = new AzureKeyVaultEmulatorContainer();

// Start the container
await container.StartAsync();

// Get configured AzureSDK clients
var keyClient = container.GetKeyClient();
var secretClient = container.GetSecretClient();
var certificateClient = container.GetCertificateClient();

// Use as normal
var secret = await secretClient.SetSecretAsync("mySecretName", "mySecretValue");

If your application uses Azure.Identity.DefaultAzureCredential, you can automate the credential wiring in your AppHost using WithAzureKeyVaultEmulatorCredentials. This automatically handles credentials, tenant, and authority.

AppHost Configuration

var keyVault = builder.AddAzureKeyVaultEmulator("keyvault");

builder.AddProject<Projects.MyApi>("api")
    .WithAzureKeyVaultEmulatorCredentials(keyVault)
    .WithReference(keyVault);

Consumer (Client) Configuration

On the client side, you must adjust your DefaultAzureCredentialOptions and ClientOptions to allow local/emulated connections:

var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions
{
    DisableInstanceDiscovery = true,
});

builder.Services.AddSingleton(_ => new SecretClient(
    new Uri(vaultUri),
    credential,
    new SecretClientOptions { DisableChallengeResourceVerification = true }));

// AppHost
var keyVault = builder.AddAzureKeyVaultEmulator("keyvault");
builder.AddProject<Projects.MyApi>("api")
    .WithAzureKeyVaultEmulatorCredentials(keyVault)
    .WithReference(keyVault);

// Client
var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions
{
    DisableInstanceDiscovery = true,
});

builder.Services.AddSingleton(_ => new SecretClient(
    new Uri(vaultUri),
    credential,
    new SecretClientOptions { DisableChallengeResourceVerification = true }));

To use the emulator within a .NET Aspire application, follow these steps:

1. Install the Hosting Package

Add the AzureKeyVaultEmulator.Aspire.Hosting package to your AppHost project:

dotnet add package AzureKeyVaultEmulator.Aspire.Hosting

2. Configure the Resource in AppHost

You can either override an existing Azure Key Vault resource or add the emulator directly:

// Option A: Override an existing resource
var keyVault = builder.AddAzureKeyVault("keyvault").RunAsEmulator();

// Option B: Add directly (no Azure config required)
var keyVault = builder.AddAzureKeyVaultEmulator("keyvault");

// Reference it in your projects
var webApi = builder.AddProject<Projects.MyApi>("api").WithReference(keyVault);

3. Enable Data Persistence (Optional)

To keep secrets, keys, and certificates between runs, enable Persist. Note: When using Persist, you MUST specify a fixed Port because Aspire's default random port assignment will break the vault URI baked into the persisted database.

var keyVault = builder
    .AddAzureKeyVault("keyvault")
    .RunAsEmulator(new KeyVaultEmulatorOptions { Persist = true, Port = 4997 });

dotnet add package AzureKeyVaultEmulator.Aspire.Hosting

// In AppHost
var keyVault = builder.AddAzureKeyVaultEmulator("keyvault");
builder.AddProject<Projects.MyApi>("api").WithReference(keyVault);