KeyVaultLibrary.Platform 1.0.6

SEyc KeyVault Library

Enhanced Azure Key Vault library with caching, retry policies, and comprehensive error handling.

Features

• Secure access to Azure Key Vault secrets
• Built-in caching for improved performance
• Automatic retry policies for transient failures
• Connection string management with tenant isolation
• Dependency injection support
• Comprehensive error handling
• Settings secret management
• Multi-tenant support

Installation

Package Manager Console

Install-Package KeyVaultLibrary.Platform

.NET CLI

dotnet add package KeyVaultLibrary.Platform

Package References

Ensure your project has the following package references:

<PackageReference Include="Azure.Identity" Version="1.12.0" />
<PackageReference Include="Azure.Security.KeyVault.Secrets" Version="4.6.0" />
<PackageReference Include="Microsoft.Extensions.Caching.Memory" Version="8.0.0" />
<PackageReference Include="Microsoft.Extensions.Configuration" Version="8.0.0" />
<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="8.0.0" />
<PackageReference Include="Microsoft.Extensions.Logging" Version="8.0.0" />
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0" />
<PackageReference Include="Polly" Version="8.2.0" />
<PackageReference Include="System.Data.SqlClient" Version="4.9.0" />

Configuration

Add the following to your appsettings.json:

{
  "KeyVaultUri": "https://your-keyvault.vault.azure.net/",
  "LicenseKey": "your-license-key"
}

Basic Usage

Creating a Key Vault Service

// Using the factory (recommended approach)
string keyVaultUrl = configuration["KeyVaultUri"];
var keyVaultService = KeyVaultFactory.Create(keyVaultUrl);

// Alternative: Direct instantiation with default credentials
var keyVaultService = new KeyVaultService(
    keyVaultUrl: "https://your-vault.vault.azure.net",
    logger: loggerInstance // Optional
);

Working with Connection Strings

// Get default connection string
string defaultConnectionString = await keyVaultService.GetConnectionStringAsync(configuration);

// Get tenant-specific connection string
string tenantConnectionString = await keyVaultService.GetConnectionStringAsync("tenant123", configuration);

Working with Settings

// Get a settings secret value for a specific tenant
string settingValue = await keyVaultService.GetSettingsSecretValue(configuration, "SettingName", "tenant123");

// Get a global settings secret value
string globalSettingValue = await keyVaultService.GetSettingsSecretValue(configuration, "GlobalSettingName");

Dependency Injection

ASP.NET Core Registration

// In Startup.cs or Program.cs:

// Simple registration with direct URL
services.AddKeyVaultService("https://your-vault.vault.azure.net");

// Registration with configuration
// Note: By default, looks for "KeyVault:Url" in configuration
services.AddKeyVaultService(Configuration);

// Registration with configuration and custom key
// If your config uses "KeyVaultUri" instead of "KeyVault:Url"
services.AddKeyVaultService(Configuration, "KeyVaultUri");

// Registration with custom options
services.AddKeyVaultService(options => {
    options.KeyVaultUrl = "https://your-vault.vault.azure.net";
    options.Credential = new ClientSecretCredential(tenantId, clientId, clientSecret);
    options.CacheExpirationMinutes = 60;
    options.EnableCaching = true;
    options.EnableAutoRefresh = false;
    options.EnableCacheInvalidation = true;
});

Usage in Services

public class MyService
{
    private readonly IKeyVaultService _keyVaultService;
    private readonly IConfiguration _configuration;
    
    public MyService(IKeyVaultService keyVaultService, IConfiguration configuration)
    {
        _keyVaultService = keyVaultService;
        _configuration = configuration;
    }
    
    public async Task<string> GetSettingValueAsync(string settingName, string tenantId)
    {
        return await _keyVaultService.GetSettingsSecretValue(_configuration, settingName, tenantId);
    }
    
    public async Task<string> GetConnectionStringAsync(string tenantId)
    {
        return await _keyVaultService.GetConnectionStringAsync(tenantId, _configuration);
    }
}

