CerbiShield.Authentication-Shared 1.2.0

CerbiShield.Authentication-Shared

A robust, configuration-driven JWT authentication library for ASP.NET Core applications with multi-audience support and deterministic app context resolution.

Version: 1.2.0 | Target Framework: .NET 8.0

What's New in 1.2.0

• Multi-audience validation: Automatically validates tokens with GUID or api://GUID format audiences
• App context resolution: Deterministic resolution from headers, claims, or configuration
• App context middleware: UseCerbiAppContext() with fail-fast 400 responses
• Enhanced diagnostics: Detailed logging of audience/issuer mismatches
• Diagnostics endpoint: Optional /api/system/whoami endpoint helper

Migration from 1.0.2/1.1.x

Required Changes

1. Add the X-Cerbi-App header to all API requests (sent by your router/gateway):

   X-Cerbi-App: your-app-name
   

2. Add new environment variables (optional but recommended):

   # If your audience is a GUID, both formats are auto-supported:
   JWT__Audience=12345678-1234-1234-1234-123456789012
   
   # Or explicitly add additional audiences:
   JWT__AdditionalAudiences=api://your-app,https://your-api.com
   

3. Update your Program.cs to include app context middleware:

   app.UseAuthentication();
   app.UseCerbiAppContext();  // NEW - add after UseAuthentication
   app.UseAuthorization();
   

Breaking Changes

• IdentityProviderOptions.AdditionalAudiences is a new property (List<string>)
• App context is now required by default (set IdentityProvider:RequireAppContext=false to disable)

Installation

dotnet add package CerbiShield.Authentication-Shared --version 1.2.0

Quick Start

1. Configure appsettings.json

{
  "JWT": {
    "Authority": "https://login.microsoftonline.com/{tenant-id}/v2.0",
    "Audience": "12345678-1234-1234-1234-123456789012"
  },
  "IdentityProvider": {
    "AppContextHeader": "X-Cerbi-App",
    "RequireAppContext": true
  }
}

2. Configure Program.cs

using CerbiShield.Authentication.Extensions;
using CerbiShield.Authentication.Middleware;
using CerbiShield.Authentication.Diagnostics;

var builder = WebApplication.CreateBuilder(args);

// Register IConfiguration (required)
builder.Services.AddSingleton<IConfiguration>(builder.Configuration);

// Add CerbiShield JWT authentication with multi-audience support
builder.Services.AddCerbiJwtAuthentication(builder.Configuration);

builder.Services.AddControllers();

var app = builder.Build();

// Middleware order is important!
app.UseAuthentication();
app.UseCerbiAppContext();  // Resolves and validates app context
app.UseAuthorization();

// Optional: Add diagnostics endpoint
app.MapCerbiWhoAmI();  // Maps /api/system/whoami

app.MapControllers();
app.Run();

Features

Multi-Audience JWT Validation

Tokens from different sources (MSAL, Azure CLI, etc.) may have different audience formats:

CerbiShield automatically validates both formats when you configure a GUID audience:

{
  "JWT": {
    "Audience": "12345678-1234-1234-1234-123456789012"
  }
}

This automatically allows:

• 12345678-1234-1234-1234-123456789012
• api://12345678-1234-1234-1234-123456789012

App Context Resolution

App context is resolved deterministically in this order:

1. X-Cerbi-App header (canonical - highest priority)
2. Configured AppClaim from token (default: app)
3. azp claim (OAuth2 authorized party)
4. appid claim (Azure AD v1)
5. Route value appName
6. DefaultAppName config (dev/test only)

// Access the resolved app context in your controller:
var appName = HttpContext.Items["CerbiApp"] as string;

// Or inject IAppContextResolver for detailed info:
public class MyController : ControllerBase
{
    private readonly IAppContextResolver _appResolver;
    
    public MyController(IAppContextResolver appResolver)
    {
        _appResolver = appResolver;
    }
    
    [HttpGet]
    public IActionResult Get()
    {
        var result = _appResolver.ResolveWithDetails(HttpContext);
        // result.AppName, result.Source, result.DiagnosticMessage
    }
}

App Context Middleware

The middleware validates app context and returns 400 if not resolved:

{
  "error": "app_context_required",
  "message": "Application context could not be resolved. Please include the 'X-Cerbi-App' header.",
  "correlationId": "abc123",
  "details": {
    "headerExpected": "X-Cerbi-App",
    "resolutionAttempts": ["..."]
  }
}

To disable (not recommended for production):

{
  "IdentityProvider": {
    "RequireAppContext": false
  }
}

Configuration Reference

JWT Settings

IdentityProvider Settings

Diagnostics

Startup Logs

========== CerbiShield JWT Authentication Configuration (v1.2.0) ==========
[JWT Config] Provider=Entra ID (Azure AD) Authority=https://login.microsoftonline.com/tenant/v2.0
[JWT Config] ValidAudiences (2): 12345678-... | api://12345678-...
[App Context] Header=X-Cerbi-App RequireAppContext=True DefaultAppName=(not set)
==========================================================================

Authentication Failure Logs

JWT authentication FAILED. Reason=Invalid audience: 'wrong-audience'
[AUTH DIAGNOSTIC] Allowed audiences: 12345678-..., api://12345678-...

License

MIT