updated webapps

Author: Erwinvandervalk

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

@@ -20,15 +20,16 @@ While many of the details can be customized, by default the following is assumed
   token service
 * the token service returns a refresh token
 
+Using this library, you can either request `user access tokens` or `client credentials tokens`. User access tokens typically contain information about the currently logged in user, such as the `sub` claim. They are used to access services under the credentials of the currently logged in user. `Client credentials tokens` do not contain information about the currently logged in user and are typically used to do machine-to-machine calls. 
+
 ## Usage
 First, you'll need to add `Duende.AccessTokenManagement.OpenIdConnect` to your solution. 
 
-Then, there  are two fundamental ways to interact with token management:
+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
+### Adding AccessTokenManagement to your project
 
 
 To use this library, start by adding the library to your .NET projects.
@@ -145,46 +146,103 @@ builder.Services.AddHttpClient<MasterDataClient>(client =>
     .AddClientAccessTokenHandler();
 ```
 
-## Usage
 
-There are three ways to interact with the token management service:
+Last but not least, if you registered clients with the factory, you can use them. They will try to make sure that a
+current access token is always sent along. If that is not possible, ultimately a 401 will be returned to the calling
+code.
 
-* Manually
-* HTTP context extension methods
-* HTTP client factory
+```csharp
+public async Task<IActionResult> CallApi()
+{
+    var client = _httpClientFactory.CreateClient("invoices");
 
-### Manually
+    var response = await client.GetAsync("list");
+    
+    // rest omitted
+}
+```
 
-You can get the current user and client access token manually by writing code against the `IUserTokenManagementService`.
+...or for a typed client:
 
 ```csharp
-public class HomeController : Controller
+public async Task<IActionResult> CallApi([FromServices] InvoiceClient client)
 {
-    private readonly IHttpClientFactory _httpClientFactory;
-    private readonly IUserTokenManagementService _tokenManagementService;
+    var response = await client.GetList();
+    
+    // rest omitted
+}
+```
 
-    public HomeController(IHttpClientFactory httpClientFactory, IUserTokenManagementService tokenManagementService)
-    {
-        _httpClientFactory = httpClientFactory;
-        _tokenManagementService = tokenManagementService;
-    }
+### Manually request access tokens
+
+If you want to use access tokens in a different way or have more advanced needs which the automatic option doesn't cover, then you can also manually request user access tokens. 
+
+{/* prettier-ignore */}
+<Tabs syncKey="atm-workers">
+  {/* prettier-ignore */}
+  <TabItem label="V4">
 
-    public async Task<IActionResult> CallApi()
+    You can get the current user access token manually by writing code against the `IUserTokenManager`.
+
+    ```csharp
+    public class HomeController : Controller
     {
-        var token = await _tokenManagementService.GetAccessTokenAsync(User);
-        var client = _httpClientFactory.CreateClient();
-        client.SetBearerToken(token.Value);
+        private readonly IHttpClientFactory _httpClientFactory;
+        private readonly IUserTokenManager _userTokenManager;
+
+        public HomeController(IHttpClientFactory httpClientFactory, IUserTokenManager userTokenManager)
+        {
+            _httpClientFactory = httpClientFactory;
+            _userTokenManager = userTokenManager;
+        }
+
+        public async Task<IActionResult> CallApi(CancellationToken ct)
+        {
+            var token = await _userTokenManager.GetAccessTokenAsync(User, ct: ct);
+            var client = _httpClientFactory.CreateClient();
+            client.SetBearerToken(token.Value);
+                
+            var response = await client.GetAsync("https://api.company.com/invoices", ct);
             
-        var response = await client.GetAsync("https://api.company.com/invoices");
-        
-        // rest omitted
+            // rest omitted
+        }
     }
-}
-```
+    ```
+  
+  </TabItem>
+  <TabItem label="V3">
+    You can get the current user access token manually by writing code against the `IUserTokenManagementService`.
+
+    ```csharp
+    public class HomeController : Controller
+    {
+        private readonly IHttpClientFactory _httpClientFactory;
+        private readonly IUserTokenManagementService _tokenManagementService;
+
+        public HomeController(IHttpClientFactory httpClientFactory, IUserTokenManagementService tokenManagementService)
+        {
+            _httpClientFactory = httpClientFactory;
+            _tokenManagementService = tokenManagementService;
+        }
+
+        public async Task<IActionResult> CallApi()
+        {
+            var token = await _tokenManagementService.GetAccessTokenAsync(User);
+            var client = _httpClientFactory.CreateClient();
+            client.SetBearerToken(token.Value);
+                
+            var response = await client.GetAsync("https://api.company.com/invoices");
+            
+            // rest omitted
+        }
+    }  
+  </TabItem>
+</Tabs>
+
 
 ### HTTP Context Extension Methods
 
-There are three extension methods on the HTTP context that simplify interaction with the token management service:
+Alternatively, you can also manually request access tokens via these extension methods on the `HttpContext`: 
 
 * `GetUserAccessTokenAsync` - returns an access token representing the user. If the current access token is expired, it
   will be refreshed.
@@ -204,31 +262,3 @@ public async Task<IActionResult> CallApi()
     // rest omitted
 }
 ```