Advanced Features

KeyVaultFactory

The KeyVaultFactory class provides several static methods to create IKeyVaultService instances:

// Basic factory method with just the Key Vault URL
var keyVaultService = KeyVaultFactory.Create("https://your-vault.vault.azure.net");

// With custom token credential
var credential = new ManagedIdentityCredential();
var keyVaultService = KeyVaultFactory.Create("https://your-vault.vault.azure.net", credential);

// With custom token credential and logger
var logger = LoggerFactory.Create(builder => builder.AddConsole()).CreateLogger<KeyVaultService>();
var keyVaultService = KeyVaultFactory.Create("https://your-vault.vault.azure.net", credential, logger);

// With custom options
var options = new KeyVaultServiceOptions
{
    KeyVaultUrl = "https://your-vault.vault.azure.net",
    Credential = new ClientSecretCredential(tenantId, clientId, clientSecret),
    CacheExpirationMinutes = 60,
    EnableCaching = true,
    EnableAutoRefresh = true,
    AutoRefreshBeforeExpirationMinutes = 5,
    EnableCacheInvalidation = true
};
var keyVaultService = KeyVaultFactory.Create(options);

Cache Control

The library provides built-in caching for improved performance. You can control caching behavior:

// Get a connection string bypassing the cache
string connectionString = await keyVaultService.GetConnectionStringAsync("tenant123", configuration, useCache: false);

// Get a settings value (no cache control parameter available)
string settingValue = await keyVaultService.GetSettingsSecretValue(configuration, "SettingName", "tenant123");

When creating the service, you can configure caching options:

services.AddKeyVaultService(options => {
    options.KeyVaultUrl = "https://your-vault.vault.azure.net";
    options.CacheExpirationMinutes = 60; // Default is 30 minutes
    options.EnableCaching = true; // Default is true
    options.EnableAutoRefresh = true; // Default is false
    options.AutoRefreshBeforeExpirationMinutes = 5; // Default is 5 minutes
    options.EnableCacheInvalidation = true; // Default is true
});

Logging

Enable logging to troubleshoot issues:

ILogger<KeyVaultService> logger = LoggerFactory.Create(builder =>
{
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Debug);
}).CreateLogger<KeyVaultService>();

IKeyVaultService keyVaultService = new KeyVaultService(keyVaultUrl, logger);

Best Practices

1. Use Caching: Enable caching to reduce the number of calls to Azure Key Vault.
2. Handle Exceptions: Always handle exceptions when calling Key Vault methods.
3. Provide Fallbacks: Implement fallback mechanisms for when Key Vault is unavailable.
4. Use Async Methods: Prefer async methods for better performance.
5. Secure Connection Strings: Store connection strings in Key Vault rather than in configuration files.
6. Tenant Isolation: Use tenant-specific secrets when working in a multi-tenant environment.

Troubleshooting

Common Issues

1. Authentication Failures:

   • Ensure your application has the correct permissions to access the Key Vault.
   • Verify that the Managed Identity or Service Principal is correctly configured.

2. Secret Not Found:

   • Check that the secret name is correct and exists in the Key Vault.
   • Verify that the Key Vault URL is correct.

   try {
       string settingValue = await _keyVaultService.GetSettingsSecretValue(_configuration, "SettingName");
       if (string.IsNullOrEmpty(settingValue)) {
           // Handle missing setting
       }
   } catch (RequestFailedException ex) when (ex.Status == 404) {
       // Setting not found
   }
   

3. Connection Issues:

   • Check network connectivity to Azure Key Vault.
   • Verify that any firewalls or network security groups allow traffic to Azure Key Vault.

4. Package Version Conflicts:

   • Ensure all projects reference compatible package versions, especially:
     • System.Data.SqlClient (version 4.9.0)
     • Microsoft.Extensions.Configuration.Abstractions (version 8.0.0)

License

MIT