Installation & Quick Start

1. Install the package

dotnet add package Methrax.Bff.AspNetCore

2. Add OIDC configuration

The current configuration root is Methrax:BffAuthentication.

{
  "Methrax": {
    "BffAuthentication": {
      "Authority": "https://identity-provider.example.com/realms/main",
      "ClientId": "bff-client-app",
      "ClientSecret": "your-client-secret",
      "RequireHttpsMetadata": true,
      "SaveTokens": true,
      "EnableServerSideSessions": true,
      "Scopes": ["openid", "profile", "offline_access", "api"],
      "Cookie": {
        "SameSite": "Lax",
        "SecurePolicy": "Always",
        "HttpOnly": true
      },
      "Endpoints": {
        "LoginPath": "/login",
        "LogoutPath": "/logout",
        "AccessDeniedPath": "/access-denied"
      }
    }
  }
}

Keep production client secrets outside source control using your deployment platform’s secret/configuration mechanism.

3. Register BFF authentication

using Methrax.Bff.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddBffAuthentication();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.Run();

The package applies configuration from Methrax:BffAuthentication and validates important options during startup.

4. Choose token persistence

Use SaveTokens = true when the BFF must delegate the user’s access token to protected downstream APIs. Use false for a session-only authentication shell.

5. Add server-side sessions when required

For token-persisting BFFs, prefer a server-side ticket store rather than carrying a large encrypted authentication ticket in the browser cookie.

using Microsoft.AspNetCore.Authentication.Cookies;

builder.Services.AddMemoryCache();
builder.Services.AddSingleton<ITicketStore, MemoryCacheTicketStore>();

builder.Services.AddBffAuthentication(options =>
{
    options.SaveTokens = true;
    options.EnableServerSideSessions = true;
});

For multi-instance production deployments, use an appropriate distributed implementation instead of process-local memory.

6. Protect application endpoints

app.MapGet("/api/profile", (HttpContext context) =>
{
    return Results.Ok(new
    {
        name = context.User.Identity?.Name,
        authenticated = context.User.Identity?.IsAuthenticated == true
    });
}).RequireAuthorization();

7. Integrate the SPA

The frontend should use browser cookies rather than storing OAuth tokens itself. For cross-origin development setups, configure credentials/CORS deliberately; production is simplest when the SPA and BFF share the intended same-site boundary.