Update OIDC client documentation with examples and clarifications

src/content/docs/identitymodel-oidcclient/automatic.md

@@ -8,10 +8,81 @@ redirect_from:
   - /foss/identitymodel.oidcclient/automatic/
 ---
 
-In automatic mode, you can encapsulate all browser interactions by
-implementing the
-[IBrowser](https://github.com/DuendeArchive/IdentityModel.OidcClient/blob/main/src/OidcClient/Browser/IBrowser.cs)
-interface:
+OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0
+protocol. It allows clients to verify the identity of the end-user based on
+the authentication performed by an authorization server, as well as obtain
+basic profile information.
+
+An essential part of the OIDC flow is the use of a browser to interact with the
+end-user and to obtain permissions to access protected resources.
+
+In the OidcClient library, you can encapsulate the browser interaction by implementing the
+[IBrowser](https://github.com/DuendeSoftware/foss/blob/main/identity-model-oidc-client/src/IdentityModel.OidcClient/Browser/IBrowser.cs)
+interface. Using `IBrowser` helps create a reusable component for all OIDC interaction.
+
+```csharp
+// Copyright (c) Duende Software. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See LICENSE in the project root for license information.
+
+namespace Duende.IdentityModel.OidcClient.Browser;
+
+/// <summary>
+/// Models a browser
+/// </summary>
+public interface IBrowser
+{
+    /// <summary>
+    /// Invokes the browser.
+    /// </summary>
+    /// <param name="options">The options.</param>
+    /// <param name="cancellationToken">A token that can be used to cancel the request</param>
+    /// <returns></returns>
+    Task<BrowserResult> InvokeAsync(BrowserOptions options, CancellationToken cancellationToken = default);
+}
+```
+
+The `BrowserResult` represents the result of the browser interaction, including any OIDC payloads that
+are returned from the authentication server.
+
+```csharp
+// Copyright (c) Duende Software. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See LICENSE in the project root for license information.
+
+namespace Duende.IdentityModel.OidcClient.Browser;
+
+/// <summary>
+/// The result from a browser login.
+/// </summary>
+/// <seealso cref="Result" />
+public class BrowserResult : Result
+{
+    /// <summary>
+    /// Gets or sets the type of the result.
+    /// </summary>
+    /// <value>
+    /// The type of the result.
+    /// </value>
+    public BrowserResultType ResultType { get; set; }
+
+    /// <summary>
+    /// Gets or sets the response.
+    /// </summary>
+    /// <value>
+    /// The response.
+    /// </value>
+    public string Response { get; set; }
+}
+```
+
+:::note
+The `IBrowser` implementation must be specific to the platform and environment and must be provided by the
+host application. For example, a Windows-specific implementation will not work within a macOS, iOS, Android, or Linux environment.
+:::
+
+For a simple example, the following code shows how to use the
+[SystemBrowser](https://github.com/DuendeSoftware/foss/blob/main/identity-model-oidc-client/clients/ConsoleClientWithBrowser/SystemBrowser.cs)
+to invoke a browser on the host desktop platform. The `SystemBrowser` is a naive implementation that uses the
+[System.Diagnostics.Process](https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.process) class to invoke the browser.
 
 ```cs
 var options = new OidcClientOptions
@@ -26,9 +97,13 @@ var options = new OidcClientOptions
 var client = new OidcClient(options);
 ```
 
-Once that is done, authentication and token requests become one line of
-code:
+Once the `IBrowser` is configured, the `LoginAsync` method can be invoked to start the authentication flow.
 
 ```cs
 var result = await client.LoginAsync();
 ```
+
+Setting the `Browser` property reduces the need to process browser respones and to handle the `BrowserResult` directly. When using this automatic mode, the `LoginAsync` method will return a
+[`LoginResult`](https://github.com/DuendeSoftware/foss/blob/19370c6d4820a684d41d1d40b8192ee8b873b8f0/identity-model-oidc-client/src/IdentityModel.OidcClient/LoginResult.cs) which will contain a `ClaimsPrincipal` with the user's claims along with the `IdentityToken` and `AccessToken`.
+
+

src/content/docs/identitymodel-oidcclient/logging.md

@@ -8,9 +8,38 @@ redirect_from:
   - /foss/identitymodel.oidcclient/logging/
 ---
 
-OidcClient logs errors, warnings, and diagnostic information using
-*Microsoft.Extensions.Logging.ILogger*, the standard .NET logging library. You can use any
-logging provider to store your logs however you like. For example, you could configure
+`OidcClient` logs errors, warnings, and diagnostic information using
+`Microsoft.Extensions.Logging.ILogger`, the standard .NET logging library.
+
+```cs
+using Duende.IdentityModel;
+using Duende.IdentityModel.OidcClient;
+
+var builder = Host.CreateApplicationBuilder(args);
+
+builder.Services.AddSingleton(svc =>
+{
+    var loggerFactory = svc.GetRequiredService<ILoggerFactory>();
+    var options = new OidcClientOptions
+    {
+        Authority = "https://demo.duendesoftware.com",
+        ClientId = "interactive.public",
+        Scope = "openid profile email offline_access",
+        RedirectUri = "app://localhost/",
+        PostLogoutRedirectUri = "app://localhost/",
+        LoggerFactory = loggerFactory
+    };
+    return new OidcClient(options);
+});
+
+var app = builder.Build();
+var client = app.Services.GetService<OidcClient>();
+```
+
+You can use any
+logging provider to store your logs however you like by setting the `LoggerFactory` property on `OidcClientOptions`.
+
+For example, you could configure
 [Serilog](https://github.com/serilog/serilog-extensions-hosting) like this:
 
 ```csharp
@@ -22,3 +51,27 @@ var serilog = new LoggerConfiguration()
 
 options.LoggerFactory.AddSerilog(serilog);
 ```
+
+## Log Levels
+
+The `OidcClient` logs at the following levels:
+
+- `Trace`
+- `Debug`
+- `Information`
+- `Error`
+
+You can set the log level in your `appSettings.json` by modifying the following snippet.
+
+```json
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft": "Warning",
+      "Microsoft.Hosting.Lifetime": "Information",
+      "Duende.IdentityModel.OidcClient": "Error"
+    }
+  }
+}
+```

src/content/docs/identitymodel-oidcclient/manual.md

@@ -3,13 +3,23 @@ title: OIDC Client Manual Mode
 description: "Guide for implementing manual mode in OidcClient to handle browser interactions and token processing"
 sidebar:
   order: 2
+  label: Manual Mode
 redirect_from:
   - /foss/identitymodel.oidcclient/manual/
 ---
 
-In manual mode, OidcClient helps you with creating the necessary start
-URL and state parameters, but you need to coordinate with whatever
-browser you want to use, e.g.:
+OpenID Connect is a protocol that allows you to authenticate users
+using a browser and involves browser-based interactions. When using this
+library you can choose between two modes: [automatic](./automatic.md) and manual.
+
+We recommend using automatic mode when possible, but sometimes you need
+to use manual mode when you want to handle browser interactions yourself.
+
+With manual mode, `OidcClient` is still useful, as it helps 
+with creating the necessary start URL and state parameters needed to complete an OIDC flow.
+You'll need to handle all browser interactions yourself with custom code. This is beneficial
+for scenarios where you want to customize the browser experience or when you want to
+integrate with other platform-specific browser libraries.
 
 ```csharp
 var options = new OidcClientOptions
@@ -26,13 +36,13 @@ var client = new OidcClient(options);
 var state = await client.PrepareLoginAsync();
 ```
 
-When the browser work is done, OidcClient can take over to process the
+When the browser work is done, `OidcClient` can take over to process the
 response, get the access/refresh tokens, contact userinfo endpoint
 etc.:
 
 ```csharp
 var result = await client.ProcessResponseAsync(data, state);
 ```
 
-The result will contain the tokens and the claims of the user.
-
+When using this manual mode, and processing the response, the `ProcessResponseAsync` method will return a
+[`LoginResult`](https://github.com/DuendeSoftware/foss/blob/19370c6d4820a684d41d1d40b8192ee8b873b8f0/identity-model-oidc-client/src/IdentityModel.OidcClient/LoginResult.cs) which will contain a `ClaimsPrincipal` with the user's claims along with the `IdentityToken` and `AccessToken`.