-
-### HTTP Client Factory
-
-Last but not least, if you registered clients with the factory, you can use them. They will try to make sure that a
-current access token is always sent along. If that is not possible, ultimately a 401 will be returned to the calling
-code.
-
-```csharp
-public async Task<IActionResult> CallApi()
-{
-    var client = _httpClientFactory.CreateClient("invoices");
-
-    var response = await client.GetAsync("list");
-    
-    // rest omitted
-}
-```
-
-...or for a typed client:
-
-```csharp
-public async Task<IActionResult> CallApi([FromServices] InvoiceClient client)
-{
-    var response = await client.GetList();
-    
-    // rest omitted
-}
-```

src/content/docs/accesstokenmanagement/workers.mdx

@@ -159,39 +159,39 @@ The following code registers an `HttpClient` called `invoices` which automatical
 </Tabs>
 
 
-    Once you have set up HTTP clients in the HTTP factory, then no token related code is needed at all, e.g.:
+Once you have set up HTTP clients in the HTTP factory, then no token related code is needed at all, e.g.:
 
-    ```csharp
-    // WorkerHttpClient.cs
-    public class WorkerHttpClient : BackgroundService
-    {
-        private readonly ILogger<WorkerHttpClient> _logger;
-        private readonly IHttpClientFactory _clientFactory;
+```csharp
+// WorkerHttpClient.cs
+public class WorkerHttpClient : BackgroundService
+{
+    private readonly ILogger<WorkerHttpClient> _logger;
+    private readonly IHttpClientFactory _clientFactory;
 
-        public WorkerHttpClient(ILogger<WorkerHttpClient> logger, IHttpClientFactory factory)
-        {
-            _logger = logger;
-            _clientFactory = factory;
-        }
+    public WorkerHttpClient(ILogger<WorkerHttpClient> logger, IHttpClientFactory factory)
+    {
+        _logger = logger;
+        _clientFactory = factory;
+    }
 
-        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        while (!stoppingToken.IsCancellationRequested)
         {
-            while (!stoppingToken.IsCancellationRequested)
-            {
-                var client = _clientFactory.CreateClient("invoices");
-                var response = await client.GetAsync("test", stoppingToken);
+            var client = _clientFactory.CreateClient("invoices");
+            var response = await client.GetAsync("test", stoppingToken);
 
-                // rest omitted
-            }
+            // rest omitted
         }
     }
-    ```
+}
+```
 
 :::note
 The clients in the HTTP client factory have a message handler attached to them that automatically retries the request in case of a `401` response code. The request get resent with a newly requested access token. If this still results in a `401`, the response is returned to the caller.
 :::
 
-### Manual
+### Manually request access tokens
 
 If you want to use access tokens in a different way or have more advanced needs which the automatic option doesn't cover, then you can also manually request access tokens.