chore: Update Etsy.md TOC

Author: DevTKSS

docs/etsy.md

@@ -17,10 +17,10 @@ Etsy's OAuth implementation uses Authorization Code with PKCE and issues refresh
       - [Manually Added Claims](#manually-added-claims)
   - [Advanced Configuration](#advanced-configuration)
   - [Accessing claims (Minimal API Sample)](#accessing-claims-minimal-api-sample)
-    - [Directly in Program.cs](#directly-in-programcs)
-    - [Feature-style typed Minimal API endpoints with MapGroup](#feature-style-typed-minimal-api-endpoints-with-mapgroup)
+    - [Minimalistic directly in Program.cs](#minimalistic-directly-in-programcs)
+    - [Extended in a Feature-style Minimal API with endpoints using MapGroup](#extended-in-a-feature-style-minimal-api-with-endpoints-using-mapgroup)
+      - [Define record types for Typed Results](#define-record-types-for-typed-results)
       - [Extension class anywhere in your project](#extension-class-anywhere-in-your-project)
-      - [Sample record types](#sample-record-types)
       - [Register the endpoints in Program.cs](#register-the-endpoints-in-programcs)
 
 ## Quick Links
@@ -210,6 +210,7 @@ Here is a comprehensive `appsettings.json` example covering supported options an
     "AuthorizationEndpoint": "https://www.etsy.com/oauth/connect",
     "TokenEndpoint": "https://openapi.etsy.com/v3/public/oauth/token",
     "UserInformationEndpoint": "https://openapi.etsy.com/v3/application/users/me",
+    "CallbackPath": "/signin/etsy",
     "SaveTokens": true,
     "Scopes": [ "shops_r", "email_r" ]
   }
@@ -229,54 +230,67 @@ If you bind then from configuration, set the options in code, for example:
 builder.Services.AddAuthentication(options =>
 {
     options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
+    // If you only have Etsy as external provider you can apply it as default challenge scheme
     options.DefaultChallengeScheme = EtsyAuthenticationDefaults.AuthenticationScheme;
 })
-.AddCookie()
+.AddCookie(options =>
+{
+    options.LoginPath = "/signin";
+    options.LogoutPath = "/signout";
+})
 .AddEtsy(options =>
 {
-    var section = builder.Configuration.GetSection("Etsy");
-    options.ClientId = section.GetValue<string?>("ClientId")
-        ?? throw new InvalidOperationException("Etsy:ClientId configuration value is missing.");
+    var section = builder.Configuration.GetSection("Etsy").Get<EtsyAuthenticationOptions>()!;
+    if (section is not EtsyAuthenticationOptions
+      // Check if the values from appsettings.json has been properly overridden
+     || section.ClientId is "client-id-from-user-secrets")
+    {
+        throw new InvalidOperationException("Etsy configuration section is missing or invalid.");
+    }
 
-    // For the Detailed User Info Endpoint and SaveTokens are default values pre-set, but you can override them here
-    options.IncludeDetailedUserInfo = section.GetValue<bool>("IncludeDetailedUserInfo");
-    options.SaveTokens = section.GetValue<bool>("SaveTokens");
+    options.ClientId = section.ClientId;
+    // Optional: The Etsy App registration provides the `Shared Secret` but it's not documented to be used/required for PKCE flows.
+    options.ClientSecret = section.ClientSecret;
+    // Optional: Include detailed user info and auto-mapped claims to get e.g. email, first and last name
+    options.IncludeDetailedUserInfo = section.IncludeDetailedUserInfo;
 
-    // Use the defaults from EtsyAuthenticationDefaults, if you want to repeat them here, but they are set automatically
+    // Optional: Override the defaults from EtsyAuthenticationDefaults with your own values (not recommended! Will potentially break the handler)
+    // Here we just re-assign the defaults for demonstration
     options.AuthorizationEndpoint = EtsyAuthenticationDefaults.AuthorizationEndpoint;
     options.TokenEndpoint = EtsyAuthenticationDefaults.TokenEndpoint;
     options.UserInformationEndpoint = EtsyAuthenticationDefaults.UserInformationEndpoint;
 
-    // Apply scopes from config if present
-    var scopes = section.Get<string[]>("Scopes");
+    // Optional: Override SaveTokens setting from configuration (not recommended to disable! as Etsy API uses refresh tokens)
+    options.SaveTokens = section.SaveTokens;
 
-    if (scopes is not null)
+    // Optional: Add scopes from configuration
+    foreach (var scope in section.Scopes)
     {
-        foreach (var scope in scopes)
-        {
-            options.Scope.Add(scope);
-        }
+        options.Scope.Add(scope);
     }
 
-    // Optionally Map the image claim
+    // Optional: Or add scopes manually with provided constants
+    options.Scope.Add(EtsyAuthenticationConstants.Scopes.TransactionsRead);
+
+    // Optional: Map the image claim
     options.ClaimActions.MapImageClaim();
 
     // Map other Claims
-    options.ClaimActions.MapJsonKey("urn:etsy:listingsWrite", "listings_w");
+    options.ClaimActions.MapJsonKey("urn:etsy:listingsWrite", EtsyAuthenticationConstants.Claims.ListingsWrite);
 })
 ```
 
 ## Accessing claims (Minimal API Sample)
 
 If you want to access the claims provided by the Etsy provider, you can set up some Minimal API endpoints like this:
 
-### Directly in Program.cs
+### Minimalistic directly in Program.cs
 
 ```csharp
 using AspNet.Security.OAuth.Etsy;
 using System.Security.Claims;
 
-app.MapGet("/profile", (ClaimsPrincipal user) =>
+app.MapGet("/etsy/profile", (ClaimsPrincipal user) =>
 {
   var userId = user.FindFirstValue(ClaimTypes.NameIdentifier);
   var shopId = user.FindFirstValue(EtsyAuthenticationConstants.Claims.ShopId);
@@ -286,10 +300,43 @@ app.MapGet("/profile", (ClaimsPrincipal user) =>
   var imageUrl = user.FindFirstValue(EtsyAuthenticationConstants.Claims.ImageUrl);
 
   return Results.Ok(new { userId, shopId, email, firstName, lastName, imageUrl });
-}).RequireAuthorization();
+})
+.RequireAuthorization()
+.WithName("EtsyProfile")
+.WithSummary("Get authenticated user's Etsy profile information");
+```
+
+### Extended in a Feature-style Minimal API with endpoints using MapGroup
+
+This sample assumes you not only have Etsy as external provider and use cookie authentication for session management.
+
+#### Define record types for Typed Results
+
+Before we can start, we need some record types to hold the user profile and token information.
+
+The following ones are created from the json-objects returned by Etsy's API.
+
+```csharp
+public sealed record UserInfo
+{
+  public required string UserId { get; init; }
+  public required string ShopId { get; init; }
+  public string? Email { get; init; }
+  public string? FirstName { get; init; }
+  public string? LastName { get; init; }
+  public string? ImageUrl { get; init; }
+}
+
+public sealed record TokenInfo
+{
+  public string? AccessToken { get; init; }
+  public string? RefreshToken { get; init; }
+  public string? ExpiresAt { get; init; }
+}
 ```
 
-### Feature-style typed Minimal API endpoints with MapGroup
+> [!NOTE]
+> Make sure to add proper JSON serialization attributes if you use System.Text.Json or Newtonsoft.Json to serialize those records to JSON in the HTTP responses.
 
 #### Extension class anywhere in your project
 
@@ -336,12 +383,11 @@ public static class EtsyAuthEndpoints
 
   private static Results<ChallengeHttpResult, RedirectHttpResult> SignInAsync(string? returnUrl)
     => TypedResults.Challenge(
-      new AuthenticationProperties { RedirectUri = returnUrl ?? "/" },
-      new[] { EtsyAuthenticationDefaults.AuthenticationScheme });
+      new AuthenticationProperties { RedirectUri = returnUrl ?? "/" }, EtsyAuthenticationDefaults.AuthenticationScheme);
 
   private static async Task<RedirectHttpResult> SignOutAsync(HttpContext context)
   {
-    await context.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
+    await context.SignOutAsync(new AuthenticationProperties { RedirectUri = "/" }, CookieAuthenticationDefaults.AuthenticationScheme);
     return TypedResults.Redirect("/");
   }
 
@@ -371,32 +417,13 @@ public static class EtsyAuthEndpoints
 
     return TypedResults.Ok(tokenInfo);
   }
-```
-
-#### Sample record types
-
-```csharp
-  public sealed record UserInfo
-  {
-    public required string UserId { get; init; }
-    public required string ShopId { get; init; }
-    public string? Email { get; init; }
-    public string? FirstName { get; init; }
-    public string? LastName { get; init; }
-    public string? ImageUrl { get; init; }
-  }
-
-  public sealed record TokenInfo
-  {
-    public string? AccessToken { get; init; }
-    public string? RefreshToken { get; init; }
-    public string? ExpiresAt { get; init; }
-  }
 }
 ```
 
 #### Register the endpoints in Program.cs
 
+Now that we have defined the extension method to map the Etsy authentication endpoints, we need to register them in our `Program.cs` file.
+
 ```csharp
 using MyApi.Features.Authorization;
 app.MapEtsyAuth();