Duende Bff

// ✅ v4: AddBff() with fluent OIDC and cookie configurationbuilder.Services.AddBff()    .ConfigureOpenIdConnect(options =>    {        options.Authority = "https://your-idp.example.com";        options.ClientId = "my-bff-client";        options.ClientSecret = "secret";        options.ResponseType = "code";        options.ResponseMode = "query";
        options.GetClaimsFromUserInfoEndpoint = true;        options.SaveTokens = true;        options.MapInboundClaims = false;
        options.Scope.Clear();        options.Scope.Add("openid");        options.Scope.Add("profile");        options.Scope.Add("offline_access"); // Required for refresh tokens    })    .ConfigureCookies(options =>    {        // Use Strict when your IDP is on the same site as the BFF.        // Use Lax when a cross-site redirect is required (e.g., IDP on a different domain).        options.Cookie.SameSite = SameSiteMode.Lax;    });
builder.Services.AddAuthorization();
var app = builder.Build();
app.UseRouting();app.UseAuthentication();app.UseBff();          // Adds CSRF anti-forgery enforcement middlewareapp.UseAuthorization();
app.Run();

// ❌ v4: Do NOT manually wire AddCookie + AddOpenIdConnect when using AddBff()// ConfigureOpenIdConnect and ConfigureCookies handle this correctlybuilder.Services.AddAuthentication()    .AddCookie("cookie")    .AddOpenIdConnect("oidc", ...); // Bypasses BFF's recommended defaults

// ✅ v3: explicit authentication scheme wiringbuilder.Services.AddBff();
builder.Services    .AddAuthentication(options =>    {        options.DefaultScheme = "cookie";        options.DefaultChallengeScheme = "oidc";        options.DefaultSignOutScheme = "oidc";    })    .AddCookie("cookie", options =>    {        options.Cookie.Name = "__Host-bff";        options.Cookie.SameSite = SameSiteMode.Strict;    })    .AddOpenIdConnect("oidc", options =>    {        options.Authority = "https://your-idp.example.com";        options.ClientId = "my-bff-client";        options.ClientSecret = "secret";        options.ResponseType = "code";        options.SaveTokens = true;        options.Scope.Add("offline_access");    });
// ...
app.MapBffManagementEndpoints(); // ✅ Required in v3

// ✅ Trigger login from the SPA (browser navigation, not fetch)// React example:// window.location.href = '/bff/login?returnUrl=/dashboard';
// ✅ Optional: supply a returnUrl to redirect after login// GET /bff/login?returnUrl=/dashboard// The returnUrl must be a local path; absolute URLs are rejected.

// ✅ The sid claim from /bff/user must be passed as a query parameter// GET /bff/logout?sid=<session-id>// This is required to prevent CSRF attacks on the logout endpoint.

// ❌ Do NOT call /bff/logout via fetch() without the sid parameter.// The logout endpoint validates the sid to prevent cross-site logout attacks.

// ✅ Minimal API: decorate with AsBffApiEndpoint()app.MapGet("/api/data", (HttpContext ctx) => Results.Ok("data"))    .RequireAuthorization()    .AsBffApiEndpoint();
// ✅ MVC Controllers: apply to the entire controller via attribute[Route("api/data")][BffApi]public class DataController : ControllerBase{    [HttpGet]    public IActionResult Get() => Ok("data");}
// ✅ MVC Controllers: apply at mapping timeapp.MapControllers()    .RequireAuthorization()    .AsBffApiEndpoint();

// ❌ Do NOT expose BFF API endpoints without AsBffApiEndpoint() or BffApi attribute.// Without it, the x-csrf header is not enforced and the endpoint is CSRF-vulnerable.app.MapGet("/api/data", () => Results.Ok("data"))    .RequireAuthorization(); // Missing .AsBffApiEndpoint()

// ✅ Correct middleware orderapp.UseRouting();app.UseAuthentication();app.UseBff();           // Must be hereapp.UseAuthorization();app.MapControllers().AsBffApiEndpoint();
// ❌ Wrong: UseBff() after UseAuthorization() — anti-forgery is not appliedapp.UseRouting();app.UseAuthentication();app.UseAuthorization();app.UseBff();           // Too late

