Merge branch 'main' into mb/standardize-editions

Author: maartenba

src/content/docs/accesstokenmanagement/advanced/client-assertions.mdx

@@ -44,7 +44,10 @@ public class ClientAssertionService(IOptionsSnapshot<ClientCredentialsClient> op
             var descriptor = new SecurityTokenDescriptor
             {
                 Issuer = options1.ClientId!.ToString(),
-                Audience = options1.TokenEndpoint!.ToString(),
+
+                // Set the audience to the url of identity server. Do not use the tokenurl to build the autority. 
+                Audience = "https://--url-to-authority-here--",
+
                 Expires = DateTime.UtcNow.AddMinutes(1),
                 SigningCredentials = GetSigningCredential(),
 
@@ -105,7 +108,9 @@ public class ClientAssertionService(IOptionsSnapshot<ClientCredentialsClient> op
             var descriptor = new SecurityTokenDescriptor
             {
                 Issuer = options1.ClientId,
-                Audience = options1.TokenEndpoint,
+
+                // Set the audience to the url of identity server. Do not use the tokenurl to build the autority. 
+                Audience = "https://--url-to-authority-here--",
                 Expires = DateTime.UtcNow.AddMinutes(1),
                 SigningCredentials = GetSigningCredential(),
 
@@ -142,3 +147,11 @@ public class ClientAssertionService(IOptionsSnapshot<ClientCredentialsClient> op
 }`}/>
     </TabItem>
 </Tabs>
+
+
+:::note
+You need to explicitly set the `Audience` to the authorization server's issuer URL (usually the URL of identity server). 
+
+Don't set the audience to the `TokenUrl`. Setting the `Audience` value to the token endpoint leaves 
+you vulnerable to these vulnerabilities: (CVE-2025-27370/CVE-2025-27371).
+:::

src/content/docs/accesstokenmanagement/advanced/extensibility.md

@@ -87,12 +87,13 @@ services.AddHttpClient<YourTypedHttpClient>()
     .AddDefaultAccessTokenResiliency()
     .AddHttpMessageHandler(provider =>
     {
-        var yourCustomTokenRetriever = new CustomTokenRetriever();
+        var yourCustomTokenRetriever = new CustomTokenRetriever(...);
 
         var logger = provider.GetRequiredService<ILogger<AccessTokenRequestHandler>>();
         var dPoPProofService = provider.GetRequiredService<IDPoPProofService>();
         var dPoPNonceStore = provider.GetRequiredService<IDPoPNonceStore>();
-        var accessTokenHandler = new AccessTokenRequestHandler(
+
+        return new AccessTokenRequestHandler(
             tokenRetriever: yourCustomTokenRetriever,
             dPoPNonceStore: dPoPNonceStore,
             dPoPProofService: dPoPProofService,

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

@@ -10,36 +10,59 @@ sidebar:
     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. 
+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. 
+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 Hosts 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). 
+The BFF dynamically configures the aspnet core authentication pipeline according to recommended practices. For example, 
+when doing Host 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. 
+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. 
+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 its own deployment schedule. 
+Consider an enterprise that hosts multiple browser based applications. Each of these applications is developed by a 
+separate team and as such, has its 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 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 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.md) feature of Duende IdentityServer. 
+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.md) feature of
+Duende IdentityServer. 
 
-This setup, with multiple frontends, each having different authentication requirements and different API surfaces, is now supported by the BFF. 
+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. 
+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. 
 
@@ -51,7 +74,7 @@ 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. 
+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 and host 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. 

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

@@ -0,0 +1,76 @@
+---
+title: "BFF Back-Channel Logout Endpoint Extensibility"
+date: 2022-12-29T10:22:12+02:00
+sidebar:
+  label: "Back-Channel Logout"
+  order: 60
+redirect_from:
+  - /bff/v2/extensibility/management/back-channel-logout/
+  - /bff/v3/extensibility/management/back-channel-logout/
+  - /identityserver/v5/bff/extensibility/management/back-channel-logout/
+  - /identityserver/v6/bff/extensibility/management/back-channel-logout/
+  - /identityserver/v7/bff/extensibility/management/back-channel-logout/
+---
+
+import { Aside, Code } from "@astrojs/starlight/components";
+import { Tabs, TabItem } from "@astrojs/starlight/components";
+
+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`.
+
+<Aside type="caution">
+    In BFF V3, the `IBackchannelLogoutEndpoint` interface is called `IBackchannelLogoutService` instead.
+</Aside>
+
+## Request Processing
+
+<Tabs syncKey="bffVersion">
+    <TabItem label="V4">
+        You can customize the behavior of the back-channel logout endpoint by implementing the `ProcessRequestAsync` method of the
+        `IBackchannelLogoutEndpoint` interface. The [default implementation][1] can serve as a starting point for your own implementation.
+
+        If you want to extend the default behavior of the back-channel logout endpoint, you can instead add a custom endpoint and
+        call the original endpoint implementation:
+
+        <Code
+            lang="csharp"
+            title="Program.cs"
+            code={`
+var bffOptions = app.Services.GetRequiredService<IOptions<BffOptions>>().Value;
+
+app.MapGet(bffOptions.BackChannelLogoutPath, async (HttpContext context, CancellationToken ct) =>
+{
+    // Custom logic before calling the original endpoint implementation
+    var endpointProcessor = context.RequestServices.GetRequiredService<IBackchannelLogoutEndpoint>();
+    await endpointProcessor.ProcessRequestAsync(context, ct);
+    // Custom logic after calling the original endpoint implementation
+});
+`} />
+    </TabItem>
+    <TabItem label="V3">
+        `ProcessRequestAsync` is the top-level function called in the endpoint service `DefaultBackchannelLogoutService`,
+        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:
+
+        <Code
+            lang="csharp"
+            code={`
+public override Task ProcessRequestAsync(HttpContext context, CancellationToken ct)
+{
+    // Custom logic here
+
+    return base.ProcessRequestAsync(context);
+}
+`}/>
+    </TabItem>
+</Tabs>
+
+## 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`.
+
+[1]: https://github.com/DuendeSoftware/products/tree/releases/bff/4.0.x/bff/src/Bff/Endpoints/Internal/DefaultBackchannelLogoutEndpoint.cs

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

@@ -0,0 +1,69 @@
+---
+title: "BFF Diagnostics Endpoint Extensibility"
+date: 2022-12-29T10:22:12+02:00
+sidebar:
+  order: 70
+  label: "Diagnostics"
+redirect_from:
+  - /bff/v2/extensibility/management/diagnostics/
+  - /bff/v3/extensibility/management/diagnostics/
+  - /identityserver/v5/bff/extensibility/management/diagnostics/
+  - /identityserver/v6/bff/extensibility/management/diagnostics/
+  - /identityserver/v7/bff/extensibility/management/diagnostics/
+---
+
+import { Aside, Code } from "@astrojs/starlight/components";
+import { Tabs, TabItem } from "@astrojs/starlight/components";
+
+The BFF diagnostics endpoint can be customized by implementing the `IDiagnosticsEndpoint`.
+
+<Aside type="caution">
+    In BFF V3, the `IDiagnosticsEndpoint` interface is called `IDiagnosticsService` instead.
+</Aside>
+
+## Request Processing
+
+<Tabs syncKey="bffVersion">
+    <TabItem label="V4">
+        You can customize the behavior of the diagnostics endpoint by implementing the `ProcessRequestAsync` method of the
+        `IDiagnosticsEndpoint` interface. The [default implementation][1]
+        can serve as a starting point for your own implementation.
+
+        If you want to extend the default behavior of the diagnostics endpoint, you can instead add a custom endpoint and
+        call the original endpoint implementation:
+
+        <Code
+            lang="csharp"
+            title="Program.cs"
+            code={`
+var bffOptions = app.Services.GetRequiredService<IOptions<BffOptions>>().Value;
+
+app.MapGet(bffOptions.DiagnosticsPath, async (HttpContext context, CancellationToken ct) =>
+{
+    // Custom logic before calling the original endpoint implementation
+    var endpointProcessor = context.RequestServices.GetRequiredService<IDiagnosticsEndpoint>();
+    await endpointProcessor.ProcessRequestAsync(context, ct);
+    // Custom logic after calling the original endpoint implementation
+});
+`} />
+    </TabItem>
+    <TabItem label="V3">
+        `ProcessRequestAsync` is the top-level function called in the endpoint service `DefaultDiagnosticsService`,
+        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:
+
+        <Code
+            lang="csharp"
+            code={`
+public override Task ProcessRequestAsync(HttpContext context, CancellationToken ct)
+{
+    // Custom logic here
+
+    return base.ProcessRequestAsync(context);
+}
+`}/>
+    </TabItem>
+</Tabs>
+
+[1]: https://github.com/DuendeSoftware/products/tree/releases/bff/4.0.x/bff/src/Bff/Endpoints/Internal/DefaultDiagnosticsEndpoint.cs