Perago.SharedKernel.Authorization 1.0.98

.NET 10.0 This package targets .NET 10.0. The package is compatible with this framework or higher. 
dotnet add package Perago.SharedKernel.Authorization --version 1.0.98
                    


                    

                
NuGet\Install-Package Perago.SharedKernel.Authorization -Version 1.0.98
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Perago.SharedKernel.Authorization" Version="1.0.98" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Perago.SharedKernel.Authorization" Version="1.0.98" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Perago.SharedKernel.Authorization" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Perago.SharedKernel.Authorization --version 1.0.98
                    


                    

                
#r "nuget: Perago.SharedKernel.Authorization, 1.0.98"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Perago.SharedKernel.Authorization@1.0.98
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Perago.SharedKernel.Authorization&version=1.0.98
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Perago.SharedKernel.Authorization&version=1.0.98
                    


                            Install as a Cake Tool

Perago.SharedKernel.Authorization

API authentication, HMAC request signing, opt-in API keys, policy authorization, session revocation, request context, service defaults, health checks, security hardening, rate limiting, OpenAPI conventions, configuration validation, OpenTelemetry, and ASP.NET Core observability middleware for Perago services.

Installation

dotnet add package Perago.SharedKernel.Authorization

Getting Started

JWT Authentication Setup

// appsettings.json
{
  "AuthApiConfiguration": {
    "RequireHttpsMetadata": false,
    "Resilience": {
      "Enabled": true,
      "BackchannelTimeout": "00:00:05",
      "ExceptionsAllowedBeforeBreaking": 3,
      "CircuitBreakDuration": "00:00:30"
    },
    "Resources": [
      {
        "Key": "BackOffice1",
        "IdentityServerBaseUrl": "http://identity-server:9900/auth",
        "OidcApiName": "my_api"
      }
    ]
  }
}

// Program.cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddApiAuthentication(Configuration);
}

public void Configure(IApplicationBuilder app)
{
    app.UseApiAuthentication();
    app.UseAuthorization();
}

When Resilience.Enabled is true (default), each configured authority gets its own OIDC backchannel timeout and circuit breaker. After repeated metadata/JWKS failures, subsequent requests fail fast with 401 instead of waiting on every HTTP call. Retries are intentionally omitted on the authentication hot path.

When multiple Resources entries are configured, AddApiAuthentication registers an issuer-based policy scheme (PeragoAuth) so each request forwards to the JWT scheme that matches the token iss claim instead of trying every authority sequentially.

JWT metadata HTTPS (H1)

AuthApiConfiguration:RequireHttpsMetadata defaults to false so existing HTTP authority URLs keep working until you opt in. When true, JWT bearer metadata and JWKS must be retrieved over HTTPS (authority URL must use https://, or set per-resource RequireHttpsMetadata to false for trusted HTTP deployments).

Startup validation (ValidateAuthApi) fails only when RequireHttpsMetadata is enabled for a resource but IdentityServerBaseUrl is not https://.

HMAC Authentication Setup

HMAC adds an extra security layer for POST/PUT/DELETE requests. Register feature management first. Preferred settings live under FeatureManagement:platform:hmacAuth. Legacy top-level HmacAuth is still used when that feature section is not configured.

services.AddPeragoFeatureManagement(Configuration);
services.AddHmacAuth(Configuration);
app.UseMiddleware<HmacPostRequestMiddleware>();

"FeatureManagement": {
  "RefreshIntervalSeconds": 30,
  "FailOpen": false,
  "platform": {
    "hmacAuth": {
      "enabled": true,
      "sharedSecret": "your-secure-secret-key",
      "allowedClockSkewSeconds": 60,
      "nonceTtlSeconds": 300,
      "nonceStoreProvider": "Memory",
      "skipPaths": ["/api/public/health"],
      "skipPathPrefixes": ["/api/public"]
    }
  }
}

Skip HMAC for Specific Endpoints

[HmacAuthSkip]
[HttpPost("api/public/endpoint")]
public IActionResult PublicEndpoint() => Ok();

API Key Authentication Setup

Opt-in middleware for machine-to-machine endpoints. JWT routes stay unchanged unless marked with [PeragoRequireApiKey].

// appsettings.json
{
  "ErpAPIConfig": {
    "APIKey": "from-env-or-secret-store"
  }
}

// Program.cs / Program.cs
using Perago.SharedKernel.Authorization.ApiKey;

public void ConfigureServices(IServiceCollection services)
{
    services.AddPeragoApiKey(Configuration);
}

public void Configure(IApplicationBuilder app)
{
    app.UseRouting();
    app.UseAuthorization();
    app.UsePeragoApiKey();
    app.MapControllers();
}

[PeragoRequireApiKey]
[HttpGet("api/internal/ping")]
public IActionResult Ping() => Ok();

Callers pass ?apiKey=... or header X-API-Key (prefer the header in production). Invalid or missing keys return 401 with no body. Hosts fail to start if marked endpoints exist without UsePeragoApiKey(). Request logs redact apiKey / api_key and any overridden QueryParameterName. See docs/API_KEY.md for HMAC interaction notes.

Session Revocation

Optional Redis check against JWT session (not sid). STS writes revoked:session:{guid}; matching requests return 401.

services.AddPeragoSessionRevocation(Configuration);
app.UsePeragoSessionRevocation();

See docs/SESSION_REVOCATION.md.

Observability Setup

Correlation IDs, request logging, exception logging, Serilog host enrichment, and optional OpenTelemetry traces/metrics export. See docs/OBSERVABILITY.md in the package for full details.

using Perago.SharedKernel.Authorization.Observability;
using Perago.SharedKernel.Authorization.OpenTelemetry;

// Program.cs / Program.cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddPeragoObservability();
    services.AddPeragoOpenTelemetry(Configuration, Environment, settings =>
    {
        settings.DefaultServiceName = "MyServiceName";
    });
}

