Astrolabe Web Common

• Domain prefixes (e.g., admin.example.com, app.example.com)
• Path segments (e.g., /admin, /dashboard)
• Custom request matching logic

3. Development Mode Controllers

Mark controllers that should only be available during development using [DevMode] attribute, automatically hidden in production.

Common Patterns

Setting Up JWT Authentication

using Astrolabe.Web.Common;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using System.Text;

var builder = WebApplication.CreateBuilder(args);

// 1. Create JWT token parameters
var jwtSecretKey = Encoding.UTF8.GetBytes(builder.Configuration["Jwt:SecretKey"] ?? throw new Exception("JWT secret key not configured"));
var jwtIssuer = builder.Configuration["Jwt:Issuer"] ?? "MyApp";
var jwtAudience = builder.Configuration["Jwt:Audience"] ?? "MyApp";

var jwtToken = new BasicJwtToken(jwtSecretKey, jwtIssuer, jwtAudience);

// 2. Configure authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(jwtToken.ConfigureJwtBearer());

builder.Services.AddAuthorization();

var app = builder.Build();

// 3. Use authentication middleware
app.UseAuthentication();
app.UseAuthorization();

app.Run();

Generating JWT Tokens

using Astrolabe.Web.Common;
using System.Security.Claims;

// Create token generator
var jwtToken = new BasicJwtToken(secretKey, issuer, audience);
var tokenGenerator = jwtToken.MakeTokenSigner();

// Generate token with claims
var claims = new[]
{
    new Claim(ClaimTypes.NameIdentifier, user.Id.ToString()),
    new Claim(ClaimTypes.Name, user.Email),
    new Claim(ClaimTypes.Role, user.Role)
};

// Token expires in 1 hour (3600 seconds)
string token = tokenGenerator(claims, 3600);

// Return to client
return Ok(new { Token = token });

Hosting Multiple SPAs by Domain

using Astrolabe.Web.Common;

var app = builder.Build();

// Main app at example.com
app.UseDomainSpa(app.Environment, "main", fallback: true);

// Admin panel at admin.example.com
app.UseDomainSpa(app.Environment, "admin");

// Dashboard at dashboard.example.com
app.UseDomainSpa(app.Environment, "dashboard");

app.Run();

Directory Structure:

ClientApp/
└── sites/
    ├── main/         # Main SPA files
    ├── admin/        # Admin SPA files
    └── dashboard/    # Dashboard SPA files

Development-Only Controllers

using Astrolabe.Web.Common;
using Microsoft.AspNetCore.Mvc;

// This controller is only available in development mode
[DevMode]
[ApiController]
[Route("api/dev")]
public class DevToolsController : ControllerBase
{
    [HttpGet("clear-cache")]
    public IActionResult ClearCache()
    {
        // Development-only endpoint
        return Ok("Cache cleared");
    }

    [HttpGet("seed-data")]
    public async Task<IActionResult> SeedTestData()
    {
        // Seed test data for development
        return Ok("Data seeded");
    }
}

Hiding Dev Controllers in Production

using Astrolabe.Web.Common;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers(options =>
{
    // Hide controllers marked with [DevMode] in production
    if (!builder.Environment.IsDevelopment())
    {
        options.Conventions.Add(new HideDevModeControllersConvention());
    }
});

var app = builder.Build();
app.Run();

Best Practices

1. Secure Secret Key Storage

// ✅ DO - Store secret keys in configuration/secrets
var secretKey = Encoding.UTF8.GetBytes(builder.Configuration["Jwt:SecretKey"]!);

// ❌ DON'T - Hardcode secret keys
var secretKey = Encoding.UTF8.GetBytes("my-secret-key-123");

2. Use Appropriate Token Expiration

// ✅ DO - Set reasonable expiration times
var token = tokenGenerator(claims, 3600);      // 1 hour for web
var refreshToken = tokenGenerator(claims, 604800); // 7 days for refresh

// ❌ DON'T - Use excessively long or short expirations
var token = tokenGenerator(claims, 31536000); // 1 year - too long
var token = tokenGenerator(claims, 60);       // 1 minute - too short

3. Order SPA Middleware Correctly

// ✅ DO - Most specific routes first, fallback last
app.UseDomainSpa(app.Environment, "admin");
app.UseDomainSpa(app.Environment, "dashboard", pathString: "/dashboard");
app.UseDomainSpa(app.Environment, "main", fallback: true); // Last!

// ❌ DON'T - Put fallback first (it will catch everything)
app.UseDomainSpa(app.Environment, "main", fallback: true);
app.UseDomainSpa(app.Environment, "admin"); // Never reached!

Troubleshooting

Common Issues

Issue: 401 Unauthorized on all requests

• Cause: JWT authentication middleware not configured or in wrong order
• Solution: Ensure app.UseAuthentication() comes before app.UseAuthorization() and before app.MapControllers()

Issue: SPA not loading / 404 errors

• Cause: SPA directory doesn't exist or wrong path
• Solution: Verify ClientApp/sites/{siteDir} exists and contains built SPA files

Issue: All requests going to wrong SPA

• Cause: Fallback SPA middleware registered before specific SPAs
• Solution: Register specific SPAs first, fallback last

Issue: JWT tokens invalid across restarts

• Cause: Secret key changes between restarts
• Solution: Store secret key in persistent configuration (appsettings.json, environment variables, or secrets manager)

Project Structure Location

• Path: Astrolabe.Web.Common/
• Project File: Astrolabe.Web.Common.csproj
• Namespace: Astrolabe.Web.Common