Cirreum.AuthorizationProvider 1.0.15

Cirreum Authorization Provider

Authorization provider abstractions and scheme management for the Cirreum Framework

Overview

Cirreum.AuthorizationProvider is the foundational library for implementing authorization providers within the Cirreum ecosystem. It provides the core abstractions, registration patterns, and scheme management infrastructure needed to build pluggable authorization solutions that integrate seamlessly with ASP.NET Core authentication.

Key Features

🔐 Provider Registration Pattern

A bifurcated approach to implementing authorization providers based on their routing mechanism:

• Audience-based providers - For OAuth/OIDC providers (Entra, Okta, Ping) that route by JWT audience claim, with separate Web API and Web App registration paths
• Header-based providers - For API key and similar providers that route by HTTP header presence
• Multi-instance support - Configure multiple instances of the same provider type with different settings
• Duplicate detection - Automatic prevention of duplicate registrations
• Validation framework - Provider-specific settings validation before registration

🎯 Scheme Registry System

Centralized management of authentication scheme mappings through AuthorizationSchemeRegistry:

• Audience-based routing - Map JWT audience claims to specific authentication schemes for OAuth/OIDC providers
• Header-based routing - Map HTTP headers to authentication schemes for API key and similar providers
• Multi-tenant support - Handle multiple authorization contexts within a single application
• Dynamic scheme resolution - Runtime lookup of appropriate schemes for incoming requests

🔑 API Key Client Resolution

Flexible API key authentication with both static and dynamic resolution:

• Static configuration - Define API keys in appsettings.json for simple scenarios
• Dynamic resolution - Database-backed key lookup for hundreds of partners/customers
• Efficient filtering - Use X-Client-Id header to optimize database queries
• Caching support - Built-in caching layer with configurable TTL
• Composite resolvers - Chain multiple resolvers (config + database) with priority ordering
• Secure validation - Constant-time comparison to prevent timing attacks

🔏 Signed Request Authentication

Bank-grade HMAC signature authentication for high-security scenarios:

• HMAC-SHA256 signatures - Cryptographically signed requests with versioning (v1=)
• Replay protection - Timestamp validation with configurable tolerance (default 2 minutes)
• Key rotation - Support for multiple active signing credentials per client
• Per-client options - Override timestamp tolerance and signature versions per client
• Rate limiting hooks - ISignatureValidationEvents interface for custom rate limiting
• Efficient lookup - Direct database query by X-Client-Id header
• Constant-time comparison - Prevents timing attacks on signature validation
• Allocation-free validation - Span<byte> overloads for high-performance body hashing

⚙️ Configuration Abstractions

Flexible configuration models that support provider-specific settings while maintaining consistency:

• Hierarchical settings - Provider-level settings with instance-specific overrides
• Enabled/disabled instances - Granular control over which provider instances are active
• Configuration binding - Seamless integration with ASP.NET Core configuration system

Secure Key Storage

API keys can be provided in three ways (checked in order):

1. Direct value - Key property in instance configuration (dev/testing only)
2. Connection string - ConnectionStrings:{InstanceName} in configuration (production)

For production environments, store API keys in Azure Key Vault using the connection string pattern:

{
  "ConnectionStrings": {
    "MyAppBroker": "@Microsoft.KeyVault(SecretUri=https://your-vault.vault.azure.net/secrets/MyAppBrokerKey)"
  },
  "Cirreum": {
    "Authorization": {
      "Providers": {
        "ApiKey": {
          "Instances": {
            "MyAppBroker": {
              "Enabled": true,
              "HeaderName": "X-Api-Key",
              "ClientId": "MyApp-broker",
              "ClientName": "MyApp Broker",
              "Roles": ["App.System"]
            }
          }
        }
      }
    }
  }
}

The instance name (MyAppBroker) is used as the connection string key, allowing both the API and client applications to resolve the same secret from Key Vault using configuration.GetConnectionString("MyAppBroker").

For local development, use user secrets:

{
  "Cirreum": {
    "Authorization": {
      "Providers": {
        "ApiKey": {
          "Instances": {
            "MyAppBroker": {
              "Enabled": true,
              "HeaderName": "X-Api-Key",
              "ClientId": "MyApp-broker",
              "Key": "dev-only-key"
            }
          }
        }
      }
    }
  }
}

Provider Types

Authentication Security Levels

Architecture

The library follows a layered architecture designed for extensibility:

