Bff.AspNetCore 1.11.0

Bff.AspNetCore

A reusable Backend-For-Frontend engine for ASP.NET Core. It terminates authentication server-side: the browser only ever receives an opaque, httpOnly session cookie, while the Keycloak access / refresh / id tokens live in a Redis-backed token vault. Downstream API calls are reverse-proxied through YARP with a Bearer token attached server-side.

Each per-app BFF (bff-katalogos, bff-erevna, ...) is a ~20-line Program.cs wrapping this package.

Why

A SPA that holds a refresh token in browser storage is one XSS away from a long-lived account takeover. The BFF removes the token from the browser entirely. The native branded login form is preserved — the SPA posts credentials to its own-origin BFF, which does server-to-server ROPC against Keycloak with a confidential client.

What it provides

Quick start

A complete per-app BFF Program.cs:

using Bff.AspNetCore.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddBffServices(builder.Configuration);

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

appsettings.json (secrets come from environment / K8s Secret):

{
  "Bff": {
    "AppName": "katalogos",
    "Keycloak": {
      "Authority": "https://identity.dloizides.com",
      "Realm": "onlinemenu",
      "ClientId": "bff-katalogos-client",
      "ClientSecret": "${BFF_CLIENT_SECRET}"
    },
    "Redis": { "ConnectionString": "redis:6379" },
    "Proxy": {
      "SpaUpstream": "http://katalogos-web",
      "Downstreams": [
        { "Segment": "menus", "Upstream": "http://onlinemenu-api" }
      ]
    },
    "Csrf": {
      "AllowedOrigins": [ "https://katalogos.dloizides.com" ]
    },
    "Methods": {
      "Default": [ "Password" ],
      "RoleOverrides": {
        "door-staff": [ "Pin" ]
      }
    },
    "TenantProxy": {
      "TenantServiceUpstream": "http://tenant-api"
    },
    "Registration": {
      "Enabled": null
    }
  }
}

Registration — is self-serve signup a product you offer?

Bff:Registration:Enabled is a nullable bool gating POST /bff/register and the registrationEnabled capability on GET /bff/config (one resolution, so the endpoint and the advertised capability can never disagree):

Set false on a product that is sold rather than signed up for. Do not instead delete the TenantProxy section: that upstream is plumbing shared by OTP, magic-link and password recovery, and removing it silently breaks all of them. An upstream hostname must never imply a product decision.

Demo — publishing a demo credential on the login page

🔴 Bff:Demo:Username + Bff:Demo:Password are served verbatim to anonymous callers in the demo block of GET /bff/config, so a login page can print them and a visitor can sign in immediately:

{ "demo": { "publishedUsername": "demo", "publishedPassword": "TryMe!2026" } }

Both keys are required; set neither (the default) and the block is "demo": null — no banner, nothing published. A half-configured section publishes nothing rather than leaking a lone username. Never point this at a real user's credential: whatever is configured here is readable by anyone who can type a URL. It is for a throwaway account that is expected to be abused, whose blast radius is one disposable seeded demo tenant.

The optional Methods section declares which login methods this BFF offers. Default is the set every role gets; RoleOverrides restricts (or grants) a named role a different set. When Methods is omitted the BFF falls back to Password only. Listing Otp in Default opens the /bff/otp/* endpoints; without it they return 501. Listing Pin in Default opens /bff/pin/login (the event-scoped PIN login); without it it returns 501.

Public API

// Registration — bind + validate the `Bff` config section and register
// the whole engine (Redis store, ROPC client, YARP proxy, CSRF, endpoints).
IServiceCollection AddBffServices(
    this IServiceCollection services,
    IConfiguration configuration,
    Action<BffOptions>? configure = null);

// Pipeline — anti-forgery middleware + auth endpoints + reverse proxy.
WebApplication UseBff(this WebApplication app);

The SPA contract

The SPA must:

1. Send credentials to the BFF, not Keycloak — POST /bff/login with { username, password }. The response body is { user: { ...claims } }; it never contains a token.
2. Call downstream APIs through /bff/api/* — the cookie is sent automatically; the BFF attaches the Bearer.
3. Send X-BFF-Csrf: 1 on every state-changing request (POST/PUT/PATCH/DELETE) to /bff/* and /bff/api/*.
4. Treat 401 from /bff/api/* or /bff/me as "session ended" — redirect to the login form.

Endpoints

Security notes

• The session cookie is __Host--prefixed: httpOnly, Secure, SameSite=Lax, Path=/. It carries only the opaque session id.
• Refresh-token rotation at the realm level is deferred (Phase 6). The per-session SETNX refresh lock is the concurrency protection until then.
• Request bodies are never logged — login bodies contain passwords.
• Set Keycloak.SkipTlsValidation only for staging's self-signed cert.

License

MIT