KeyVaultLibrary.Platform 2.0.0

KeyVaultLibrary.Platform

A robust Azure Key Vault integration library providing enhanced security, performance, and reliability features for accessing and managing secrets in multi-tenant environments.

Overview

KeyVaultLibrary simplifies Azure Key Vault integration with advanced features including:

• Memory-based caching with configurable expiration for improved performance
• Tenant-aware secret management for multi-tenant applications
• Comprehensive retry policies for handling transient failures
• Secure connection string management with encryption/decryption
• Extensive error handling and detailed logging
• Seamless dependency injection integration

Multi-Framework Support

This library supports the following .NET frameworks:

• .NET 8.0

Installation

Install the package from NuGet:

dotnet add package KeyVaultLibrary.Platform

Or via Package Manager Console:

Install-Package KeyVaultLibrary.Platform

Configuration

Add the following to your appsettings.json:

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

Usage

Dependency Injection Setup

// Register with dependency injection using URL
services.AddKeyVaultService("https://your-keyvault.vault.azure.net/");

// Register with user-assigned managed identity
services.AddKeyVaultServiceWithUserAssignedManagedIdentity(
    "https://your-keyvault.vault.azure.net/",
    "your-managed-identity-client-id");

// Register with configuration
services.AddKeyVaultService(configuration);

// Register with configuration for user-assigned managed identity
services.AddKeyVaultServiceWithUserAssignedManagedIdentity(
    configuration,
    keyVaultUrlKey: "KeyVault:Url",
    managedIdentityClientIdKey: "KeyVault:ManagedIdentityClientId");

// Register with custom options
services.AddKeyVaultService(options => {
    options.KeyVaultUrl = "https://your-keyvault.vault.azure.net/";
    options.CacheExpirationMinutes = 60;
    options.EnableAutoRefresh = true;
    options.EnableCacheInvalidation = true;
});

// Register with custom options using user-assigned managed identity
services.AddKeyVaultService(options => {
    options.KeyVaultUrl = "https://your-keyvault.vault.azure.net/";
    options.ManagedIdentityClientId = "your-managed-identity-client-id";
    options.CacheExpirationMinutes = 60;
    options.EnableAutoRefresh = true;
});

Direct Instantiation

// Using KeyVaultFactory (recommended)
IKeyVaultService keyVaultService = KeyVaultFactory.Create(keyVaultUrl);

// With user-assigned managed identity
IKeyVaultService keyVaultService = KeyVaultFactory.CreateWithUserAssignedManagedIdentity(keyVaultUrl, "your-managed-identity-client-id");

// With custom token credential
var credential = new DefaultAzureCredential();
IKeyVaultService keyVaultService = KeyVaultFactory.Create(keyVaultUrl, credential);

// With custom options
var options = new KeyVaultServiceOptions {
    KeyVaultUrl = keyVaultUrl,
    CacheExpirationMinutes = 60
};
IKeyVaultService keyVaultService = KeyVaultFactory.Create(options);

// With custom options and user-assigned managed identity
var options = new KeyVaultServiceOptions {
    KeyVaultUrl = keyVaultUrl,
    ManagedIdentityClientId = "your-managed-identity-client-id",
    CacheExpirationMinutes = 60
};
IKeyVaultService keyVaultService = KeyVaultFactory.Create(options);

Retrieving Secrets

// Get connection string for a specific tenant
string connectionString = await keyVaultService.GetConnectionStringAsync(tenantKey, configuration);

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

// Get settings secret value with tenant context
string settingValue = await keyVaultService.GetSettingsSecretValue(configuration, "SettingName", tenantKey);

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

Tenant-Aware Secret Retrieval

The library handles tenant-specific secrets with an intelligent workflow:

1. Decrypts tenant keys automatically if encrypted
2. Retrieves gateway database connection string from Key Vault
3. Queries the gateway database to find tenant-specific Key Vault secret names
4. Retrieves and decrypts tenant-specific connection strings and secrets
5. Falls back to direct decryption or configuration if Key Vault lookup fails

Cache Management

The library includes a sophisticated caching system to improve performance:

