BFF v4 updates

Author: Erwinvandervalk

src/content/docs/bff/architecture/index.md

@@ -22,21 +22,33 @@ functions:
 * Server-side Token Management
 * Blazor support with unified authentication state management across rendering modes.
 
+## Authentiation flow
+
+The following diagram shows how the BFF protects browser based applications.  
+
 ![BFF Security Framework Architecture Overview](../images/bff_application_architecture.svg)
 
+
+* **Authentication flows**: The server handles the authentication flows. There are specific endpoints for login / logout. While the browser is involved with these authentication flows, because the user is redirected to and from the identity provider, the actual browser based application will never see the authentication tokens. These are exchanged for a code on the server only. 
+* **Cookies**: After successful authentication, a cookie is added. This cookie protects all subsequent calls to the apis. When using this type of authentication, **CSRF protection** is very important. 
+* **Access to apis**: The BFF can expose embedded apis (which are embedded in the BFF itself) or proxy calls to remote api's (which is more common in a microservice environment). While proxying, it will exchange the authentication cookie for an access token. 
+* **Session Management**: The BFF can manage the users session. This can either be cookie based session management or storage based session management. 
+
+
+## Internals
 Duende.BFF builds on widely used tools and frameworks, including ASP.NET Core's OpenID Connect and cookie authentication
 handlers, YARP, and Duende.AccessTokenManagement. Duende.BFF combines these tools and adds additional security and
 application features that are useful with a BFF architecture so that you can focus on providing application logic
 instead of security logic:
 
 ![Duende BFF Security Framework - components](../images/bff_blocs.svg)
 
-## ASP.NET OpenID Connect Handler
+### ASP.NET OpenID Connect Handler
 
 Duende.BFF uses ASP.NET's OpenID Connect handler for OIDC and OAuth protocol processing. As long-term users of and
 contributors to this library, we think it is a well implemented and flexible implementation of the protocols.
 
-## ASP.NET Cookie Handler
+### ASP.NET Cookie Handler
 
 Duende.BFF uses ASP.NET's Cookie handler for session management. The Cookie handler provides a claims-based identity to
 the application persisted in a digitally signed and encrypted cookie that is protected with modern cookie security
@@ -45,28 +57,28 @@ support, and has a flexible extensibility model, which Duende.BFF uses to
 implement [server-side session management](/bff/fundamentals/session/server-side-sessions/)
 and [back-channel logout support](/bff/fundamentals/session/management/back-channel-logout/).
 
-## Duende.AccessTokenManagement
+### Duende.AccessTokenManagement
 
 Duende.BFF uses the Duende.AccessTokenManagement library for access token management and storage. This includes storage
 and retrieval of tokens, refreshing tokens as needed, and revoking tokens on logout. The library provides integration
 with the ASP.NET HTTP client to automatically attach tokens to outgoing HTTP requests, and its underlying management
 actions can also be programmatically invoked through an imperative API.
 
-## API Endpoints
+### API Endpoints
 
 In the BFF architecture, the frontend makes API calls to backend services via the BFF host exclusively. Typically, the
 BFF acts as a reverse proxy to [remote APIs](/bff/fundamentals/apis/remote), providing session and token management.
 Implementing local APIs within the BFF host is also [possible](/bff/fundamentals/apis/local). Regardless, requests to
 APIs are authenticated with the session cookie and need to be secured with an anti-forgery protection header.
 
-## YARP
+### YARP
 
 Duende.BFF proxies requests to remote APIs using Microsoft's YARP (Yet Another Reverse Proxy). You can set up YARP using
 a simplified developer-centric configuration API provided by Duende.BFF, or if you have more complex requirements, you
 can use the full YARP configuration system directly. If you are using YARP directly, Duende.BFF
 provides [YARP integration](/bff/fundamentals/apis/yarp) to add BFF security and identity features.
 
-## UI Assets
+### UI Assets
 
 The BFF host typically serves at least some of the UI assets of the frontend, which can be HTML/JS/CSS, WASM, and/or
 server-rendered content. Serving the UI assets, or at least the index page of the UI from the same origin as the backend
@@ -78,7 +90,7 @@ SameSite cookie attribute prevents the frontend from sending the authentication
 It is also possible to separate the BFF and UI and host them separately. See [here](/bff/architecture/ui-hosting) for
 more discussion of UI hosting architecture.
 
-## Blazor Support
+### Blazor Support
 
 Blazor based applications have unique challenges when it comes to authentication state. It's possible to mix various
 rendering models in a single application. Auto mode even starts off server rendered, then transitions to WASM when the

