BFF v4 endpoints

Author: Erwinvandervalk

src/content/docs/bff/extensibility/http-forwarder.md

@@ -17,7 +17,7 @@ You can customize the HTTP forwarder behavior in two ways
 * provide a customized HTTP client for outgoing calls
 * provide custom request/response transformation
 
-### Custom HTTP clients
+## Custom HTTP clients
 By default, Duende.BFF will create and cache an HTTP client per configured route or local path.
 
 This invoker is set up like this:
@@ -32,64 +32,116 @@ var client = new HttpMessageInvoker(new SocketsHttpHandler
 });
 ```
 
-If you want to customize the HTTP client for specific paths, you can either implement the *IHttpMessageInvokerFactory* interface or derive from the *DefaultHttpMessageInvokerFactory*, e.g.:
+If you want to customize the HTTP client you can either implement the *IForwarderHttpClientFactory* interface, e.g.:
 
 ```cs
-public class MyInvokerFactory : DefaultHttpMessageInvokerFactory
+public class MyInvokerFactory : IForwarderHttpClientFactory
 {
-    public override HttpMessageInvoker CreateClient(string localPath)
+    public public HttpMessageInvoker CreateClient(ForwarderHttpClientContext context)
     {
-        if (localPath == "/foo")
+        return Clients.GetOrAdd(localPath, (key) =>
         {
-            return Clients.GetOrAdd(localPath, (key) =>
+            return new HttpMessageInvoker(new SocketsHttpHandler
             {
-                return new HttpMessageInvoker(new SocketsHttpHandler
-                {
-                    // this API needs a proxy
-                    UseProxy = true,
-                    Proxy = new WebProxy("https://myproxy"),
-                    
-                    AllowAutoRedirect = false,
-                    AutomaticDecompression = DecompressionMethods.None,
-                    UseCookies = false
-                });
+                // this API needs a proxy
+                UseProxy = true,
+                Proxy = new WebProxy("https://myproxy"),
+                
+                AllowAutoRedirect = false,
+                AutomaticDecompression = DecompressionMethods.None,
+                UseCookies = false
             });
-        }
-        
-        return base.CreateClient(localPath);
+        });
     }
 }
 ```
 
 ...and override our registration:
 
 ```cs
