KeyVaultReferenceResolver 1.1.0

🔐 KeyVaultReferenceResolver

Seamlessly resolve Azure Key Vault secrets in your .NET configuration — using the same format as Azure App Service.

✨ Why KeyVaultReferenceResolver?

When deploying to Azure App Service, you can reference Key Vault secrets directly in your configuration using the @Microsoft.KeyVault(SecretUri=...) syntax. But what about local development? What about running in Docker, Kubernetes, or other environments?

KeyVaultReferenceResolver bridges that gap. Use the exact same configuration files everywhere — no environment-specific transforms, no code changes, no friction.

┌─────────────────────────────────────────────────────────────────┐
│  appsettings.json                                               │
│  ─────────────────                                              │
│  "ConnectionString": "@Microsoft.KeyVault(SecretUri=https://    │
│                       myvault.vault.azure.net/secrets/db-conn)" │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
          ┌───────────────────────────────────────┐
          │   KeyVaultReferenceResolver           │
          │   ─────────────────────────           │
          │   • Detects Key Vault references      │
          │   • Authenticates via Azure Identity  │
          │   • Resolves secrets automatically    │
          │   • Caches for performance            │
          └───────────────────────────────────────┘
                              │
                              ▼
          ┌───────────────────────────────────────┐
          │  Your Application                     │
          │  ────────────────                     │
          │  config["ConnectionString"]           │
          │  → "Server=prod.db;Password=..."      │
          └───────────────────────────────────────┘

🚀 Quick Start

Installation

dotnet add package KeyVaultReferenceResolver

Basic Usage

using KeyVaultReferenceResolver;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddKeyVaultReferenceResolver()  // ← Just add this line
    .Build();

// That's it! Secrets are resolved automatically.
var connectionString = configuration["ConnectionStrings:Database"];

ASP.NET Core

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddKeyVaultReferenceResolver(options =>
{
    // Fail fast in production, be lenient in development
    options.ThrowOnResolveFailure = builder.Environment.IsProduction();
});

var app = builder.Build();

📝 Configuration Format

Use the standard Azure App Service Key Vault reference format:

{
  "ConnectionStrings": {
    "Database": "@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/db-connection)",
    "Redis": "@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/redis-conn)"
  },
  "ExternalServices": {
    "ApiKey": "@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/api-key/v1)"
  },
  "RegularSetting": "This stays as-is"
}

🔑 Authentication

KeyVaultReferenceResolver uses DefaultAzureCredential by default, which automatically works with:

Custom Credentials

// Managed Identity (User-Assigned)
builder.AddKeyVaultReferenceResolver(
    new ManagedIdentityCredential("client-id-here"));

// Service Principal
builder.AddKeyVaultReferenceResolver(options =>
{
    options.Credential = new ClientSecretCredential(
        tenantId: "...",
        clientId: "...",
        clientSecret: "...");
});

// Chained credentials (try multiple in order)
builder.AddKeyVaultReferenceResolver(
    new ChainedTokenCredential(
        new ManagedIdentityCredential(),
        new AzureCliCredential()));

⚙️ Configuration Options

builder.AddKeyVaultReferenceResolver(options =>
{
    // 🚨 Throw on failure (default: false)
    // Set to true in production to fail fast
    options.ThrowOnResolveFailure = true;

    // ⏱️ Timeout per secret (default: 30 seconds)
    options.Timeout = TimeSpan.FromSeconds(60);

    // 💾 Cache resolved secrets (default: true)
    // Improves performance, secrets resolved once at startup
    options.EnableCaching = true;

    // 🔐 Custom credential (default: DefaultAzureCredential)
    options.Credential = new DefaultAzureCredential();
});

📊 Logging

Get visibility into what's happening:

var loggerFactory = LoggerFactory.Create(builder => 
    builder.AddConsole().SetMinimumLevel(LogLevel.Debug));

builder.AddKeyVaultReferenceResolver(
    options: new KeyVaultReferenceResolverOptions(),
    logger: loggerFactory.CreateLogger("KeyVault"));

Sample output:

info: KeyVault[0] Resolved Key Vault reference: ConnectionStrings:Database
info: KeyVault[0] Resolved Key Vault reference: ExternalServices:ApiKey
info: KeyVault[0] Resolved 2 Key Vault reference(s)

🧪 Testing

Use the built-in MockSecretResolver for unit tests:

[Fact]
public void Configuration_ResolvesSecrets_FromMock()
{
    // Arrange
    var mockResolver = new MockSecretResolver()
        .AddSecret(
            "https://myvault.vault.azure.net/secrets/db-conn",
            "Server=localhost;Database=TestDb")
        .AddSecret(
            "https://myvault.vault.azure.net/secrets/api-key",
            "test-api-key-12345");

    var configuration = new ConfigurationBuilder()
        .AddInMemoryCollection(new Dictionary<string, string?>
        {
            ["Database"] = "@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/db-conn)",
            ["ApiKey"] = "@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/api-key)"
        })
        .AddKeyVaultReferenceResolver(mockResolver)
        .Build();

    // Act & Assert
    Assert.Equal("Server=localhost;Database=TestDb", configuration["Database"]);
    Assert.Equal("test-api-key-12345", configuration["ApiKey"]);
}

MockSecretResolver Features

// Fluent API
var mock = new MockSecretResolver()
    .AddSecret("uri1", "value1")
    .AddSecret("uri2", "value2");

// Bulk add
mock.AddSecrets(new Dictionary<string, string>
{
    ["uri3"] = "value3",
    ["uri4"] = "value4"
});

// Silent mode (returns empty string instead of throwing)
var silentMock = new MockSecretResolver(secrets, throwOnMissing: false);

// Inspection
bool exists = mock.ContainsSecret("uri1");
int count = mock.Count;
mock.Clear();

🛠️ Utility Methods

using KeyVaultReferenceResolver;

// Check if a value is a Key Vault reference
string value = "@Microsoft.KeyVault(SecretUri=https://...)";
bool isRef = KeyVaultReferenceResolverExtensions.IsKeyVaultReference(value);
// → true

// Extract the secret URI
string? uri = KeyVaultReferenceResolverExtensions.ExtractSecretUri(value);
// → "https://..."

🔒 Security Best Practices

1. Use Managed Identity in Azure — No secrets to manage
2. Enable ThrowOnResolveFailure in production — Fail fast if secrets can't be loaded
3. Use specific secret versions for critical configs — Prevents unexpected changes
4. Grant minimal permissions — Only Get permission on secrets is required
5. Audit access — Enable Key Vault logging in Azure

Required Key Vault Permissions

🏗️ Architecture

KeyVaultReferenceResolver/
├── ISecretResolver.cs                      # Interface for DI/testing
├── KeyVaultSecretResolver.cs               # Default Azure implementation
├── MockSecretResolver.cs                   # Testing mock
├── KeyVaultReferenceResolverExtensions.cs  # IConfigurationBuilder extensions
├── KeyVaultReferenceResolverOptions.cs     # Configuration options
└── KeyVaultReferenceResolutionException.cs # Custom exception

📋 Requirements

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

<p align="center"> <b>Stop juggling configuration transforms. Start shipping.</b> </p>