Cirreum.Authorization.ApiKey 1.0.1

Cirreum Authorization Provider - API Key

API key authentication provider for the Cirreum Framework

Overview

Cirreum.AuthorizationProvider.ApiKey provides header-based API key authentication for ASP.NET Core applications within the Cirreum ecosystem. It enables secure service-to-service communication and broker authentication scenarios where OAuth/OIDC flows are not appropriate.

Key Features

• Header-based authentication - Validates API keys from configurable HTTP headers
• Multi-client support - Multiple clients can share the same header with unique keys
• Secure validation - Constant-time comparison prevents timing attacks
• Role-based authorization - Configure roles per client for fine-grained access control
• Seamless integration - Works alongside audience-based providers (Entra, Okta) in the same application

Use Cases

• Service-to-service communication
• Broker applications pushing data to APIs
• External system integrations
• Background job authentication
• IoT device connectivity

Installation

dotnet add package Cirreum.AuthorizationProvider.ApiKey

Configuration

Add API key clients to your appsettings.json:

{
  "Cirreum": {
    "Authorization": {
      "Providers": {
        "ApiKey": {
          "Instances": {
            "TrackBroker": {
              "Enabled": true,
              "HeaderName": "X-Api-Key",
              "ClientId": "track-broker",
              "ClientName": "Track Broker Application",
              "Key": "your-secure-api-key-here",
              "Roles": ["App.System"]
            },
            "ExternalService": {
              "Enabled": true,
              "HeaderName": "X-Api-Key",
              "ClientId": "external-service",
              "ClientName": "External Integration Service",
              "Key": "different-secure-key",
              "Roles": ["App.Agent"]
            }
          }
        }
      }
    }
  }
}

Configuration Properties

Secure Key Storage

API keys can be provided in two 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": {
    "LapCastBroker": "@Microsoft.KeyVault(SecretUri=https://your-vault.vault.azure.net/secrets/LapCastBrokerKey)"
  },
  "Cirreum": {
    "Authorization": {
      "Providers": {
        "ApiKey": {
          "Instances": {
            "LapCastBroker": {
              "Enabled": true,
              "HeaderName": "X-Api-Key",
              "ClientId": "lapcast-broker",
              "ClientName": "LapCast Broker",
              "Roles": ["App.System"]
            }
          }
        }
      }
    }
  }
}

The instance name (LapCastBroker) 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("LapCastBroker").

For local development, use user secrets or direct configuration:

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

Generating API Keys

For secure key generation, use RandomNumberGenerator:

var key = Convert.ToBase64String(RandomNumberGenerator.GetBytes(32));

Architecture

The provider follows the Cirreum header-based authorization pattern:

ApiKeyAuthorizationRegistrar
└── Extends HeaderAuthorizationProviderRegistrar
    ├── Registers clients in ApiKeyClientRegistry
    ├── Registers scheme via AuthorizationSchemeRegistry.RegisterHeaderScheme()
    └── Configures ApiKeyAuthenticationHandler

ApiKeyAuthenticationHandler
├── Extracts key from configured header
├── Validates against ApiKeyClientRegistry
├── Builds ClaimsPrincipal with ClientId, ClientName, Roles
└── Uses constant-time comparison for security

ApiKeyAuthorizationInstanceSettings
└── Extends HeaderAuthorizationProviderInstanceSettings
    └── HeaderName, ClientId, ClientName, Roles

Authentication Flow

1. Request arrives with API key header (e.g., X-Api-Key: your-key)
2. ForwardDefaultSelector detects header and routes to API key scheme
3. ApiKeyAuthenticationHandler extracts the key value
4. ApiKeyClientRegistry.ValidateKey() performs secure comparison against all registered clients for that header
5. On match, handler builds ClaimsPrincipal with client identity and roles
6. Authorization policies evaluate roles as normal

Multi-Client Support

Multiple clients can use the same header name with different keys:

{
  "ApiKey": {
    "Instances": {
      "ClientA": {
        "HeaderName": "X-Api-Key",
        "ClientId": "client-a",
        "Key": "key-for-client-a",
        "Roles": ["App.Admin"]
      },
      "ClientB": {
        "HeaderName": "X-Api-Key",
        "ClientId": "client-b",
        "Key": "key-for-client-b",
        "Roles": ["App.User"]
      }
    }
  }
}

The ApiKeyClientRegistry validates the provided key against all clients registered for that header and returns the matching client, enabling different roles and identities per key.

Security Considerations

• Constant-time comparison - Key validation uses CryptographicOperations.FixedTimeEquals to prevent timing attacks
• Key storage - Never commit API keys to source control; use Azure Key Vault or similar secret management
• Key rotation - Plan for key rotation by supporting multiple active keys during transition periods
• Transport security - Always use HTTPS to protect keys in transit
• Least privilege - Assign minimum required roles to each client

Claims

Authenticated requests receive the following claims:

License

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

Cirreum Foundation Framework
Layered simplicity for modern .NET