-services.AddSingleton<IHttpMessageInvokerFactory, MyInvokerFactory>();
+services.AddSingleton<IForwarderHttpClientFactory, MyInvokerFactory>();
 ```
 
-### Custom Transformations
-In the standard configuration, BFF uses the YARP default behavior for forwarding HTTP requests. In addition, we
+## Custom transformations when using Direct Forwarding
 
-* remove the sensitive session cookie
-* add the current access token
+The method MapRemoteBffApiEndpoint uses default transformations that:
+* removes the cookie header from the forwarded request
+* removes local path from from the forwarded request
+* Adds the access token to the original request
 
-If you want to modify this behavior you can either implement *IHttpTransformerFactory* from scratch: 
+If you wish to change or extend this behavior, you can do this for a single mapped endpoint
+or for all mapped api endpoints. 
 
-```cs
-public interface IHttpTransformerFactory
+### Changing the transformer for a single mapped endpoint
+
+This code block shows an example how you can extend the default transformers with an additional custom
+transform. 
+
+```csharp
+
+app.MapRemoteBffApiEndpoint("/local", new Uri("https://target/"), context => {
+
+    // If you want to extend the existing behavior, then you must call the default builder:
+    DefaultBffYarpTransformerBuilders.DirectProxyWithAccessToken("/local", context);
+
+    //You can also add custom transformers, such as this one that adds an additional header
+    context.AddRequestHeader("custom", "with value");
+
+});
+
+```
+
+The default transformbuilder performs these transforms:
+
+```csharp
+context.AddRequestHeaderRemove("Cookie");
+context.AddPathRemovePrefix(localPath);
+context.AddBffAccessToken(localPath);
+```
+
+For more information, also see the [yarp documentation on transforms](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/yarp/transforms?view=aspnetcore-9.0)
+
+### Changing the default transformer. 
+
+You can change the default transformer builder delegate by registering one in the services collection:
+
+```csharp
+BffYarpTransformBuilder builder = (localPath, context) => {
+
+    // If you want to extend the existing behavior, then you must call the default builder:
+    DefaultBffYarpTransformerBuilders.DirectProxyWithAccessToken(localpath, context);
+
+   //You can also add custom transformers, such as this one that adds an additional header
+    context.AddResponseHeader("added-by-custom-default-transform", "some-value");
+
+};
+
+services.AddSingleton<BffYarpTransformBuilder>(builder);
+```
+
+## Changing the Forwarder Request Config
+
+You an also modify the forwarder request config, either globally or per mapped path.
+This can be useful if you want to tweak things like activity timeouts. 
+
+```csharp
+
+// Register a forwarder config globally. 
+services.AddSingleton(new ForwarderRequestConfig()
 {
-    /// <summary>
-    /// Creates a HTTP transformer based on the local path
-    /// </summary>
-    /// <param name="localPath">Local path the remote API is mapped to</param>
-    /// <param name="accessToken">The access token to attach to the request (if present)</param>
-    /// <returns></returns>
-    HttpTransformer CreateTransformer(string localPath, string accessToken = null);
-}
+    ActivityTimeout = TimeSpan.FromMilliseconds(100)
+});
+
+// Or modify one on a per mapped route basis:
+app.MapRemoteBffApiEndpoint("/local", new Uri("https://target/"),
+    requestConfig: new ForwarderRequestConfig()
+    {
+        // 100 ms timeout, which is not too short that the normal process might fail,
+        // but not too long that the test will take forever
+        ActivityTimeout = TimeSpan.FromMilliseconds(100)
+    });
+
 ```
 
-...or derive from the *DefaultHttpTransformerFactory*.
 
-:::note
-The transformations are based on YARP's transform library and are extensible. See [here](https://microsoft.github.io/reverse-proxy/articles/transforms.html) for a full list of built-in transforms.
-:::
+

src/content/docs/bff/extensibility/management/back-channel-logout.md

@@ -12,68 +12,23 @@ redirect_from:
   - /identityserver/v7/bff/extensibility/management/back-channel-logout/
 ---
 
-The back-channel logout endpoint has several extensibility points organized into two interfaces and their default implementations. The *IBackChannelLogoutService* is the top level abstraction that processes requests to the endpoint. This service can be used to add custom request processing logic or to change how it validates incoming requests. When the back-channel logout endpoint receives a valid request, it revokes sessions using the *ISessionRevocationService*. 
+The back-channel logout endpoint has several extensibility points organized into two interfaces. The *IBackChannelLogoutEndpoint* is the top level abstraction that processes requests to the endpoint. This service can be used to add custom request processing logic or to change how it validates incoming requests. When the back-channel logout endpoint receives a valid request, it revokes sessions using the *ISessionRevocationService*. 
 
 ## Request Processing