AuthorizationProviderRegistrar<TSettings, TInstanceSettings> (Base)
├── Provider Type Identification
├── Instance Management & Validation
└── Abstract RegisterScheme()
    │
    ├── AudienceAuthorizationProviderRegistrar<TSettings, TInstanceSettings>
    │   ├── Registers via AuthorizationSchemeRegistry.RegisterAudienceScheme()
    │   ├── Abstract AddAuthorizationForWebApi()
    │   └── Abstract AddAuthorizationForWebApp()
    │
    └── HeaderAuthorizationProviderRegistrar<TSettings, TInstanceSettings>
        ├── Registers via AuthorizationSchemeRegistry.RegisterHeaderScheme()
        ├── Registers clients via ApiKeyClientRegistry
        └── Abstract AddAuthenticationHandler()

AuthorizationProviderInstanceSettings (Base)
├── Scheme, Enabled, Section
│
├── AudienceAuthorizationProviderInstanceSettings
│   └── Audience
│
└── HeaderAuthorizationProviderInstanceSettings
    └── HeaderName, ClientId, ClientName, Roles

Dynamic Resolution (Database-backed)
├── ApiKey/
│   ├── IApiKeyClientResolver - Interface for key resolution
│   ├── DynamicApiKeyClientResolver - Base class for database lookup
│   ├── ConfigurationApiKeyClientResolver - Static config resolver
│   ├── CachingApiKeyClientResolver - Caching decorator
│   └── CompositeApiKeyClientResolver - Chains multiple resolvers
│
└── SignedRequest/
    ├── ISignedRequestClientResolver - Interface for credential resolution
    ├── DynamicSignedRequestClientResolver - Base class for database lookup
    ├── StoredSigningCredential - Credential model with per-client options
    ├── ISignatureValidator - Signature computation/validation (with Span<byte> overloads)
    ├── DefaultSignatureValidator - HMAC-SHA256 implementation
    └── ISignatureValidationEvents - Rate limiting hooks

Installation

dotnet add package Cirreum.AuthorizationProvider

Usage

Provider implementations (Entra, API Key, etc.) live in separate Infrastructure packages. This package provides the abstractions they build upon.

Audience-Based Provider (OAuth/OIDC)

For providers that authenticate via JWT tokens with audience claims:

public class MyOAuthInstanceSettings : AudienceAuthorizationProviderInstanceSettings
{
    public string TenantId { get; set; } = "";
    public string ClientId { get; set; } = "";
}

public class MyOAuthProvider 
    : AudienceAuthorizationProviderRegistrar<MyOAuthSettings, MyOAuthInstanceSettings>
{
    public override string ProviderName => "MyOAuth";

    public override void AddAuthorizationForWebApi(
        IConfigurationSection instanceSection,
        MyOAuthInstanceSettings settings,
        AuthenticationBuilder authBuilder)
    {
        authBuilder.AddJwtBearer(settings.Scheme, options =>
        {
            instanceSection.Bind(options);
        });
    }

    public override void AddAuthorizationForWebApp(
        IConfigurationSection instanceSection,
        MyOAuthInstanceSettings settings,
        AuthenticationBuilder authBuilder)
    {
        authBuilder.AddOpenIdConnect(settings.Scheme, options =>
        {
            instanceSection.Bind(options);
        });
    }
}

Header-Based Provider (API Key)

For providers that authenticate via HTTP headers:

public class MyApiKeyInstanceSettings : HeaderAuthorizationProviderInstanceSettings
{
    // Inherits: HeaderName, ClientId, ClientName, Roles
    // Add any additional properties here
}

public class MyApiKeyProvider 
    : HeaderAuthorizationProviderRegistrar<MyApiKeySettings, MyApiKeyInstanceSettings>
{
    public override string ProviderName => "MyApiKey";

    protected override void AddAuthenticationHandler(
        string schemeName,
        MyApiKeyInstanceSettings settings,
        AuthenticationBuilder authBuilder)
    {
        authBuilder.AddScheme<MyApiKeyOptions, MyApiKeyHandler>(
            schemeName,
            options => options.HeaderName = settings.HeaderName);
    }
}

Contribution Guidelines

1. Be conservative with new abstractions
   The API surface must remain stable and meaningful.

2. Limit dependency expansion
   Only add foundational, version-stable dependencies.

3. Favor additive, non-breaking changes
   Breaking changes ripple through the entire ecosystem.

4. Include thorough unit tests
   All primitives and patterns should be independently testable.

5. Document architectural decisions
   Context and reasoning should be clear for future maintainers.

6. Follow .NET conventions
   Use established patterns from Microsoft.Extensions.* libraries.

Versioning

Cirreum.AuthorizationProvider follows Semantic Versioning:

• Major - Breaking API changes
• Minor - New features, backward compatible
• Patch - Bug fixes, backward compatible

Given its foundational role, major version bumps are rare and carefully considered.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Cirreum Foundation Framework
Layered simplicity for modern .NET