Chromex.Authentication 2.0.0

Chromex Authentication

A branded, environment-aware authentication package for .NET applications. Provides development workarounds (CLI credentials, database JWT keys) and production paths (Managed Identity, Key Vault). Supports pluggable extensions for SQL and JWT.

Features

• Environment-Aware Authentication: Automatically detects development vs. production environments with configuration-driven behavior
• Development Support:
  • Azure CLI credentials (via az login)
  • Database JWT key storage
  • Early startup verification to fail fast if credentials are unavailable
• Production Support:
  • Azure Managed Identity (recommended)
  • Azure Key Vault integration
• Intelligent Token Caching: Per-scope/audience caching with 5-minute refresh buffer to prevent token expiration during use
• Thread-Safe Operations: Concurrent cache access with proper synchronization
• Pluggable Extensions: SQL and JWT extension points for customization
• Comprehensive Logging: Detailed diagnostics for troubleshooting

Supported Frameworks

• .NET 8.0
• .NET 9.0

Installation

Install via NuGet Package Manager:

dotnet add package Chromex.Authentication

Or via Package Manager Console:

Install-Package Chromex.Authentication

Usage

Basic Setup

Register the authentication service in your application:

using Chromex.Authentication;
using Chromex.Authentication.Configuration;

var builder = WebApplication.CreateBuilder(args);

// Add Chromex Authentication
builder.Services.AddChromexAuthentication();

var app = builder.Build();

// Initialize during startup (automatic mode detection)
var authService = app.Services.GetRequiredService<IChromexAuthenticationService>();
await authService.InitializeAsync();

app.Run();

Getting Access Tokens

public class MyService
{
	private readonly IChromexAuthenticationService _authService;

	public MyService(IChromexAuthenticationService authService)
	{
		_authService = authService;
	}

	public async Task<string> GetSqlTokenAsync()
	{
		// Get token for SQL Database
		return await _authService.GetAccessTokenAsync("https://database.windows.net/.default");
	}

	public async Task<string> GetKeyVaultTokenAsync()
	{
		// Get token for Key Vault
		return await _authService.GetAccessTokenAsync("https://vault.azure.net/.default");
	}
}

Configuration

Development Environment

In development, ensure Azure CLI is logged in:

az login

The service will verify credentials are available and fail fast if they're not.

Production Environment

In production, use Azure Managed Identity:

// This is handled automatically - no explicit configuration needed
// The service will use Managed Identity when running in production

Architecture

Token Caching

• Separate cache per audience/scope ensures tokens for different Azure services don't interfere
• 5-minute refresh buffer prevents token expiration during active use
• Thread-safe cache operations using locks
• Automatic cache invalidation before token expires

Environment Detection

• Development: Uses Azure CLI credentials (az login), applies early verification at startup
• Production: Uses Azure Managed Identity, skips verification (assumes proper identity is assigned)

Startup Verification

During development, InitializeAsync() must be called:

• Verifies az login credentials are cached and accessible
• 30-second timeout prevents hanging if Azure CLI is unresponsive
• Clear error messages guide users to run az login

Not Suitable For

• ❌ Service principals (use ServicePrincipalCredential or DefaultAzureCredential instead)
• ❌ Applications requiring interactive user authentication
• ❌ VDI environments relying on VDI managed identity

Dependencies

• Azure.Identity (1.17.x)
• Azure.Core (1.51.x)
• Azure.Security.KeyVault.Certificates (4.7.x)
• Azure.Security.KeyVault.Keys (4.7.x)
• System.IdentityModel.Tokens.Jwt (8.16.x)
• Microsoft.IdentityModel.Tokens (8.16.x)
• Microsoft.AspNetCore.Authentication.JwtBearer (8.0.x for .NET 8, 9.0.x for .NET 9)

Documentation

For detailed API documentation, see the XML documentation in the package or visit our GitHub repository.

License

See LICENSE.md for details.

Contributing

We welcome contributions! Please feel free to submit pull requests or open issues for bugs and feature requests.

Support

For issues, questions, or contributions, please visit our GitHub repository.