wip

Author: Erwinvandervalk

src/content/docs/accesstokenmanagement/advanced/_meta.yml

@@ -1,3 +1,3 @@
 label: 'Advanced'
-order: 4
+order: 10
 collapsed: true

src/content/docs/accesstokenmanagement/index.mdx

@@ -16,6 +16,12 @@ The `Duende.AccessTokenManagement` library provides automatic access token manag
 - automatic access token lifetime management using a refresh token for API calls on behalf of the currently logged-in user (using the `Duende.AccessTokenManagement.OpenIdConnect` package)
 - revocation of access tokens
 
+:::note
+    Duende.AccessTokenManagement version 4 (currently in preview 2) brings significant improvements, but also several breaking
+    changes. Please see the [migration guide](/accesstokenmanagement/upgrading/atm-v3-to-v4/) and [release notes](https://github.com/DuendeSoftware/foss/releases/tag/atm-4.0.0-Preview.2).
+:::
+    
+
 ## Machine-to-machine token management
 
 To get started, install the NuGet Package:

src/content/docs/accesstokenmanagement/upgrading/_meta.yml

@@ -0,0 +1,3 @@
+label: 'Upgrading'
+order: 20
+collapsed: true

src/content/docs/accesstokenmanagement/upgrading/atm-v3-to-v4.mdx

@@ -0,0 +1,69 @@
+---
+title: "Duende AccessTokenManagement v3.x to v4.0"
+description: Guide for upgrading Duende BFF Security Framework from version 3.x to version 4.0, including migration steps for custom implementations and breaking changes.
+sidebar:
+  label: v3.x → v4.0
+  order: 100
+---
+
+## Changes
+### Moving Towards HybridCache Implementation and Away from Distributed Cache
+
+Microsoft has recently released HybridCache. While this is only released as a .NET 9 DLL, these assemblies work fine in .NET 8. So, while we still support .NET 8 with ATM 4.0, we are moving towards using HybridCache.
+
+HybridCache brings significant improvements for us. Because of the two-layered cache, we've found it significantly improves performance.  
+If you currently use a distributed cache, this should still work seamlessly.
+
+If you wish to encrypt access tokens, you can do so by implementing a custom serializer. Documentation on this will follow later.
+
+We have added support for using a custom HybridCache instance via keyed services.
+
+### Complete Internal Refactoring
+
+The library has undergone extensive internal changes—so much so that it can be considered a new implementation under the same conceptual umbrella. Despite this, the public API surface remains mostly compatible with earlier versions.
+
+* New extensibility model (see below).
+* All async methods now support cancellation tokens.
+* Renaming of certain classes and interfaces (see below).
+* Implementation logic is now internal.
+
+#### Reduced Public API Surface
+
+All internal implementation details are now marked as internal, reducing accidental coupling and clarifying the intended extension points. In V3, all classes were public and most public methods were marked as virtual. This meant you could override any class by inheriting from it and overriding a single method.
+
+While this was very convenient for our consumers, it made it very difficult for us to introduce changes to the library without making breaking changes.
+
+We still want to ensure our users' extensibility needs are met, but via more controlled mechanisms. If you find that you have an extensibility need that is not covered by the new model, please raise a discussion in our discussion board. If this is a scenario we want to support, we'll do our best to accommodate it.
+
+### Explicit Extension Model
+
+Instead of relying on implicit behaviors or inheritance, V4 introduces clearly defined extension points, making it easier to customize behavior without relying on internal details.
+
+### Composition Over Inheritance
+
+The `AccessTokenHandler` has been restructured to use composition rather than inheritance, simplifying the customization of token handling and increasing testability.
+
+If you wish to implement a custom access token handling process, for example to implement token exchange, you can now implement your own `AccessTokenRequestHandler.ITokenRetriever`.
+
+### Strongly Typed Configuration
+
+Configuration is now represented by strongly typed objects, improving validation, discoverability, and IDE support.
+
+This means that where before you could assign strings to the configuration system, you'll now have to explicitly parse the string values.
+
+For example:
+
+```csharp
+var scheme = Scheme.Parse("oidc");
+
+```
+
+### Renamed classes
+Several classes have been renamed, either to make their usage clearer or to drop the 'service' suffix, which only adds noise:
+
+AccessTokenHandler => AccessTokenRequestHandler
+ClientCredentialsTokenManagementService => IClientIClientCredentialsTokenManager
+IClientCredentialsTokenEndpointService => IClientCredentialsTokenEndpoint
+IUserTokenManagementService => IUserTokenManager
+ITokenRequestSynchronization => IUserTokenRequestConcurrencyControl
+IUserTokenEndpointService => IUserTokenEndpoint

src/content/docs/accesstokenmanagement/web-apps.md

@@ -12,12 +12,6 @@ redirect_from:
 The `Duende.AccessTokenManagement.OpenIdConnect` library automates all the tasks around access token lifetime management for
 user-centric web applications.
 
-To use this library, start by adding the library to your .NET projects.
-
-```bash
-dotnet add package Duende.AccessTokenManagement.OpenIdConnect
-```
-
 While many of the details can be customized, by default the following is assumed:
 
 * ASP.NET Core web application
@@ -26,7 +20,22 @@ While many of the details can be customized, by default the following is assumed
   token service
 * the token service returns a refresh token
 
-## Setup
+## Usage
+First, you'll need to add `Duende.AccessTokenManagement.OpenIdConnect` to your solution. 
+
+Then, there  are two fundamental ways to interact with token management:
+1. **Automatic** <Badge text="recommended"/>: You request a http client from the IHTTPClientFactory. This http client automatically requests, optionally renews and attaches the access tokens on each request. 
+2. **Manually**  <Badge text="advanced"/>: You request an access token, which you can then use to (for example) authenticate with services. You are responsible for attaching the access token to requests. 
+
+
+## Adding Duende.AccessTokenManagement.OpenIdConnect
+
+
+To use this library, start by adding the library to your .NET projects.
+
+```bash
+dotnet add package Duende.AccessTokenManagement.OpenIdConnect
+```
 
 By default, the token management library will use the ASP.NET Core default authentication scheme for token storage (this
 is typically the cookie handler and its authentication session), and the default challenge scheme for deriving token
@@ -90,7 +99,7 @@ builder.Services.AddAuthentication(options =>
 builder.Services.AddOpenIdConnectAccessTokenManagement();
 ```
 
-### HTTP Client Factory
+### Automatic via HTTP Client Factory
 
 Similar to the worker service support, you can register HTTP clients that automatically send the access token of the
 current user when making API calls. The message handler plumbing associated with those HTTP clients will try to make