// ✅ Webhook receiver: skip anti-forgery for endpoints that cannot send the headerapp.MapPost("/api/webhook", (WebhookPayload payload) => Results.Ok())    .AsBffApiEndpoint()    .SkipAntiforgery();

// ✅ Skip BFF's automatic 401/403 conversion — triggers actual OIDC redirect on challengeapp.MapGet("/api/interactive", () => Results.Ok("data"))    .RequireAuthorization()    .AsBffApiEndpoint()    .SkipResponseHandling();

builder.Services.AddBff(options =>{    options.DisableAntiForgeryCheck = context =>        context.Request.Path.StartsWithSegments("/api/webhook");});

// ✅ Direct forwarding via MapRemoteBffApiEndpointbuilder.Services.AddBff()    .AddRemoteApis();
// Maps /api/orders and all sub-paths to https://orders-service/ordersapp.MapRemoteBffApiEndpoint("/api/orders", new Uri("https://orders-service/orders"))    .WithAccessToken(RequiredTokenType.User);    // Attach the user's access token
app.MapRemoteBffApiEndpoint("/api/public", new Uri("https://content-service/public"))    .WithAccessToken(RequiredTokenType.None);    // Anonymous remote API
app.MapRemoteBffApiEndpoint("/api/internal", new Uri("https://internal-service/api"))    .WithAccessToken(RequiredTokenType.Client);  // Client credentials token (machine-to-machine)

// ✅ Custom token retriever: select token based on route or request contextpublic class MyTokenRetriever : IAccessTokenRetriever{    public Task<AccessTokenResult> GetAccessToken(GetAccessTokenContext context)    {        // Custom logic — e.g., choose token based on route or header        return Task.FromResult<AccessTokenResult>(            new BearerTokenResult(context.UserToken, "Bearer"));    }}
// Register per-endpointapp.MapRemoteBffApiEndpoint("/api/custom", new Uri("https://api.example.com"))    .WithAccessToken(RequiredTokenType.User)    .WithAccessTokenRetriever<MyTokenRetriever>();

app.MapRemoteBffApiEndpoint("/api/long-running", new Uri("https://api.example.com"))    .WithAccessToken(RequiredTokenType.User)    .WithForwarderRequestConfig(new ForwarderRequestConfig    {        ActivityTimeout = TimeSpan.FromMinutes(5),        AllowResponseBuffering = true    });

// ✅ Restrict access in addition to token requirementsapp.MapRemoteBffApiEndpoint("/api/admin", new Uri("https://admin-service/api"))    .WithAccessToken(RequiredTokenType.User)    .RequireAuthorization("AdminPolicy");

// ❌ MapRemoteBffApiEndpoint opens the entire sub-path namespace.// Do NOT use broad paths like "/" or "/api" unless all sub-routes should be exposed.app.MapRemoteBffApiEndpoint("/", new Uri("https://backend-service")); // Exposes everything

// ✅ In-memory server-side sessions (development/testing only)builder.Services.AddBff()    .AddServerSideSessions();
// ✅ Production: persist with Entity Framework// dotnet add package Duende.BFF.EntityFrameworkbuilder.Services.AddBff()    .AddEntityFrameworkServerSideSessions(options =>    {        options.UseSqlServer(builder.Configuration.GetConnectionString("BffSessions"));    });

// ✅ Session cleanup (v4): manual registration requiredbuilder.Services.AddBff(options =>{    options.SessionCleanupInterval = TimeSpan.FromMinutes(5);}).AddEntityFrameworkServerSideSessions(options =>{    options.UseSqlServer(connectionString);}).AddSessionCleanupBackgroundProcess();

// ❌ In-memory sessions are NOT suitable for production.// Sessions are lost on restart; BFF horizontal scaling requires a shared store.builder.Services.AddBff()    .AddServerSideSessions(); // No EF store — data lives only in process memory

// ✅ Retrieve the current user access token in a local API endpointapp.MapGet("/api/data", async (HttpContext ctx, IHttpClientFactory factory) =>{    // ATM handles refresh automatically if the token is expired    var token = await ctx.GetUserAccessTokenAsync();
    var client = factory.CreateClient();    client.SetBearerToken(token);
    var response = await client.GetAsync("https://remote-service/data");    return Results.Text(await response.Content.ReadAsStringAsync());}).AsBffApiEndpoint();

