Skip to content

Commit a69d4e3

Browse files
Erwinvandervalkmaartenba
Erwinvandervalk
authored and
maartenba
committed
BFF v4 - Restructuring
1 parent 93f28f0 commit a69d4e3

File tree

6 files changed

+187
-2
lines changed

6 files changed

+187
-2
lines changed

‎src/content/docs/bff/getting-started/_meta.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
label: "Getting Started"
2+
collapsed: true
3+
order: 1

‎src/content/docs/bff/samples/bff-blazor.mdx renamed to ‎src/content/docs/bff/getting-started/blazor.mdx

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,6 @@ Then you need to configure the application to use the BFF Blazor application. Ad
7272
}
7373
.WithDefaultCookieOptions(options =>
7474
{
75-
options.Cookie.Name = "__Host-blazor";
76-
7775
// Because we use an identity server that's configured on a different site
7876
// (duendesoftware.com vs localhost), we need to configure the SameSite property to Lax.
7977
// Setting it to Strict would cause the authentication cookie not to be sent after loggin in.
@@ -109,6 +107,7 @@ Then you need to configure the application to use the BFF Blazor application. Ad
109107
})
110108
.AddCookie("cookie", options =>
111109
{
110+
// Configure the cookie with __Host prefix for maximum security
112111
options.Cookie.Name = "__Host-blazor";
113112

114113
// Because we use an identity server that's configured on a different site

‎src/content/docs/bff/getting-started/index.mdx

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: Getting started
3+
description: A collection of getting started guides to start with the BFF
4+
sidebar:
5+
order: 1
6+
label: Overview
7+
---
8+
9+
Currently, the most recent version is 4 (preview 1). If you're upgrading from a previous version, please checkout our [upgrade guides](/bff/upgrading).
10+
11+
If you're starting a new BFF project, consider the following startup guides:
12+
13+
* [Single frontend BFF](/bff/getting-started/single-frontend)
14+
* [Single frontend BFF in V3 style](/bff/getting-started/single-frontend-v3)
15+
* [Multi-frontend BFF](/bff/getting-started/multi-frontend)
16+
* [Blazor](/bff/getting-started/blazor)

‎src/content/docs/bff/getting-started/multi-frontend.mdx

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: Getting Started - Multiple frontends
3+
description: A guide on how to create a BFF application with a single frontend.
4+
sidebar:
5+
order: 20
6+
label: Multiple frontends
7+
---

‎src/content/docs/bff/getting-started/single-frontend.mdx

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
title: Getting Started - Single Frontend
3+
description: A guide on how to create a BFF application with a single frontend.
4+
sidebar:
5+
order: 10
6+
label: Single frontend
7+
---
8+
import { Code } from "astro/components";
9+
import { Tabs, TabItem } from "@astrojs/starlight/components";
10+
11+
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.
12+
13+
:::note
14+
Duende.BFF V4 introduces this 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](/bff/upgrading/bff-v3-to-v4)
15+
:::
16+
17+
## Prerequisites
18+
19+
- .NET 8.0 or later
20+
- A frontend application (e.g., React, Angular, Vue, or plain JavaScript)
21+
22+
## Setting up a BFF project
23+
24+
### 1. Create a New ASP.NET Core Project
25+
26+
Create a new ASP.NET Core Web Application:
27+
28+
```sh
29+
dotnet new web -n MyBffApp
30+
cd MyBffApp
31+
```
32+
33+
### 2. Add the Duende.BFF NuGet Package
34+
35+
Install the Duende.BFF package:
36+
37+
```sh
38+
dotnet add package Duende.BFF
39+
```
40+
41+
### 3. Configure BFF in `Program.cs`
42+
43+
Add the following to your `Program.cs`:
44+
45+
{/* prettier-ignore */}
46+
<Tabs syncKey="bffVersion">
47+
{/* prettier-ignore */}
48+
<TabItem label="Duende BFF v4">
49+
```csharp
50+
// BFF setup for blazor
51+
builder.Services.AddBff()
52+
.WithDefaultOpenIdConnectOptions(options =>
53+
{
54+
options.Authority = "https://demo.duendesoftware.com";
55+
options.ClientId = "interactive.confidential";
56+
options.ClientSecret = "secret";
57+
options.ResponseType = "code";
58+
options.ResponseMode = "query";
59+
60+
options.GetClaimsFromUserInfoEndpoint = true;
61+
options.SaveTokens = true;
62+
options.MapInboundClaims = false;
63+
64+
options.Scope.Clear();
65+
options.Scope.Add("openid");
66+
options.Scope.Add("profile");
67+
68+
// Add this scope if you want to receive refresh tokens
69+
options.Scope.Add("offline_access");
70+
}
71+
.WithDefaultCookieOptions(options =>
72+
{
73+
// Because we use an identity server that's configured on a different site
74+
// (duendesoftware.com vs localhost), we need to configure the SameSite property to Lax.
75+
// Setting it to Strict would cause the authentication cookie not to be sent after loggin in.
76+
// The user would have to refresh the page to get the cookie.
77+
// Recommendation: Set it to 'strict' if your IDP is on the same site as your BFF.
78+
options.Cookie.SameSite = SameSiteMode.Lax;
79+
});
80+
81+
builder.Services.AddAuthorization();
82+
```
83+
84+
</TabItem>
85+
{/* prettier-ignore */}
86+
<TabItem label="Duende BFF v3">
87+
```csharp
88+
// BFF setup for blazor
89+
builder.Services.AddBff();
90+
91+
// Configure the authentication
92+
builder.Services
93+
.AddAuthentication(options =>
94+
{
95+
options.DefaultScheme = "cookie";
96+
options.DefaultChallengeScheme = "oidc";
97+
options.DefaultSignOutScheme = "oidc";
98+
})
99+
.AddCookie("cookie", options =>
100+
{
101+
// Configure the cookie with __Host prefix for maximum security
102+
options.Cookie.Name = "__Host-blazor";
103+
104+
// Because we use an identity server that's configured on a different site
105+
// (duendesoftware.com vs localhost), we need to configure the SameSite property to Lax.
106+
// Setting it to Strict would cause the authentication cookie not to be sent after loggin in.
107+
// The user would have to refresh the page to get the cookie.
108+
// Recommendation: Set it to 'strict' if your IDP is on the same site as your BFF.
109+
options.Cookie.SameSite = SameSiteMode.Lax;
110+
})
111+
.AddOpenIdConnect("oidc", options =>
112+
{
113+
options.Authority = "https://demo.duendesoftware.com";
114+
options.ClientId = "interactive.confidential";
115+
options.ClientSecret = "secret";
116+
options.ResponseType = "code";
117+
options.ResponseMode = "query";
118+
119+
options.GetClaimsFromUserInfoEndpoint = true;
120+
options.SaveTokens = true;
121+
options.MapInboundClaims = false;
122+
123+
options.Scope.Clear();
124+
options.Scope.Add("openid");
125+
options.Scope.Add("profile");
126+
127+
// Add this scope if you want to receive refresh tokens
128+
options.Scope.Add("offline_access");
129+
});
130+
131+
builder.Services.AddAuthorization();
132+
133+
```
134+
</TabItem>
135+
</Tabs>
136+
137+
Make sure to replace the Authority, ClientID and ClientSecret with values from your identity provider. Also consider if the scopes are correct.
138+
139+
## Adding local api's
140+
141+
If your browser based application uses local api's, you can add those directly to your BFF app. The BFF supports both controllers and minimal api's to create local api's.
142+
143+
144+
145+
146+
147+
## Adding remote api's
148+
149+
## Adding Server Side Sessions
150+

‎src/content/docs/bff/index.mdx

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,16 @@ The source code for the BFF framework can be found on GitHub. Builds are distrib
4141
/>
4242
</CardGrid>
4343

44+
## Getting started
45+
46+
Currently, the most recent version is 4 (preview 1). If you're upgrading from a previous version, please checkout our [upgrade guides](/bff/upgrading).
47+
48+
If you're starting a new BFF project, consider the following startup guides:
49+
* [Single frontend BFF](/bff/getting-started/single-frontend)
50+
* [Multi-frontend BFF](/bff/getting-started/multi-frontend)
51+
* [Blazor](/bff/getting-started/blazor)
52+
53+
4454
## Background
4555

4656
Single-Page Applications (SPAs) are increasingly common, offering rich functionality within the browser. Front-end development has rapidly evolved with new frameworks and changing browser security requirements. Consequently, best practices for securing these applications have also shifted dramatically.

0 commit comments

Comments
 (0)