src/content/docs/bff/architecture/ui-hosting.md

@@ -102,4 +102,8 @@ a number of [deployment options](https://angular.io/guide/deployment) that allow
 assets.
 
 The added complexity of this technique is justified when there is a requirement to host the front end on a different
-site (typically a CDN) from the BFF.
+site (typically a CDN) from the BFF.
+
+:::note
+BFF V4 has built-in support for proxying the index.html from a CDN. 
+:::

src/content/docs/bff/fundamentals/apis/_meta.yml

@@ -1,2 +1,3 @@
 label: "API Endpoints"
-collapsed: true
+collapsed: true
+order: 100

src/content/docs/bff/fundamentals/apis/index.md

@@ -15,10 +15,14 @@ redirect_from:
 
 A frontend application using the BFF pattern can call two types of APIs:
 
-#### Remote APIs
+#### Embedded (local) APIs
 
-These APIs are deployed on a different host than the BFF, which allows them to be shared between multiple frontends or (more generally speaking) multiple clients. These APIs can only be called via the BFF host acting as a proxy.
+These APIs embedded inside the BFF and typically exist to support the BFF's frontend; they are not shared with other frontends or services. 
+
+See [Embedded apis](local.mdx) for more information. 
 
-#### Local APIs
+#### Proxying to Remote APIs
+
+These APIs are deployed on a different host than the BFF, which allows them to be shared between multiple frontends or (more generally speaking) multiple clients. These APIs can only be called via the BFF host acting as a proxy.
 
-These APIs only exist to support the specific frontend; they are not shared with other frontends or services. They are located in the BFF host and can be called directly by the frontend.
+You can use [Direct Forwarding](./remote.md) for most scenarios. If you have more complex requirements, you can also directly interact with [YARP](./yarp.md)

src/content/docs/bff/fundamentals/apis/local.mdx

@@ -1,6 +1,6 @@
 ---
-title: "Local APIs"
-description: Documentation about Local APIs in BFF, including self-contained APIs and those using managed access tokens, along with securing endpoints and configuration details.
+title: "Embedded (local) APIs"
+description: Documentation about Embedded (Embedded) APIs in BFF, including self-contained APIs and those using managed access tokens, along with securing endpoints and configuration details.
 sidebar:
   order: 10
 redirect_from:
@@ -13,28 +13,28 @@ redirect_from:
 
 import { Steps } from "@astrojs/starlight/components";
 
-A _Local API_ is an API located within the BFF host. Local APIs are implemented with the familiar ASP.NET abstractions of API controllers or Minimal API endpoints.
+An _Embedded API_ (or local api) is an API located within the BFF host. Embedded APIs are implemented with the familiar ASP.NET abstractions of API controllers or Minimal API endpoints.
 
-There are two styles of local APIs:
+There are two styles of Embedded APIs:
 
-- Self-contained Local APIs
-- Local APIs that Make Requests using Managed Access Tokens
+- Self-contained Embedded APIs
+- Embedded APIs that Make Requests using Managed Access Tokens
 
-#### Self-Contained Local APIs
+#### Self-Contained Embedded APIs
 
 These APIs reside within the BFF and don't make HTTP requests to other APIs. They access data controlled by the BFF itself, which can simplify the architecture of the system by reducing the number of APIs that must be deployed and managed. They are suitable for scenarios where the BFF is the sole consumer of the data. If you require data accessibility from other applications or services, this approach is probably not suitable.
 
-#### Local APIs That Make Requests Using Managed Access Tokens
+#### Embedded APIs That Make Requests Using Managed Access Tokens
 
-Alternatively, you can make the data available as a service and make HTTP requests to that service from your BFF's local endpoints. The benefits of this style of Local Endpoint include:
+Alternatively, you can make the data available as a service and make HTTP requests to that service from your BFF's Embedded endpoints. The benefits of this style of Embedded Endpoint include:
 
 - Your frontend's network access can be simplified into an aggregated call for the specific data that it needs, which reduces the amount of data that must be sent to the client.
 - Your BFF endpoint can expose a subset of your remote APIs so that they are called in a more controlled manner than if the BFF proxied all requests to the endpoint.
 - Your BFF endpoint can include business logic to call the appropriate endpoints, which simplifies your front end code.
 
-Your local endpoints can leverage services like the HTTP client factory and Duende.BFF [token management](/bff/fundamentals/tokens) to make the outgoing calls.
+Your Embedded endpoints can leverage services like the HTTP client factory and Duende.BFF [token management](/bff/fundamentals/tokens) to make the outgoing calls.
 
-The following is a simplified example showing how local endpoints can get managed access tokens and use them to make requests to remote APIs.
+The following is a simplified example showing how Embedded endpoints can get managed access tokens and use them to make requests to remote APIs.
 
 ```csharp
 // MyApiController.cs
@@ -66,11 +66,11 @@ public class MyApiController : ControllerBase
 }
 ```
 
-The example above is simplified to demonstrate the way that you might obtain a token. Real local endpoints will typically enforce constraints on the way the API is called, aggregate multiple calls, or perform other business logic. Local endpoints that merely forward requests from the frontend to the remote API may not be needed at all. Instead, you could proxy the requests through the BFF using either the [simple http forwarder](/bff/fundamentals/apis/remote/) or [YARP](/bff/fundamentals/apis/yarp/).
+The example above is simplified to demonstrate the way that you might obtain a token. Real Embedded endpoints will typically enforce constraints on the way the API is called, aggregate multiple calls, or perform other business logic. Embedded endpoints that merely forward requests from the frontend to the remote API may not be needed at all. Instead, you could proxy the requests through the BFF using either the [simple http forwarder](/bff/fundamentals/apis/remote/) or [YARP](/bff/fundamentals/apis/yarp/).
 
-## Securing Local API Endpoints
+## Securing Embedded API Endpoints
 
-Regardless of the style of data access used by a local API, it must be protected against threats such as [CSRF (Cross-Site Request Forgery)](https://developer.mozilla.org/en-US/docs/Glossary/CSRF) attacks. To defend against such attacks and ensure that only the frontend can access these endpoints, we recommend implementing two layers of protection.
+Regardless of the style of data access used by a Embedded API, it must be protected against threats such as [CSRF (Cross-Site Request Forgery)](https://developer.mozilla.org/en-US/docs/Glossary/CSRF) attacks. To defend against such attacks and ensure that only the frontend can access these endpoints, we recommend implementing two layers of protection.
 
 #### SameSite Cookies
 
@@ -221,3 +221,7 @@ MVC controllers and actions can use the `BffApiSkipAntiforgeryAttribute` (which
 public class SampleApiController : ControllerBase
 { /* ... */ }
 ```
+
+:::note
+It's also possible to disable anti-forgery protection using _BffOptions.DisableAntiForgeryCheck()_
+:::

…ent/docs/bff/fundamentals/apis/remote.md …nt/docs/bff/fundamentals/apis/remote.mdxsrc/content/docs/bff/fundamentals/apis/remote.md renamed to src/content/docs/bff/fundamentals/apis/remote.mdx src/content/docs/bff/fundamentals/apis/remote.md renamed to src/content/docs/bff/fundamentals/apis/remote.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Remote APIs"
+title: "Proxying to Remote APIs"
 description: Learn how to configure and secure remote API access through BFF using HTTP forwarding and token management.
 sidebar:
   order: 20
@@ -10,19 +10,26 @@ redirect_from:
   - /identityserver/v6/bff/apis/remote/
   - /identityserver/v7/bff/apis/remote/
 ---
+import { Badge } from "@astrojs/starlight/components";
+import { Code } from "@astrojs/starlight/components";
+import { Tabs, TabItem } from "@astrojs/starlight/components";
 
 A _Remote API_ is an API that is deployed separately from the BFF host. Remote APIs use access tokens to authenticate and authorize requests, but the frontend does not possess an access token to make requests to remote APIs directly. Instead, all access to remote APIs is proxied through the BFF, which authenticates the frontend using its authentication cookie, gets the appropriate access token, and forwards the request to the Remote API with the token attached.
 
 There are two different ways to set up Remote API proxying in Duende.BFF. This page describes the built-in simple HTTP forwarder. Alternatively, you can integrate Duende.BFF with Microsoft's [YARP](/bff/fundamentals/apis/yarp) reverse proxy, which allows for more complex reverse proxy features provided by YARP combined with the security and identity features of Duende.BFF.
 
-## Simple HTTP forwarder
+## Direct HTTP forwarding
 
-Duende.BFF's simple HTTP forwarder maps routes in the BFF to a remote API surface. It uses [Microsoft YARP](https://github.com/microsoft/reverse-proxy) internally, but is much simpler to configure than YARP. The intent is to provide a developer-centric and simplified way to proxy requests from the BFF to remote APIs when more complex reverse proxy features are not needed.
+Duende.BFF's direct HTTP forwarder maps routes in the BFF to a remote API surface. It uses [Microsoft YARP](https://github.com/microsoft/reverse-proxy) internally, but is much simpler to configure than YARP. The intent is to provide a developer-centric and simplified way to proxy requests from the BFF to remote APIs when more complex reverse proxy features are not needed.
 
 These routes receive automatic anti-forgery protection and integrate with automatic token management.
 
 To enable this feature, add a reference to the *Duende.BFF.Yarp* NuGet package, add the remote APIs service to the service provider, and then add the remote endpoint mappings.
 
+:::note
+The BFF multi-frontend feature has built-in support for direct forwarding. 
+:::
+
 #### Add Remote API Service to Service Provider
 
 To use the HTTP forwarder, register it in the service provider:
@@ -41,11 +48,24 @@ Use the `MapRemoteBffApiEndpoint` extension method to describe how to map reques
 
 The `MapRemoteBffApiEndpoint` extension method maps a path and all sub-paths below it. The intent is to allow easy mapping of groups of URLs. For example, you can set up mappings for the `/users`, `/users/{userId}`, `/users/{userId}/books`, and `/users/{userId}/books/{bookId}` endpoints without having to explicitly include all of them:
 
+{/* prettier-ignore */}
+<Tabs syncKey="bffVersion">
+  {/* prettier-ignore */}
+  <TabItem label="V4">
 ```csharp
 // Program.cs
 app.MapRemoteBffApiEndpoint("/api/users", new Uri("https://remoteHost/users"))
     .WithAccessToken(RequiredTokenType.User);
 ```
+  </TabItem>
+  <TabItem label="V3">
+```csharp
+// Program.cs
+app.MapRemoteBffApiEndpoint("/api/users", new Uri("https://remoteHost/users"))
+    .WithAccessToken(TokenType.User);
+```  
+  </TabItem>
+</Tabs>
 
 :::note
 This example opens up the complete */users* API namespace to the frontend, and thus, to the outside world. While it is convenient to register API paths this way, consider if you need to be more specific hen designing the forwarding paths to prevent accidentally exposing unintended endpoints.

src/content/docs/bff/fundamentals/blazor/_meta.yml

@@ -1,2 +1,3 @@
 label: "Blazor"
-collapsed: true
+collapsed: true
+order: 140

src/content/docs/bff/fundamentals/blazor/rendering-modes.md

@@ -25,7 +25,7 @@ It's important to understand that, if you use a rendering mode that uses WebAsse
 
 If you have a component that's rendered both on the server AND on the client, then you effectively need to make sure that all the services it requires are available both on the server AND on the client. 
 
-## Fetching Data From Local APIs
+## Fetching Data From Embedded APIs
 
 If your BFF application can directly access data (for example from a database), then you have to decide where this information is rendered. 
 
@@ -35,11 +35,11 @@ For web assembly rendering, you'll need to make the data available via a web ser
 
 When using auto-rendering mode, you'll need to make sure that the component get's a different 'data access' component for server rendering vs client rendering. Consider the following diagram:
 
-![local APIs](../../images/bff_blazor_local_api.svg)
+![Embedded APIs](../../images/bff_blazor_local_api.svg)
 
 In this diagram, you'll see the example **IDataAccessor** that has two implementations. One that accesses the data via an HTTP client (for use in WASM) and one that directly accesses the data. 
 
-The data is also exposed (and secured by the BFF) via a local api. 
+The data is also exposed (and secured by the BFF) via an embedded api. 
 
 Below is an example of registering an abstraction 
 
@@ -68,7 +68,7 @@ internal class ServerWeatherClient() : IDataAccessor
 ```csharp
 // setup on the client
 
-// Register a http client that can access the data via a local api. 
+// Register a http client that can access the data via an embedded api. 
 builder.Services.AddLocalApiHttpClient<DataAccessHttpClient>();
 
 // Register an adapter that would abstract between the data accessor and the http client. 

src/content/docs/bff/fundamentals/index.md

@@ -0,0 +1,8 @@
+---
+title: Overview
+sidebar:
+  order: 0
+  label: Overview
+description: "Overview of the BFF fundamentals"
+date: 2024-07-21T08:22:12+02:00
+---

src/content/docs/bff/fundamentals/multi-frontend/_meta.yml

@@ -0,0 +1,3 @@
+label: "Multiple frontends"
+collapsed: true
+order: 120