Getting Started - Single Frontend

Duende.BFF (Backend for Frontend) is a library that helps you build secure, modern web applications by acting as a security gateway between your frontend and backend APIs. This guide will walk you through setting up a simple BFF application with a single frontend.

What You’ll Build

By the end of this guide you will have an ASP.NET Core host that:

• Authenticates users via OpenID Connect and stores the session server-side
• Exposes secure local API endpoints with CSRF protection
• Optionally proxies remote API calls with automatic token attachment

Prerequisites

• .NET 8.0 SDK or later
• A frontend application (e.g., React, Angular, Vue, or plain JavaScript)
• An OpenID Connect-compatible identity provider (e.g., Duende IdentityServer, Auth0, Azure AD)

BFF v4 default frontend

Duende.BFF V4 introduced a new way of configuring the BFF, which automatically configures the BFF using recommended practices. If you’re upgrading from V3, please refer to the upgrade guide.

When in single frontend mode, an implicit default frontend is automatically registered. This ensures all the management routes and OpenID Connect-handling routes are available for your frontend.

When you call .AddFrontend() to add a new frontend, the system switches to multi-frontend mode. If you wish to have a default frontend in multi-frontend mode, you’ll need to explicitly add it. See multi-frontend support for more information on this topic.

Setting Up A BFF project

1. Create A New ASP.NET Core Project

   Create a new ASP.NET Core Web Application:

   dotnet new web -n MyBffApp
   cd MyBffApp

2. Add The Duende.BFF NuGet Package

   Install the Duende.BFF package:

   dotnet add package Duende.BFF

3. Configure BFF In Program.cs

   Add the following to your Program.cs:

   Duende BFF v4

   builder.Services.AddBff()
       .ConfigureOpenIdConnect(options =>
       {
           options.Authority = "https://demo.duendesoftware.com";
           options.ClientId = "interactive.confidential";
           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");
   
           // Add this scope if you want to receive refresh tokens
           options.Scope.Add("offline_access");
       })
       .ConfigureCookies(options =>
       {
           // Because we use an identity server that's configured on a different site
           // (duendesoftware.com vs localhost), we need to configure the SameSite property to Lax.
           // Setting it to Strict would cause the authentication cookie not to be sent after logging in.
           // The user would have to refresh the page to get the cookie.
           // Recommendation: Set it to 'strict' if your IDP is on the same site as your BFF.
           options.Cookie.SameSite = SameSiteMode.Lax;
       });
   
   builder.Services.AddAuthorization();
   
   var app = builder.Build();
   
   app.UseAuthentication();
   app.UseRouting();
   
   // adds antiforgery protection for local APIs
   app.UseBff();
   
   // adds authorization for local and remote API endpoints
   app.UseAuthorization();
   
   app.Run();

   Duende BFF v3

   builder.Services.AddBff();
   
   // Configure the authentication
   builder.Services
       .AddAuthentication(options =>
       {
           options.DefaultScheme = "cookie";
           options.DefaultChallengeScheme = "oidc";
           options.DefaultSignOutScheme = "oidc";
       })
       .AddCookie("cookie", options =>
       {
           // Configure the cookie with __Host prefix for maximum security
           options.Cookie.Name = "__Host-blazor";
   
           // Because we use an identity server that's configured on a different site
           // (duendesoftware.com vs localhost), we need to configure the SameSite property to Lax.
           // Setting it to Strict would cause the authentication cookie not to be sent after logging in.
           // The user would have to refresh the page to get the cookie.
           // Recommendation: Set it to 'strict' if your IDP is on the same site as your BFF.
           options.Cookie.SameSite = SameSiteMode.Lax;
       })
       .AddOpenIdConnect("oidc", options =>
       {
           options.Authority = "https://demo.duendesoftware.com";
           options.ClientId = "interactive.confidential";
           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");
   
           // Add this scope if you want to receive refresh tokens
           options.Scope.Add("offline_access");
       });
   
   builder.Services.AddAuthorization();
   
   
   var app = builder.Build();
   
   app.UseAuthentication();
   app.UseRouting();
   
   // adds antiforgery protection for local APIs
   app.UseBff();
   
   // adds authorization for local and remote API endpoints
   app.UseAuthorization();
   
   // login, logout, user, backchannel logout...
   app.MapBffManagementEndpoints();
   
   app.Run();

   Make sure to replace the Authority, ClientID and ClientSecret with values from your identity provider. Also consider if the scopes are correct.

4. Adding Local APIs

   If your browser-based application uses local APIs, you can add those directly to your BFF app. The BFF supports both controllers and minimal APIs to create local API endpoints.

   It’s important to mark up the APIs with .AsBffApiEndpoint(), because this adds CSRF protection.

   Tip

   Always call .AsBffApiEndpoint() on your local API routes. Without it, the X-CSRF header is not enforced and your endpoints are vulnerable to CSRF attacks. See Local APIs for details.

   Minimal Apis

   Program.cs

   // Adds authorization for local and remote API endpoints
   app.UseAuthorization();
   
   // Place your custom routes after the 'UseAuthorization()'
   app.MapGet("/hello-world", () => "hello-world")
     .AsBffApiEndpoint(); // Adds CSRF protection to the controller endpoints

   Controllers

   Program.cs

   builder.Services.AddControllers();
   
   // ...
   
   app.UseAuthorization();
   
   // When mapping the api controllers, place this after // UseAuthorization()
   app.MapControllers()
     .RequireAuthorization()
     .AsBffApiEndpoint(); // This statement adds CSRF protection to the controller endpoints

   LocalApiController.cs

   [Route("hello")]
   public class LocalApiController : ControllerBase
   {
     [Route("world")]
     [HttpGet]
     public IActionResult SelfContained()
     {
         return Ok("hello world");
     }
   }

