Nabs.Launchpad.Core.Gateway 10.0.219

Nabs Launchpad Core Gateway Library

A comprehensive API Gateway library built on Microsoft's YARP (Yet Another Reverse Proxy) with integrated Azure Active Directory authentication and custom authorization features.

Overview

The Nabs.Launchpad.Core.Gateway library provides a robust, production-ready API Gateway solution that acts as a reverse proxy for microservices architectures. It includes built-in authentication, authorization, CORS support, and service discovery capabilities.

Key Features

• YARP-based Reverse Proxy: Built on Microsoft's high-performance YARP reverse proxy
• Azure AD Integration: Full integration with Microsoft Identity platform for authentication
• Custom Authorization: JWT token generation and validation for downstream services
• Service Discovery: Integration with .NET Aspire service discovery
• CORS Support: Configurable Cross-Origin Resource Sharing
• Request Transformation: Automatic header injection and authorization token forwarding
• Development Authentication: Test authentication handler for development scenarios
• Configuration Validation: FluentValidation-based configuration validation

Key Components

Gateway Configuration

The library uses GatewayOptions to configure the gateway behavior:

public sealed class GatewayOptions
{
    public AuthorizationIssuerOptions AuthorizationIssuerOptions { get; set; }
    public YarpOptions YarpOptions { get; set; }
}

Authentication & Authorization

• Production: Uses Microsoft Identity Web with Azure AD/Entra ID
• Development: Optional test authentication handler for local development
• JWT Token Generation: Issues custom JWT tokens for downstream service authentication
• Authorization Policies: Configurable policies for UI and API access

YARP Integration

• Service Discovery: Automatic service resolution using .NET Aspire
• Request Transformation: Adds custom headers and authorization tokens
• Load Balancing: Built-in load balancing capabilities through YARP

Usage

Basic Setup

var builder = WebApplication.CreateBuilder(args);

builder.AddGateway(gatewayOptions =>
{
    // Configure YARP options
    gatewayOptions.YarpOptions.HeaderName = "X-Custom-Header";
    gatewayOptions.YarpOptions.HeaderValue = "CustomValue";

    // Configure authorization issuer
    gatewayOptions.AuthorizationIssuerOptions.Issuer = "https://your-gateway";
    gatewayOptions.AuthorizationIssuerOptions.Audience = "https://your-api";
    gatewayOptions.AuthorizationIssuerOptions.Key = "your-secret-key";
});

var app = builder.Build();

app.UseGateway();

await app.RunAsync();

Configuration

The gateway expects YARP configuration in appsettings.json:

{
  "ReverseProxy": {
    "Routes": {
      "api-route": {
        "ClusterId": "api-cluster",
        "Match": {
          "Path": "/api/{**catch-all}"
        }
      }
    },
    "Clusters": {
      "api-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "http://api-service/"
          }
        }
      }
    }
  },
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "RedirectUri": "https://your-gateway/signin-oidc"
  }
}

Dependencies

• Microsoft.AspNetCore.App: Core ASP.NET Core framework
• Yarp.ReverseProxy: Microsoft's reverse proxy implementation
• Microsoft.Extensions.ServiceDiscovery.Yarp: Service discovery integration
• Microsoft.Identity.Web: Azure AD authentication
• FluentValidation: Configuration validation
• CommunityToolkit.Mvvm: MVVM helpers

Architecture

The gateway follows a layered architecture:

1. Entry Point: ProjectExtensions provides fluent configuration API
2. Authentication Layer: Handles Azure AD authentication and test scenarios
3. Authorization Layer: Issues JWT tokens for downstream services
4. Proxy Layer: YARP handles request routing and transformation
5. Service Discovery: Automatic service resolution and load balancing

Request Flow

1. Incoming Request: Client sends request to gateway
2. Authentication: Azure AD validates user identity
3. Authorization: Gateway generates JWT token for downstream services
4. Transformation: Custom headers and authorization tokens are added
5. Routing: YARP routes request to appropriate backend service
6. Response: Backend response is returned to client

Testing

The library includes comprehensive test harnesses:

• Launchpad.Harness.Gateway: Test gateway application
• Launchpad.Core.Gateway.UnitTests: Unit test suite
• Integration Tests: Full end-to-end testing capabilities

Best Practices

1. Security: Always use HTTPS in production
2. Configuration: Validate all configuration options
3. Monitoring: Implement proper logging and telemetry
4. Performance: Configure appropriate timeouts and connection limits
5. Scalability: Use service discovery for dynamic service resolution

Development

For development scenarios, the gateway can be configured with test authentication:

// Uncomment for development testing
builder.Services.AddAuthentication("TestAuth")
    .AddScheme<AuthenticationSchemeOptions, TestAuthHandler>("TestAuth", null);

Related Projects

• Nabs.Launchpad.Core.ServiceDefaults: Common service configurations
• Nabs.Launchpad.Core.Portal: Blazor UI that can run behind the gateway
• Nabs.Launchpad.Core.SiloClient: Orleans client integration

License

This project is part of the Nabs Launchpad framework by Net Advantage Business Solutions.