// Clear the entire cache when needed (e.g., after updating secrets)
keyVaultService.ClearCache();

Cache features include:

• Memory-based caching with configurable expiration (default: 60 minutes)
• Size-based cache management with automatic compaction when limits are reached
• Optional cache invalidation when secrets are updated
• Efficient cache key generation for tenant-specific secrets
• Thread-safe singleton pattern for caching Key Vault secrets

Using with SQL Connections

// Get a SQL connection for a specific tenant
using (var connection = await keyVaultService.GetSqlConnectionAsync(configuration, tenantKey))
{
    // Use the connection
}

// Execute an action with automatic connection management and retry
await keyVaultService.ExecuteWithConnectionAsync(configuration, async (connection) => {
    // Use the connection to execute commands
    using (var command = connection.CreateCommand())
    {
        command.CommandText = "SELECT * FROM MyTable";
        using (var reader = await command.ExecuteReaderAsync())
        {
            // Process results
        }
    }
}, tenantKey);

Framework-Specific Considerations

• When targeting .NET Framework 4.7.2, nullable reference types are not supported
• For .NET 6.0 and .NET 8.0, nullable reference types are supported
• The library automatically handles compatibility differences between frameworks

Features

Security

• Secure access to Azure Key Vault secrets
• Encryption/decryption of sensitive data using AES with RFC2898 key derivation
• Support for various authentication methods (Managed Identity, Service Principal, Client Secret)
• Tenant key decryption for enhanced security in multi-tenant environments

Performance

• Memory-based caching with configurable expiration
• Size-based cache management with automatic compaction
• Optional auto-refresh of cached secrets
• Cache invalidation on secret updates
• Efficient cache key generation for tenant-specific secrets

Reliability

• Intelligent retry policies for transient failures (HTTP 429, 5xx errors)
• Comprehensive error handling with detailed logging
• Fallback mechanisms when Key Vault is unavailable
• Graceful degradation when services are unavailable

Multi-tenancy

• Tenant-aware secret management
• Tenant-specific connection strings
• Tenant isolation for settings
• Support for tenant-specific Key Vault instances

Integration

• Dependency injection support
• Extension methods for common scenarios
• SQL connection management helpers
• Serilog integration for structured logging

Best Practices

1. Use Caching: Enable caching to reduce the number of calls to Azure Key Vault
2. Handle Exceptions: Always wrap Key Vault calls in try-catch blocks
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. Consider Alternative Caching: For high-load scenarios, consider alternative caching mechanisms:
   • Redis Cache for distributed high-performance caching
   • Azure Cache for Redis as a managed service option
   • Memory Cache with periodic persistence for smaller workloads
   • Blob storage with local memory cache for less frequently accessed secrets

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

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 Dependency Conflicts:

   • When encountering errors like NU1106: Unable to satisfy conflicting requests for 'System.Xml.XmlDocument', use package reference aliases in your project file:

   <PackageReference Include="System.Xml.XmlDocument" Version="4.3.0" />
   <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
   

   • Alternatively, add package binding redirects in your app.config or web.config:

   <runtime>
     <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
       <dependentAssembly>
         <assemblyIdentity name="System.Xml.XmlDocument" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
         <bindingRedirect oldVersion="0.0.0.0-4.3.0.0" newVersion="4.3.0.0" />
       </dependentAssembly>
     </assemblyBinding>
   </runtime>
   

   • For .NET Core and .NET 5+ projects, consider using <PackageReference> with PrivateAssets="All" to prevent dependency conflicts

Dependencies

The library uses different package versions based on the target framework to ensure maximum compatibility:

• Azure.Identity (1.12.0)
• Azure.Security.KeyVault.Secrets (4.6.0)
• Microsoft.Extensions.Caching.Memory (8.0.0)
• Microsoft.Extensions.Configuration (8.0.0)
• Microsoft.Extensions.DependencyInjection (8.0.0)
• Microsoft.Extensions.Logging (8.0.0)
• Polly (8.2.0)
• System.Data.SqlClient (4.9.0)
• Newtonsoft.Json (for serialization/deserialization)