-You can add custom logic to the endpoint by implementing the *IBackChannelLogoutService* or by extending its default implementation (*Duende.Bff.DefaultBackChannelLogoutService*). In most cases, extending the default implementation is preferred, as it has several virtual methods that can be overridden to customize particular aspects of how the request is processed.
+You can add custom logic to the endpoint by implementing the *IBackChannelLogoutEndpoint* .
 
 *ProcessRequestAsync* is the top level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
 
 ```csharp
-public class CustomizedBackChannelLogoutService : DefaultBackChannelLogoutService
+public class CustomizedBackChannelLogoutService : IBackChannelLogoutEndpoint
 {
-    public override Task ProcessRequestAsync(HttpContext context)
+    public override Task ProcessRequestAsync(HttpContext context, CancellationToken ct)
     {
         // Custom logic here
-
-        return base.ProcessRequestAsync(context);
-    }
-}
-```
-
-## Validation
-
-Validation of the incoming request can be customized by overriding one of several virtual methods in the *DefaultBackChannelLogoutService*. *GetTokenValidationParameters* allows you to specify the *[TokenValidationParameters](https://learn.microsoft.com/en-us/dotnet/API/microsoft.identitymodel.tokens.tokenvalidationparameters?view=azure-dotnet)* used to validate the incoming logout token. The default implementation creates token validation parameters based on the authentication scheme's configuration. Your override could begin by calling the base method and then make changes to those parameters or completely customize how token validation parameters are created. For example:
-
-```csharp
-public class CustomizedBackChannelLogoutService : DefaultBackChannelLogoutService
-{
-    protected override async Task<TokenValidationParameters> GetTokenValidationParameters()
-    {
-        var tokenValidationParams = await base.GetTokenValidationParameters();
-
-        // Set custom parameters here
-        // For example, make clock skew more permissive than it is by default:
-        tokenValidationParams.ClockSkew = TimeSpan.FromMinutes(15);
-
-        return tokenValidationParams;
     }
 }
 ```
-If you need more control over the validation of the logout token, you can override *ValidateJwt*. The default implementation of *ValidateJwt* validates the token and produces a *ClaimsIdentity* using a *[JsonWebTokenHandler](https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/wiki/ValidatingTokens)* and the token validation parameters returned from *GetTokenValidationParameters*. Your override could call the base method and then manipulate this *ClaimsIdentity* or add a completely custom method for producing the *ClaimsIdentity* from the logout token.
-
-*ValidateLogoutTokenAsync* is the coarsest-grained validation method. It is responsible for validating the incoming logout token and determining if logout should proceed, based on claims in the token. It returns a *ClaimsIdentity* if logout should proceed or null if it should not. Your override could prevent logout in certain circumstances by returning null. For example:
-
-```csharp
-public class CustomizedBackChannelLogoutService : DefaultBackChannelLogoutService
-{
-    protected override async Task<ClaimsIdentity?> ValidateLogoutTokenAsync(string logoutToken)
-    {
-        var identity = await base.ValidateLogoutTokenAsync(logoutToken);
 
-        // Perform custom logic here
-        // For example, prevent logout based on certain conditions
-        if(identity?.FindFirst("sub")?.Value == "12345") 
-        {
-            return null;
-        } 
-        else 
-        {
-            return identity;
-        }
-    }
-}
-```
 
 ## Session Revocation
 The back-channel logout service will call the registered session revocation service to revoke the user session when it receives a valid logout token. To customize the revocation process, implement the *ISessionRevocationService*. 

src/content/docs/bff/extensibility/management/diagnostics.md

@@ -12,18 +12,17 @@ redirect_from:
   - /identityserver/v7/bff/extensibility/management/diagnostics/
 ---
 
-The BFF diagnostics endpoint can be customized by implementing the *IDiagnosticsService* or by extending *DefaultDiagnosticsService*, its default implementation.
+The BFF diagnostics endpoint can be customized by implementing the *IDiagnosticsEndpoint*.
 
 ## Request Processing
 *ProcessRequestAsync* is the top level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
 
 For example, you could take whatever actions you need before normal processing of the request like this:
 
 ```csharp
-public override Task ProcessRequestAsync(HttpContext context)
+public Task ProcessRequestAsync(HttpContext context, CancellationToken ct)
 {
     // Custom logic here
 
-    return base.ProcessRequestAsync(context);
 }
 ```

src/content/docs/bff/extensibility/management/index.md

@@ -27,12 +27,12 @@ builder.Services.AddTransient<IDiagnosticsService, DefaultDiagnosticsService>();
 
 You can add your own implementation by overriding the default after calling *AddBff()*.
 
-The management endpoint services all inherit from the *IBffEndpointService*, which provides a general-purpose mechanism to add custom logic to the endpoints. 
+The management endpoint services all inherit from the *IBffEndpointEndpoint*, which provides a general-purpose mechanism to add custom logic to the endpoints. 
 
 ```csharp
 public interface IBffEndpointService
 {
-    Task ProcessRequestAsync(HttpContext context);
+    Task ProcessRequestAsync(HttpContext context, CancellationToken ct);
 }
 ```
 

src/content/docs/bff/extensibility/management/login.md

@@ -12,15 +12,15 @@ redirect_from:
   - /identityserver/v7/bff/extensibility/management/login/
 ---
 
-The BFF login endpoint has extensibility points in two interfaces. The *ILoginService* is the top level abstraction that processes requests to the endpoint. This service can be used to add custom request processing logic. The *IReturnUrlValidator* ensures that the *returnUrl* parameter passed to the login endpoint is safe to use.
+The BFF login endpoint has extensibility points in two interfaces. The *ILoginEndpoint* is the top level abstraction that processes requests to the endpoint. This service can be used to add custom request processing logic. The *IReturnUrlValidator* ensures that the *returnUrl* parameter passed to the login endpoint is safe to use.
 
 ## Request Processing
 *ProcessRequestAsync* is the top level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
 
 For example, you could take whatever actions you need before normal processing of the request like this:
 
 ```csharp
-public override Task ProcessRequestAsync(HttpContext context)
+public Task ProcessRequestAsync(HttpContext context, CancellationToken ct)
 {
     // Custom logic here
 

src/content/docs/bff/extensibility/management/logout.md

@@ -12,15 +12,15 @@ redirect_from:
   - /identityserver/v7/bff/extensibility/management/logout/
 ---
 
-The BFF logout endpoint has extensibility points in two interfaces. The *ILogoutService* is the top level abstraction that processes requests to the endpoint. This service can be used to add custom request processing logic. The *IReturnUrlValidator* ensures that the *returnUrl* parameter passed to the logout endpoint is safe to use.
+The BFF logout endpoint has extensibility points in two interfaces. The *ILogoutEndpoint* is the top level abstraction that processes requests to the endpoint. This service can be used to add custom request processing logic. The *IReturnUrlValidator* ensures that the *returnUrl* parameter passed to the logout endpoint is safe to use.
 
 ## Request Processing
 *ProcessRequestAsync* is the top level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
 
 For example, you could take whatever actions you need before normal processing of the request like this:
 
 ```csharp
-public override Task ProcessRequestAsync(HttpContext context)
+public Task ProcessRequestAsync(HttpContext context, CancellationToken ct)
 {
     // Custom logic here
 

src/content/docs/bff/extensibility/management/silent-login-callback.md

@@ -12,15 +12,15 @@ redirect_from:
   - /identityserver/v7/bff/extensibility/management/silent-login-callback/
 ---
 
-The BFF silent login callback endpoint can be customized by implementing the *ISilentLoginCallbackService* or by extending *DefaultSilentLoginCallbackService*, its default implementation.
+The BFF silent login callback endpoint can be customized by implementing the *ISilentLoginCallbackEndpoint*.
 
 ## Request Processing
 *ProcessRequestAsync* is the top level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
 
 For example, you could take whatever actions you need before normal processing of the request like this:
 
 ```csharp
-public override Task ProcessRequestAsync(HttpContext context)
+public Task ProcessRequestAsync(HttpContext context, CancellationToken ct)
 {
     // Custom logic here
 

src/content/docs/bff/extensibility/management/silent-login.md

@@ -12,15 +12,15 @@ redirect_from:
   - /identityserver/v7/bff/extensibility/management/silent-login/
 ---
 
-The BFF silent login endpoint can be customized by implementing the *ISilentLoginService* or by extending *DefaultSilentLoginService*, its default implementation.
+The BFF silent login endpoint can be customized by implementing the *ISilentLoginEndpoint*.
 
 ## Request Processing
 *ProcessRequestAsync* is the top level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
 
 For example, you could take whatever actions you need before normal processing of the request like this:
 
 ```csharp
-public override Task ProcessRequestAsync(HttpContext context)
+public Task ProcessRequestAsync(HttpContext context, CancellationToken ct)
 {
     // Custom logic here