Azure Key Vault Emulator

A fully featured, emulated version of the Azure Key Vault product.

.NET Aspire has the ability to create emulated, easily referenced resources in development environments - unfortunately Key Vault is not one of those. To work with Key Vault in a dev-env you need to have a deployed, real world instance of the resource in an active Azure Subscription; this emulator removes that requirement.

The emulator does not connect to or update an existing Azure Key Vault, it simply mimics the API (with identical functionality) allowing you to build applications without needing to host a real resource.

You can find a sample application here.

Prerequisites

• Docker

Quickstart (.NET Aspire)

1. Install the Hosting package into your AppHost project:

dotnet add package AzureKeyVaultEmulator.Aspire.Hosting

2. Next you can either override an existing Aspire AzureKeyVaultResource or directly include the AzureKeyVaultEmulator.

var keyVaultServiceName = "keyvault"; // Remember this string, you'll need it to get the vaultUri!

// With existing resource, requires Azure configuration in your AppHost
var keyVault = builder
    .AddAzureKeyVault(keyVaultServiceName)
    .RunAsEmulator(); // Add this line

// OR directly add the emulator as a resource, no configuration required
var keyVault = builder.AddAzureKeyVaultEmulator(keyVaultServiceName);

var webApi = builder
    .AddProject<Projects.MyApi>("api")
    .WithReference(keyVault); // reference as normal

3. Install the Client package into your application using Azure Key Vault:

dotnet add package AzureKeyVaultEmulator.Client

4. Get the connection string that .NET Aspire has injected for you and dependency inject the AzureClients you need:

// Injected by Aspire using the name "keyvault".
var vaultUri = builder.Configuration.GetConnectionString("keyvault") ?? string.Empty;

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

// Or configure which clients you need to use
builder.Services.AddAzureKeyVaultEmulator(vaultUri, secrets: true, keys: true, certificates: false);

5. Now you can use your AzureClients as normal dependency injected services:

private SecretClient _secretClient;

public SecretsController(SecretClient secretClient)
{
    _secretClient = secretClient;
}

public async Task<string> GetSecretValue(string name)
{
    var secret = await _secretClient.GetSecretAsync(name);

    return secret.Value;
}

Optional

Configure your Program.cs to optionally inject the emulated or real Azure Key Vault clients depending on your current execution environment:

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

if(builder.Environment.IsDevelopment())
    builder.Services.AddAzureKeyVaultEmulator(vaultUri, secrets: true, certificates: true, keys: true);
else
    builder.Services.AddAzureClients(client =>
    {
        var asUri = new Uri(vaultUri);

        client.AddSecretClient(asUri);
        client.AddKeyClient(asUri);
        client.AddCertificateClient(asUri);
    });

Note

There's a pending PR to add support for the KeyClient and CertificateClient into the new Aspire.Azure.Security.Client package. Support for these 2 clients is expected in .NET Aspire 9.3.

While the primary purpose of this (forked) project is to provide native .NET Aspire support it does not require it. To use the emulator in a different environment simply pull down the image and follow the setup instructions:

docker pull jamesgoulddev/azure-keyvault-emulator:latest

Roadmap

Some API functionality may not be supported while the initial development is ongoing, please refer to the roadmap below to double check if you're attempting a supported operation. The full API will be supported, but if you run into issues beforehand that's likely the reason why.

• Introduction of the full API for Azure Key Vault:
  • Secrets
  • Keys
  • Certificates
  • Managed HSM
• Separate NuGet package for introducing an emulated Key Vault into your .NET Aspire projects.
• Separate NuGet package for easy usage of the emulator in client applications.
• Complete docker-compose options for integrating the emulator into a cluster.