AzureSecureAccess 1.1.0

Azure Secure Access

A modern .NET library for secure access to Azure Key Vault secrets, certificates, and encryption. Simplifies connecting to SQL Server databases using Always Encrypted with Azure Key Vault as the key store.

✨ Features

• Secrets Management: Retrieve and cache secrets from Azure Key Vault
• Flexible Authentication: Client Secret, Certificate, Managed Identity, or DefaultAzureCredential
• SQL Server Always Encrypted: First-class support with fluent builder API
• Certificate Providers: Load X509 certificates from file, OS store, or Key Vault
• Performance: Built-in caching to reduce API calls and latency
• Clean Architecture: Domain-driven namespaces for intuitive discovery

📦 Installation

dotnet add package AzureSecureAccess

🚀 Quick Start

1. Authentication

Choose the authentication method that fits your scenario:

using AzureSecureAccess.Authentication;

// Client Secret (for service principals)
var credential = new ClientSecretCredentialProvider(tenantId, clientId, clientSecret);

// Certificate-based authentication
var credential = new CertificateCredentialProvider(tenantId, clientId, certificate);

// Managed Identity (Azure-hosted: App Service, AKS, VMs)
var credential = new ManagedIdentityCredentialProvider(); // System-assigned
var credential = new ManagedIdentityCredentialProvider(
    ManagedIdentityId.FromUserAssignedClientId("client-id")); // User-assigned

// DefaultAzureCredential (tries multiple methods automatically)
var credential = new DefaultCredentialProvider();

2. Retrieving Secrets

using AzureSecureAccess.Secrets;

var secretProvider = new KeyVaultSecretProvider("my-keyvault", credential.GetCredential());

// Get the latest version of a secret
string apiKey = await secretProvider.GetSecretValueAsync("ApiKey");

// Get a specific version
string oldKey = await secretProvider.GetSecretVersionValueAsync("ApiKey", "abc123version");

With Caching (reduces API calls)

var baseProvider = new KeyVaultSecretProvider("my-keyvault", credential.GetCredential());
using var cachedProvider = new CachedSecretProvider(baseProvider, TimeSpan.FromMinutes(30));

// First call hits Key Vault, subsequent calls use cache for 30 minutes
string secret = await cachedProvider.GetSecretValueAsync("ApiKey");

3. Working with Certificates

using AzureSecureAccess.Certificates;

// From local file
var localProvider = LocalCertificateProvider.FromFile("/path/to/cert.pfx");
var cert = localProvider.GetCertificate();

// From OS certificate store (by thumbprint)
var storeProvider = LocalCertificateProvider.FromStore("ABC123THUMBPRINT");
var cert = storeProvider.GetCertificate();

// From Azure Key Vault
var kvCertProvider = new KeyVaultCertificateProvider("my-keyvault", credential.GetCredential());
var certWithPrivateKey = await kvCertProvider.GetCertificateAsync("MyCertificate");

4. SQL Server with Always Encrypted

Basic Usage

using AzureSecureAccess.SqlServer;

var credential = new DefaultCredentialProvider();

AlwaysEncryptedProvider.RegisterKeyVaultProvider(credential.GetCredential());

using var connection = new SqlConnection(
    "Server=myserver.database.windows.net;Database=MyDB;Column Encryption Setting=Enabled;");
await connection.OpenAsync();

// Encrypted columns are automatically decrypted!

Advanced: Fluent Builder with Key Vault Secrets

using AzureSecureAccess.SqlServer;

// Connection string stored directly
var connection = new SecureConnectionBuilder()
    .WithCredential(new ManagedIdentityCredentialProvider())
    .WithConnectionString("Server=...;Column Encryption Setting=Enabled;")
    .Build();

// Connection string stored in Key Vault (with caching)
var connection = await new SecureConnectionBuilder()
    .WithCredential(new DefaultCredentialProvider())
    .WithConnectionStringFromKeyVault("my-keyvault", "SqlConnectionString")
    .WithCaching(TimeSpan.FromMinutes(45)) // Cache the connection string
    .BuildAsync();

await connection.OpenAsync();

📚 API Reference

Authentication Providers

Secrets

Certificates

SQL Server

🏗️ Architecture

The library is organized by domain, not technical layers:

AzureSecureAccess
├── Authentication/       ← How to authenticate with Azure
├── Secrets/             ← How to manage secrets
├── Certificates/        ← How to retrieve certificates
└── SqlServer/           ← How to connect to SQL Server with encryption

Each namespace answers a specific question:

• Authentication: How do I prove I'm authorized?
• Secrets: Where are my configuration secrets?
• Certificates: Where are my X509 certificates?
• SqlServer: How do I connect securely to SQL Server?

🔒 Security Best Practices

1. Use Managed Identity in production — Eliminates credential management
2. Enable caching — Reduces API calls but be mindful of secret rotation
3. Use Always Encrypted — Protects data at rest and in transit from DBAs
4. Store connection strings in Key Vault — Never hardcode credentials
5. Apply the least privilege — Grant only necessary Key Vault permissions

🧪 Testing

Unit Tests (default)

dotnet test -f net8.0

Integration Tests (Key Vault + Always Encrypted)

Integration tests only run when RUN_INTEGRATION_TESTS=true is set.

Required environment variables:

• RUN_INTEGRATION_TESTS=true
• AZURE_TENANT_ID
• AZURE_CLIENT_ID
• AZURE_CLIENT_SECRET
• AZURE_KEYVAULT_KEY_ID
• AZURE_KEYVAULT_NAME (required for Key Vault secret/certificate tests)
• AZURE_TESTS_KEEP_DB=true (optional, skips DB cleanup for debugging)

Alternative if you prefer to pass Key Vault name + key:

• AZURE_KEYVAULT_NAME
• AZURE_KEY_NAME
• AZURE_KEY_VERSION

Provision a Key Vault + RSA key + app registration:

• Bash: ./scripts/provision-keyvault.sh <resource-group> <location> <keyvault-name> <app-name>
• PowerShell: ./scripts/provision-keyvault.ps1 -ResourceGroup <rg> -Location <loc> -KeyVaultName <kv> -AppName <app>

Run integration tests:

RUN_INTEGRATION_TESTS=true dotnet test -f net8.0

Azure Pipelines Variable Group

The pipeline expects a variable group named AzureSecureAccess-Integration. Create it in Azure DevOps and add these variables:

• RUN_INTEGRATION_TESTS = true (or false to disable)
• AZURE_TENANT_ID
• AZURE_CLIENT_ID
• AZURE_CLIENT_SECRET
• AZURE_KEYVAULT_KEY_ID
• AZURE_KEYVAULT_NAME
• AZURE_TESTS_KEEP_DB (optional)

If you want a different group name, update azure-pipelines.yml.