5. Adding Remote APIs

   If you also want to call remote api’s from your browser based application, then you should proxy the calls through the BFF.

   The BFF extends the capabilities of Yarp in order to achieve this.

   Tip

   For a comparison of local vs. remote vs. YARP-based APIs, see the API Overview.

   Terminal

   dotnet add package Duende.BFF.Yarp

   Direct forwarding

   Program.cs

   builder.Services.AddBff()
     .AddRemoteApis(); // Adds the capabilities needed to perform proxying to remote APIs.
   
   // ...
   
   // Map any call (including child routes) from /api/remote to https://remote-api-address
   app.MapRemoteBffApiEndpoint("/api/remote", new Uri("https://remote-api-address"))
     .WithAccessToken(RequiredTokenType.Client);

   Yarp

   Program.cs

   builder.Services.AddBff()
     .AddRemoteApis() // This adds the capabilities needed to perform proxying to remote api's.
     .AddYarpConfig(new RouteConfig() // This statement configures yarp.
     {
         RouteId = "route_id",
         ClusterId = "cluster_id",
   
         Match = new RouteMatch
         {
             Path = $"api/remote/{{**catch-all}}"
         }
     }, new ClusterConfig()
     {
         ClusterId = "cluster_id",
   
         Destinations = new Dictionary<string, DestinationConfig>(StringComparer.OrdinalIgnoreCase)
         {
             { "destination_1", new DestinationConfig { Address = "https://remote-api-address" } }
         }
     });
   
   
   // ...
   
   app.UseAuthorization();
   
   // Add the Yarp middleware that will proxy the requests.
   app.MapReverseProxy(proxyApp => {
     proxyApp.UseAntiforgeryCheck();
   });

   You can also use an IConfiguration instead of programmatically configuring the proxy.

6. Adding Server-Side Sessions

   In-Memory

   By default, Duende.BFF uses an in-memory session store. This is suitable for development and testing, but not recommended for production as sessions will be lost when the application restarts.

   Program.cs

   builder.Services.AddBff()
     .AddServerSideSessions(); // Uses in-memory session store by default
   
   // ...existing code for authentication, authorization, etc.

   Entity Framework

   For production scenarios, you can use Entity Framework to persist sessions in a database. First, add the NuGet package:

   Terminal

   dotnet add package Duende.BFF.EntityFramework

   Then configure the session store in your Program.cs:

   Program.cs

   builder.Services.AddBff()
     .AddServerSideSessions()
     .AddEntityFrameworkServerSideSessions(options =>
     {
         options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection"));
     });
   
   // ...existing code for authentication, authorization, etc.

   You will also need to run the Entity Framework migrations to create the necessary tables.

In-memory sessions are not production-ready

The default in-memory session store loses all sessions on application restart and cannot be shared across multiple instances. Always use Entity Framework-backed sessions in production.

Frontend Integration

With the BFF host running, your frontend (JavaScript SPA, React, Angular, etc.) needs to call a few BFF endpoints for authentication and to make API calls. Below is a minimal vanilla JavaScript pattern you can adapt.

Check the current user session

On load, call /bff/user to check whether the user is logged in. This endpoint returns the user’s claims as JSON when authenticated, or a 401/empty response when anonymous.

// Fetch the current user from the BFF session
async function getUser() {
    const response = await fetch('/bff/user', {
        headers: { 'X-CSRF': '1' }
    });

    if (response.ok) {
        return await response.json(); // Array of { type, value } claim objects
    }

    return null; // Not authenticated
}

Login and logout links

Use plain anchor tags pointing to the BFF management endpoints. Do not use fetch for these — they must trigger a full browser redirect.

<!-- Login: redirects to the identity provider -->
<a href="/bff/login">Log in</a>

<!-- Logout: the href must include the session ID from the logout_url claim -->
<!-- Read this from the /bff/user response, not hardcoded -->
<a id="logout-link">Log out</a>

// Wire up logout link with the session-bound URL from /bff/user
const user = await getUser();
if (user) {
    const logoutUrlClaim = user.find(c => c.type === 'bff:logout_url');
    document.getElementById('logout-link').href = logoutUrlClaim?.value ?? '/bff/logout';
}

Calling BFF API endpoints

Every request to a BFF API endpoint must include the X-CSRF: 1 header. Without it, the BFF will reject the request with 401 Unauthorized.

// Centralized fetch wrapper — always add the X-CSRF header
async function bffFetch(url, options = {}) {
    const response = await fetch(url, {
        ...options,
        headers: {
            'X-CSRF': '1',
            ...options.headers,
        },
    });

    // Redirect to login if the session has expired
    if (response.status === 401) {
        window.location.href = `/bff/login?returnUrl=${encodeURIComponent(window.location.pathname)}`;
        return;
    }

    return response;
}

// Example usage
const data = await bffFetch('/api/weather');
const json = await data.json();

Tip

Use bffFetch (or an equivalent interceptor in your framework) consistently throughout your frontend. This ensures every authenticated request includes the CSRF header and gracefully handles session expiry.

Proactive session polling (optional)

To detect server-initiated session termination (e.g., back-channel logout), poll /bff/user periodically:

// Poll every 60 seconds; redirect to login if session ends
setInterval(async () => {
    const user = await getUser();
    if (!user) {
        window.location.href = '/bff/login';
    }
}, 60_000);

See Also

• Multiple Frontends — Serve several SPAs from the same BFF host
• Blazor Applications — BFF setup for Blazor Server and WASM
• Local APIs — Full reference for embedded API endpoints and CSRF protection
• Remote APIs — Direct forwarding to upstream services
• Token Management — How BFF handles access token refresh automatically
• Server-Side Sessions — Persistent session configuration
• Access Token Management — The underlying token lifecycle library used by BFF