public void Configure(IApplicationBuilder app)
{
    app.UsePeragoObservability(); // Exception -> Correlation -> Request logging
}

builder.Host.UsePeragoSerilog("MyServiceName");

Service Defaults

Use the service defaults when a service wants the recommended shared-kernel API stack with one registration point.

public void ConfigureServices(IServiceCollection services)
{
    services.AddPeragoServiceDefaults(Configuration, options =>
    {
        options.EnableConfigurationValidation = true;
        options.EnableExceptionHandling = true;
        options.EnableRequestContext = true;
        options.EnableRateLimiting = true;
        options.EnableOpenApiConventions = true;
        options.EnableOpenTelemetry = true;
        options.EnableSessionRevocation = true;
    });
}

public void Configure(IApplicationBuilder app)
{
    app.UsePeragoServiceDefaults();
}

PeragoServiceDefaultsOptions flags default to false. Opt in explicitly. Environment-specific overrides still apply for Development and Test after consumer configuration runs.

Request Context and Correlation

Register request-context helpers to expose user, organization, tenant, application, request, and correlation metadata through one accessor. The same metadata can be propagated to outgoing HTTP calls and integration messages.

services.AddPeragoRequestContext();
app.UsePeragoRequestContext();

Rate Limiting

Register named policies globally, then apply them per action or controller.

services.AddPeragoRateLimiting(options =>
{
    options.AddFixedWindowPolicy("commands", permitLimit: 20, window: TimeSpan.FromMinutes(1));
});

[PeragoRateLimiter("commands")]
public IActionResult CreateOrder() => Ok();

Configuration Validation

Startup validation fails fast when shared-kernel settings are missing or unsafe. Diagnostics are aggregated and redact secret values.

services.AddPeragoConfigurationValidation(Configuration, options =>
{
    options.EnvironmentName = "Production";
    options.RequireRabbitMq = true;
    options.RequireDatabase = true;
});

Documentation

Package docs include setup and migration details:

Topic Packaged doc
Service defaults docs/SERVICE_DEFAULTS.md
Observability and correlation docs/OBSERVABILITY.md
OpenTelemetry / OTLP docs/TELEMETRY.md
Request and tenant context docs/REQUEST_CONTEXT.md
Multi-tenancy docs/MULTI_TENANCY.md
Health checks docs/HEALTH_CHECKS.md
Exception handling docs/EXCEPTION_HANDLING.md
Authorization policies docs/AUTHORIZATION_POLICIES.md
Resilience docs/RESILIENCE.md
Idempotency docs/IDEMPOTENCY.md
Security hardening docs/SECURITY_HARDENING.md
Rate limiting and store choices docs/RATE_LIMITING.md
Session revocation docs/SESSION_REVOCATION.md
OpenAPI conventions docs/OPENAPI_CONVENTIONS.md
API key authentication docs/API_KEY.md
Configuration validation docs/CONFIGURATION_VALIDATION.md
Migration notes docs/OBSOLETE_API_MIGRATION_NOTES.md

HMAC Headers

Header Description
X-Hmac-Timestamp Unix timestamp (seconds) in UTC
X-Hmac-Nonce Unique random value (e.g., UUID)
X-Hmac-Signature Base64-encoded HMAC-SHA256 signature

Dependencies

Versions are managed centrally in this repository (Directory.Packages.props):

  • Microsoft.AspNetCore.Authentication.JwtBearer (10.0.12)
  • Microsoft.EntityFrameworkCore (10.0.12)
  • Npgsql / Npgsql.EntityFrameworkCore.PostgreSQL / Npgsql.OpenTelemetry (10.0.3)
  • Audit.EntityFramework.Core (32.3.1)
  • MassTransit (7.3.0)
  • Newtonsoft.Json (13.0.4)
  • Polly (8.8.0)
  • Serilog.AspNetCore (10.0.0)
  • Serilog.Exceptions (8.4.0)
  • OpenTelemetry.* (1.19.0); Redis instrumentation is 1.19.0-beta.1
  • StackExchange.Redis (2.13.17)
  • Swashbuckle.AspNetCore (10.2.3)

Target Frameworks

  • net10.0

License

MIT

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.98 35 9/19/2026
1.0.97 35 9/19/2026
1.0.96 54 9/16/2026
1.0.95 69 9/11/2026
1.0.94 54 9/11/2026
1.0.93 58 9/11/2026
1.0.92 74 9/5/2026
1.0.91 62 8/31/2026
1.0.90 65 8/30/2026
1.0.89 89 8/29/2026
1.0.88 91 8/19/2026
1.0.87 74 8/18/2026
1.0.86 77 8/17/2026
1.0.85 85 8/11/2026
1.0.84 65 8/9/2026
1.0.83 113 8/8/2026
1.0.82 141 7/23/2026
1.0.81 111 7/23/2026
1.0.80 115 7/23/2026
1.0.79 113 7/23/2026
Loading failed