// ✅ Named HttpClient with automatic token management (preferred pattern)builder.Services.AddUserAccessTokenHttpClient("apiClient", configureClient: client =>{    client.BaseAddress = new Uri("https://remote-service/");});
app.MapGet("/api/proxy", async (IHttpClientFactory factory) =>{    var client = factory.CreateClient("apiClient"); // Token attached automatically    return Results.Text(await (await client.GetAsync("data")).Content.ReadAsStringAsync());}).AsBffApiEndpoint();

// ✅ Typed HttpClient with token handlerbuilder.Services.AddHttpClient<RemoteApiClient>(client =>{    client.BaseAddress = new Uri("https://remote-service/");}).AddUserAccessTokenHandler();

// ❌ Do NOT manually read tokens from the session and store them in JavaScript.// This defeats the entire purpose of BFF. Tokens must stay server-side.var token = await ctx.GetUserAccessTokenAsync();return Results.Json(new { accessToken = token }); // ❌ Exposes token to browser

// ✅ Manually revoke if needed (e.g., on account compromise)await HttpContext.RevokeUserRefreshTokenAsync();

// ✅ Strict (preferred when IDP is same-site)options.Cookie.SameSite = SameSiteMode.Strict;
// ✅ Lax (required when IDP is on a different domain)options.Cookie.SameSite = SameSiteMode.Lax;
// ❌ None requires Secure=true and is only appropriate for third-party contexts// which are fundamentally incompatible with the BFF patternoptions.Cookie.SameSite = SameSiteMode.None;

// ✅ Trust forwarded headers from proxy (add before UseAuthentication)app.UseForwardedHeaders(new ForwardedHeadersOptions{    ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto});
// ✅ If the BFF is mounted at a sub-path (e.g., /app)app.UsePathBase("/app");

// ✅ Restrict CORS to known origins if the BFF and SPA are on different originsbuilder.Services.AddCors(options =>{    options.AddPolicy("SpaPolicy", policy =>    {        policy.WithOrigins("https://app.example.com")              .AllowAnyHeader()              .AllowAnyMethod()              .AllowCredentials(); // Required for cookie-based auth across origins    });});
app.UseCors("SpaPolicy");

// ✅ Shared key ring (e.g., Azure Blob Storage + Key Vault)builder.Services.AddDataProtection()    .PersistKeysToAzureBlobStorage(/* ... */)    .ProtectKeysWithAzureKeyVault(/* ... */);
// ✅ Shared key ring via database (e.g., Entity Framework)builder.Services.AddDataProtection()    .PersistKeysToDbContext<ApplicationDbContext>();

// ❌ Default in-memory key ring in multi-instance deployments// Each instance generates its own keys; cookies from one instance// cannot be decrypted by another.builder.Services.AddDataProtection(); // No persistence — broken in clusters

// ✅ YARP with BFF extensions — in-code route/cluster configurationbuilder.Services.AddBff();
var proxyBuilder = builder.Services.AddReverseProxy()    .AddBffExtensions(); // Register BFF token management for YARP
// Configure routes in code using LoadFromMemoryproxyBuilder.LoadFromMemory(    routes:    [        new RouteConfig        {            RouteId = "api",            ClusterId = "api-cluster",            Match = new RouteMatch { Path = "/api/{**catch-all}" }        }        .WithAccessToken(TokenType.User)      // Note: YARP uses TokenType, not RequiredTokenType        .WithAntiforgeryCheck()    ],    clusters:    [        new ClusterConfig        {            ClusterId = "api-cluster",            Destinations = new Dictionary<string, DestinationConfig>            {                ["default"] = new DestinationConfig                {                    Address = "https://upstream-api.example.com"                }            }        }    ]);
var app = builder.Build();
app.UseRouting();app.UseAuthentication();app.UseBff();app.UseAuthorization();
// ✅ UseAntiforgeryCheck() must be explicitly added inside MapReverseProxyapp.MapReverseProxy(proxyApp =>{    proxyApp.UseAntiforgeryCheck();});
app.Run();

// ❌ Do NOT omit UseAntiforgeryCheck() in the YARP pipeline —// anti-forgery is not automatically applied to YARP routesapp.MapReverseProxy(); // Missing UseAntiforgeryCheck()

builder.Services.AddBff(options =>{    options.AutomaticallyRegisterBffMiddleware = false;});
var app = builder.Build();
app.UseRouting();app.UseAuthentication();
// ✅ Register BFF middleware components individually for multi-frontend controlapp.UseBffPreProcessing();app.UseBffFrontendSelection();app.UseBffPathMapping();app.UseBffOpenIdCallbacks();app.UseBffStaticFileProxying();
app.UseAuthorization();

builder.Services.AddBff()    .AddFrontend("admin", frontend =>    {        frontend.MatchingPath = "/admin";        frontend.CdnIndexHtmlUrl = new Uri("https://cdn.example.com/admin/index.html");
        frontend.ConfigureOpenIdConnect(options =>        {            options.Authority = "https://idp.example.com";            options.ClientId = "admin-client";            options.ClientSecret = "secret";        });
        frontend.AddRemoteApi("api", remote =>        {            remote.PathMatch = "/api/admin";            remote.TargetUri = new Uri("https://admin-api.example.com");            remote.RequiredTokenType = RequiredTokenType.User;        });    });

public class FrontendConfigTransformer : IIndexHtmlTransformer{    public Task<string> TransformAsync(string indexHtml, HttpContext context)    {        // Inject runtime configuration into the SPA's index.html        var config = $"<script>window.__CONFIG__ = {{ api: '/api' }};</script>";        return Task.FromResult(indexHtml.Replace("</head>", $"{config}</head>"));    }}

builder.Services.AddBff(options =>{    options.IndexHtmlDefaultCacheDuration = TimeSpan.FromMinutes(10);});

// ✅ Blazor Server: AddBlazorServer() integrates BFF session management with the circuit modelbuilder.Services.AddBff()    .ConfigureOpenIdConnect(options =>    {        options.Authority = "https://identity.example.com";        options.ClientId = "blazor-server";        options.ClientSecret = "secret";        options.ResponseType = "code";        options.Scope.Add("api1");        options.Scope.Add("offline_access");        options.SaveTokens = true;    })    .AddBlazorServer();

// ✅ Server-side Program.csbuilder.Services.AddBff()    .ConfigureOpenIdConnect(options =>    {        options.Authority = "https://identity.example.com";        options.ClientId = "blazor-wasm";        options.ClientSecret = "secret";        options.ResponseType = "code";        options.Scope.Add("api1");        options.Scope.Add("offline_access");        options.SaveTokens = true;    })    .AddBffBlazorClient();

// ✅ Client-side Program.cs (WASM project)builder.Services.AddBffBlazorClient(options =>{    options.RemoteApiPath = "/api/remote";    options.Polling = new BffBlazorClientPollingOptions    {        Interval = TimeSpan.FromSeconds(30) // Default is 5 seconds    };});
// AddLocalApiHttpClient<T>() creates a typed HTTP client that routes through the BFF hostbuilder.Services.AddLocalApiHttpClient<WeatherClient>();

public class CustomLogoutEndpoint : ILogoutEndpoint{    private readonly ILogoutEndpoint _inner;
    public CustomLogoutEndpoint(ILogoutEndpoint inner) => _inner = inner;
    public async Task<IResult> ProcessRequestAsync(HttpContext context)    {        // Pre-processing: audit log, cleanup, etc.        var result = await _inner.ProcessRequestAsync(context);        // Post-processing        return result;    }}

public interface IUserSessionStore{    Task<UserSession?> GetUserSessionAsync(UserSessionKey key, CancellationToken ct);    Task CreateUserSessionAsync(UserSession session, CancellationToken ct);    Task UpdateUserSessionAsync(UserSessionKey key, UserSessionUpdate session, CancellationToken ct);    Task DeleteUserSessionAsync(UserSessionKey key, CancellationToken ct);    Task<IReadOnlyCollection<UserSession>> GetUserSessionsAsync(        PartitionKey partitionKey, UserSessionsFilter filter, CancellationToken ct);    Task DeleteUserSessionsAsync(        PartitionKey partitionKey, UserSessionsFilter filter, CancellationToken ct);}