Merge pull request #757 from DuendeSoftware/bffv4

BFF v4 documentation spike

Author: maartenba

.idea/codeStyles/Project.xml

@@ -0,0 +1 @@
+*.mdx

.idea/prettier.xml

@@ -0,0 +1,65 @@
+---
+title: "Multi-frontend support"
+description: Overview on what BFF multi-frontend support is, how it works and why you would use it. 
+date: 2024-06-11T08:22:12+02:00
+sidebar:
+  label: "Multiple Frontends"
+  order: 5
+  badge:
+    text: v4
+    variant: tip
+---
+
+BFF V4.0 introduces the capability to support multiple BFF Frontends in a single host. This helps to simplify your application landscape by consolidating multiple physical BFF Hosts into a single deployable unit. 
+
+A single BFF setup consists of:
+1. A browser based application, typically built using technology like React, Angular or VueJS. This is typically deployed to a Content Delivery Network (CDN). 
+2. A BFF host, that will take care of the OpenID Connect login flows. 
+3. An API surface, exposed and protected by the BFF. 
+
+With the BFF Multi-frontend support, you can logically host multiple of these BFF Setups in a single host. The concept of a single frontend (with OpenID Connect configuration, an API surface and a browser based app) is now codified inside the BFF. By using a flexible frontend selection mechanism (using Origins or Paths to distinguish), it's possible to create very flexible setups. 
+
+The BFF dynamically configures the aspnet core authentication pipeline according to recommended practices. For example, when doing Origin based routing, it will configure the cookies using the most secure settings and with the prefix [`__Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie). 
+
+Frontends can be added or removed dynamically from the system, without having to restart the system. You can do this via configuration (for example by modifying a configuration file) or programmatically. 
+
+:::note
+The Duende BFF V4 library doesn't ship with an abstraction to store or read frontends from a database. It's possible to implement this by creating your own store (based on your requirements), then modify the `FrontendCollection` at run-time. 
+:::
+
+## A Typical Example
+
+Consider an enterprise that hosts multiple browser based applications. Each of these applications is developed by a separate team and as such, has it's own deployment schedule. 
+
+There are some internal-facing applications that are exclusively used by internal employees. These internal employees are all present in Microsoft Entra ID, so these internal-facing applications should directly authenticate against Microsoft Entra ID. These applications also use several internal APIs, that due to the sensitivity, should not be accessible by external users. However, they also use some of the more common APIs. These apps are only accessible via an internal DNS name, such as `https://app1.internal.example.com`. 
+
+There are also several public facing applications, that are used directly by customers. These users should be able to log in using their own identity, via providers like Google, Twitter, or others. This authentication process is handled by Duende IdentityServer. There is constant development ongoing on these applications and it's not uncommon for new applications to be introduced. There should be single sign-on across all these public facing applications. They are all available on the same domain name, but use path based routing to distinguish themselves, such as `https://app.example.com/app1`
+
+There is also a partner portal. This partner portal can only be accessed by employees of the partners. Each partner should be able to bring their own identity provider. This is implemented using the [Dynamic Providers](/identityserver/ui/login/dynamicproviders/) feature of Duende IdentityServer. 
+
+This setup, with multiple frontends, each having different authentication requirements and different API surfaces, is now supported by the BFF. 
+
+Each frontend can either rely on the global configuration or override (parts of) this configuration, such as the identity provider or the Client ID and Client Secret to use. 
+
+It's also possible to dynamically add or remove frontends, without restarting the BFF host. 
+
+## Internals
+
+BFF V4 still allows you to manually configure the ASP.NET Core authentication options, by calling `.AddAuthentication().AddOpenIdConnect().AddCookies()`. However, if you wish to use the multi-frontend features, then this setup needs to become dynamic. 
+
+To achieve this, the BFF automatically configures the ASP.NET Core pipeline:
+
+![BFF Multi-Frontend Pipeline](../images/bff_multi_frontend_pipeline.svg)
+
+1. `FrontendSelectionMiddleware` - This middleware performs the frontend selection by seeing which frontend's selection criteria best matches the incoming request route. It's possible to mix both path based routing origin based routing, so the most specific will be selected. 
+2. `PathMappingMiddleware` - If you use path mapping, in the selected frontend, then it will automatically map the frontend's path so none of the subsequent middlewares know (or need to care) about this fact. 
+3. `OpenIdCallbackMiddleware` - To dynamically perform the OpenID Connect authentication without explicitly adding each frontend as a scheme, we inject a middleware that will handle the OpenID Connect callbacks. This only kicks in for dynamic frontends.
+4. Your own applications logic is executed in this part of the pipeline. For example, calling `.UseAuthentication(), .UseRequestLogging()`, etc. 
+
+After your application's logic is executed, there are two middlewares registered as fallback routes:
+
+5. `MapRemoteRoutesMiddleware` - This will handle any configured remote routes. Note, it will not handle plain YARP calls, only routes that are specifically added to a frontend.
+    
+6. `ProxyIndexMiddleware` - If configured, this proxy the `index.html` to start the browser based app.  
+
+

.prettierignore

@@ -111,9 +111,9 @@ Implementations of the *IAccessTokenRetriever* can be added to endpoints when th
 
 ```cs
 app.MapRemoteBffApiEndpoint(
-        "/API/impersonation", 
-        "https://API.example.com/endpoint/requiring/impersonation"
-    ).RequireAccessToken(TokenType.User)
+        "/api/impersonation", 
+        "https://api.example.com/endpoint/requiring/impersonation"
+    ).WithAccessToken(RequiredTokenType.User)
      .WithAccessTokenRetriever<ImpersonationAccessTokenRetriever>();
 ```
 

src/content/docs/bff/architecture/multi-frontend.md

@@ -43,15 +43,15 @@ The `MapRemoteBffApiEndpoint` extension method maps a path and all sub-paths bel
 
 ```csharp
 // Program.cs
-app.MapRemoteBffApiEndpoint("/API/users", "https://remoteHost/users")
-    .RequireAccessToken(TokenType.User);
+app.MapRemoteBffApiEndpoint("/api/users", "https://remoteHost/users")
+    .WithAccessToken(RequiredTokenType.User);
 ```
 
 :::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.
 :::
 
-The `RequireAccessToken` method can be added to [specify token requirements](#access-token-requirements) for the remote API. The BFF will automatically forward the correct access token to the remote API, which will be scoped to the client application, the user, or either.
+The `WithAccessToken` method can be added to [specify token requirements](#access-token-requirements) for the remote API. The BFF will automatically forward the correct access token to the remote API, which will be scoped to the client application, the user, or either.
 
 ## Securing Remote APIs
 
@@ -81,11 +81,19 @@ The value of the header is not important, but its presence, combined with the co
 
 #### Require authorization
 
-The `MapRemoteBffApiEndpoint` method returns the appropriate type to integrate with the ASP.NET Core authorization system. You can attach authorization policies to remote endpoints using `RequireAuthorization` extension method, just as you would for a standard ASP.NET core endpoint created with `MapGet`. The authorization middleware will then enforce that policy before forwarding requests on that route to the remote endpoint.
+The `MapRemoteBffApiEndpoint` method returns the appropriate type to integrate with the ASP.NET Core authorization system. You can attach authorization policies to remote endpoints using the `WithAccessToken` extension method, just as you would for a standard ASP.NET core endpoint created with `MapGet`. The authorization middleware will then enforce that policy before forwarding requests on that route to the remote endpoint.
+
+:::note
+In Duende.BFF version 3, use the `MapRemoteBffApiEndpoint` method with the `RequireAuthorization` extension method to attach authorization policies.
+:::
 
 #### Access token requirements
 
-Remote APIs sometimes allow anonymous access, but usually require an access token, and the type of access token (user or client) will vary as well. You can specify access token requirements via the `RequireAccessToken` extension method. Its `TokenType` parameter has three options:
+Remote APIs sometimes allow anonymous access, but usually require an access token, and the type of access token (user or client) will vary as well. You can specify access token requirements via the `WithAccessToken` extension method. Its `RequiredTokenType` parameter has three options:
+
+* `None`
+
+    No token is required.
 
 * `User`
 
@@ -99,7 +107,9 @@ Remote APIs sometimes allow anonymous access, but usually require an access toke
 
     Either a valid user access token or a valid client access token (as fallback) is required and will be forwarded to the remote API.
 
-You can also use the `WithOptionalUserAccessToken` extension method to specify that the API should be called with a user access token if one is available and anonymously if not.
+* `UserOrNone`
+
+    A valid user access token will be forwarded to the remote API when logged in. No access token will be sent when not logged in, and no OIDC flow is challenged to get an access token.
 
 :::note
 These settings only specify the logic that is applied before the API call gets proxied. The remote APIs you are calling should always specify their own authorization and token requirements.

src/content/docs/bff/extensibility/tokens.md

@@ -66,7 +66,7 @@ builder.Services.AddBff()
     .AddBlazorServer();
 
 
-// ... <snip>..
+// ... <snip> ...
 
 // Add the BFF middleware which performs anti forgery protection
 app.UseBff();
@@ -78,17 +78,15 @@ app.UseAntiforgery();
 // This has to be added after 'UseAuthorization()'
 app.MapBffManagementEndpoints();
 
-// .. <snip>
+// ... <snip> ...
 ```
 
 ```csharp
-
 var builder = WebAssemblyHostBuilder.CreateDefault(args);
 
 builder.Services
     .AddBffBlazorClient() // Provides auth state provider that polls the /bff/user endpoint
     .AddCascadingAuthenticationState();
 
 builder.Services.AddLocalApiHttpClient<WeatherHttpClient>();
-
 ```

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

@@ -19,7 +19,7 @@ You set the options at startup time:
 ```cs
 builder.Services.AddBff(options =>
 {
-    // configure options here..
+    // configure options here...
 })
 ```
 
@@ -154,7 +154,7 @@ In WASM, you configure the **BffBlazorClientOptions** using the **AddBffBlazorCl
 ```csharp
 builder.Services.AddBffBlazorClient(opt =>
 {
-    // configure options here..
+    // configure options here...
 })
 ```
 

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

@@ -69,10 +69,11 @@ Just enable session cleanup:
 ```csharp
 var cn = _configuration.GetConnectionString("db");
 
-builder.Services.AddBff(options => {
+builder.Services.AddBff(options =>
+    {
         options.EnableSessionCleanup = true;
     })
-    .AddEntityFrameworkServerSideSessions(options=> 
+    .AddEntityFrameworkServerSideSessions(options => 
     {
         options.UseSqlServer(cn);        
     });

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

@@ -0,0 +1,3 @@
+label: "Getting Started"
+collapsed: true
+order: 1