Sylin.Koan.Web.Auth.Services 0.8.0

Koan.Web.Auth.Services

Zero-configuration service-to-service authentication for the Koan Framework using OAuth 2.0 Client Credentials flow.

Features

• Zero Configuration: Works out-of-the-box with package reference
• Attribute-Driven: Declarative service definitions and dependencies
• Auto-Discovery: Automatic service registration and endpoint resolution
• OAuth 2.0 Compliant: Industry-standard client credentials flow
• Container-Aware: Smart service discovery for Docker/local development
• JWT Tokens: Self-contained authentication with scope-based authorization

Quick Start

1. Add Package Reference

   <ProjectReference Include="Koan.Web.Auth.Services" />
   

2. Declare Your Service

   [ApiController]
   [KoanService("my-service", ProvidedScopes = new[] { "data:read", "data:write" })]
   public class MyController : ControllerBase
   {
       private readonly IKoanServiceClient _client;
   
       public MyController(IKoanServiceClient client) => _client = client;
   }
   

3. Call Other Services

   [HttpPost("process")]
   [CallsService("ai-service", RequiredScopes = new[] { "ml:inference" })]
   public async Task<IActionResult> Process([FromBody] ProcessRequest request)
   {
       // Automatic authentication with JWT Bearer token
       var result = await _client.PostAsync<ProcessResult>("ai-service", "/api/process", request);
       return Ok(result);
   }
   

That's it! The framework handles:

• JWT token acquisition and caching
• Service endpoint discovery
• Authorization header injection
• Token refresh and error handling

Configuration (Optional)

{
  "Koan": {
    "Auth": {
      "Services": {
        "ClientId": "my-service",
        "ClientSecret": "production-secret",
        "ServiceEndpoints": {
          "ai-service": "https://ai.example.com",
          "analytics-service": "https://analytics.example.com"
        }
      },
      "TestProvider": {
        "EnableClientCredentials": true,
        "AllowedScopes": ["ml:inference", "analytics:write", "data:read"],
        "RegisteredClients": {
          "my-service": {
            "ClientId": "my-service",
            "ClientSecret": "production-secret",
            "AllowedScopes": ["ml:inference", "analytics:write"]
          }
        }
      }
    }
  }
}

Architecture

Browser → Web App (Cookie Auth) → Service A (JWT) → Service B (JWT)
             ↓                        ↓               ↓
      Session Cookie            Bearer Token    Bearer Token

• User Authentication: Secure HTTP-only cookies for browsers
• Service Authentication: JWT Bearer tokens for API calls
• Progressive Disclosure: Zero config → minimal config → full control

Development vs Production

Development

• Auto-generated client secrets
• Relaxed TLS validation
• Container-aware service discovery
• Verbose logging

Production

• Explicit configuration required
• Strict TLS validation
• Manual service endpoints
• Minimal logging

API Reference

Core Interfaces

IServiceAuthenticator

Handles JWT token acquisition and management.

public interface IServiceAuthenticator
{
    Task<string> GetServiceTokenAsync(string targetService, string[]? scopes = null, CancellationToken ct = default);
    Task<ServiceTokenInfo> GetServiceTokenInfoAsync(string targetService, string[]? scopes = null, CancellationToken ct = default);
    Task InvalidateTokenAsync(string targetService, CancellationToken ct = default);
}

IServiceDiscovery

Resolves service endpoints using container-aware discovery.

public interface IServiceDiscovery
{
    Task<ServiceEndpoint> ResolveServiceAsync(string serviceId, CancellationToken ct = default);
    Task<ServiceEndpoint[]> DiscoverServicesAsync(CancellationToken ct = default);
    Task RegisterServiceAsync(ServiceRegistration registration, CancellationToken ct = default);
}

IKoanServiceClient

Authenticated HTTP client with automatic token injection.

public interface IKoanServiceClient
{
    Task<T?> GetAsync<T>(string serviceId, string endpoint, CancellationToken ct = default) where T : class;
    Task<T?> PostAsync<T>(string serviceId, string endpoint, object? data = null, CancellationToken ct = default) where T : class;
    Task<HttpResponseMessage> SendAsync(string serviceId, HttpRequestMessage request, CancellationToken ct = default);
}

Attributes

[KoanService]

Declares a controller as a service with provided scopes.

[KoanService("service-id", ProvidedScopes = new[] { "scope1", "scope2" }, Description = "Service description")]

[CallsService]

Declares service dependencies with required scopes.

[CallsService("target-service", RequiredScopes = new[] { "scope1" }, Optional = false)]

Configuration

ServiceAuthOptions

Core configuration for service authentication.

ClientCredentialsClient

TestProvider client registration.

Data Types

ServiceTokenInfo

public record ServiceTokenInfo(string AccessToken, DateTimeOffset ExpiresAt, string[] GrantedScopes);

ServiceEndpoint

public record ServiceEndpoint(string ServiceId, Uri BaseUrl, string[] SupportedScopes);

ServiceRegistration

public record ServiceRegistration(string ServiceId, Uri BaseUrl, string[] ProvidedScopes);

Exception Types

ServiceDiscoveryException

Thrown when service endpoint cannot be resolved.

public class ServiceDiscoveryException : Exception
{
    public string ServiceId { get; }
}

ServiceAuthenticationException

Thrown when token acquisition fails.

public class ServiceAuthenticationException : Exception
{
    public string ServiceId { get; }
    public string[] RequestedScopes { get; }
}

Documentation

• Technical Documentation - Architecture and implementation details
• Usage Samples - Comprehensive usage examples
• Decision Document - Design decisions and rationale

Examples

See samples/S5.Recs/Controllers/ServiceDemoController.cs for complete examples.