Add Documentation to illustrate the use of ITokenRequestCustomizer

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

@@ -99,3 +99,70 @@ services.AddHttpClient<YourTypedHttpClient>()
             logger: logger);
     });
 ```
+
+## Token Request Customization
+
+Token request parameters can be customized by implementing the `ITokenRequestCustomizer` interface.
+This interface allows you to dynamically modify token request parameters based on the incoming HTTP request context, making it ideal for multi-tenant applications where token parameters need to vary per tenant.
+
+The customizer is invoked before token retrieval and works with both user and client credentials flows. Unlike implementing a custom token retriever, which replaces the entire token acquisition logic, the customizer focuses on modifying parameters such as scopes, resources or other parts of the `TokenRequestParameters`.
+
+### Multi-Tenant Scenario
+
+In multi-tenant applications, different tenants often require different parameters. For example, each tenant might have:
+- A unique API resource or audience identifier
+- Tenant-specific scopes
+
+The `ITokenRequestCustomizer` provides a clean way to handle these variations without needing separate `HttpClient` configurations for each tenant.
+
+The following example demonstrates a multi-tenant scenario where the customizer extracts the tenant identifier from the HTTP request and applies tenant-specific token parameters:
+
+```csharp
+// MultiTenantTokenRequestCustomizer.cs
+public class MultiTenantTokenRequestCustomizer(
+    ITenantResolver tenantResolver,
+    ITenantConfigurationStore tenantConfigStore) : ITokenRequestCustomizer
+{
+    public async Task<TokenRequestParameters> Customize(
+        HttpRequestMessage httpRequest,
+        TokenRequestParameters baseParameters,
+        CancellationToken cancellationToken)
+    {
+        // Extract tenant identifier from the request
+        // This could come from a header, subdomain, or route parameter
+        var tenantId = await tenantResolver.GetTenantIdAsync(httpRequest, cancellationToken);
+
+        // Get tenant-specific configuration
+        var tenantConfig = await tenantConfigStore.GetConfigurationAsync(tenantId, cancellationToken);
+
+        // Customize parameters with tenant-specific values
+        return baseParameters with
+        {
+            Resource = Resource.Parse(tenantConfig.ApiResource),
+            Scope = Scope.Parse(tenantConfig.RequiredScopes),
+            // Add any additional customizations
+        };
+    }
+}
+```
+
+Register the customizer in your application startup:
+
+```csharp
+// Program.cs
+services.AddSingleton<ITokenRequestCustomizer, MultiTenantTokenRequestCustomizer>();
+```
+
+The customizer is automatically used by the access token management pipeline when configured. Both user token management and client credentials token management will invoke the customizer before retrieving tokens.
+
+:::tip[When to use ITokenRequestCustomizer vs ITokenRetriever]
+- Use **ITokenRequestCustomizer** when you need to modify token request parameters (scopes, resources, audiences) based on request context
+- Use **ITokenRetriever** when you need to replace the entire token acquisition logic with a custom flow
+:::
+
+### Additional Use Cases
+
+Beyond multi-tenancy, `ITokenRequestCustomizer` can be used for:
+- Dynamically setting scopes based on the target API endpoint
+- Adding audience or resource parameters based on request headers or route data
+- Implementing per-request token parameter logic without changing the core retrieval flow