From 207074761a5d4db7827ffc5a05470de64a07fa3c Mon Sep 17 00:00:00 2001
From: Darcy Ye <darcyye@silverhand.io>
Date: Mon, 11 Nov 2024 18:37:51 +0800
Subject: [PATCH 1/7] feat: support identifiers and first_screen sign-in params

---
 samples/sample-blazor/Program.cs              | 17 +++++-
 .../sample-mvc/Controllers/HomeController.cs  | 13 ++++-
 samples/sample/Pages/Index.cshtml.cs          | 13 ++++-
 .../LogtoParameters.cs                        | 53 +++++++++++++++++++
 .../AuthenticationBuilderExtensions.cs        | 20 +++++--
 5 files changed, 108 insertions(+), 8 deletions(-)

diff --git a/samples/sample-blazor/Program.cs b/samples/sample-blazor/Program.cs
index 014eb11..dcc1b95 100644
--- a/samples/sample-blazor/Program.cs
+++ b/samples/sample-blazor/Program.cs
@@ -47,8 +47,21 @@
 {
     if (!(context.User?.Identity?.IsAuthenticated ?? false))
     {
-        await context.ChallengeAsync(new AuthenticationProperties { RedirectUri = "/" });
-    } else {
+        var authProperties = new AuthenticationProperties 
+        { 
+            RedirectUri = "/" 
+        };
+
+        authProperties.SetParameter("first_screen", LogtoParameters.Authentication.FirstScreen.Register);
+        authProperties.SetParameter("identifiers", string.Join(",", new[] 
+        { 
+            LogtoParameters.Authentication.Identifiers.Username,
+        }));
+
+        await context.ChallengeAsync(authProperties);
+    } 
+    else 
+    {
         context.Response.Redirect("/");
     }
 });
diff --git a/samples/sample-mvc/Controllers/HomeController.cs b/samples/sample-mvc/Controllers/HomeController.cs
index b1dfa96..57ecb5f 100644
--- a/samples/sample-mvc/Controllers/HomeController.cs
+++ b/samples/sample-mvc/Controllers/HomeController.cs
@@ -25,7 +25,18 @@ public async Task<IActionResult> Index()
 
     public IActionResult SignIn()
     {
-        return Challenge(new AuthenticationProperties { RedirectUri = "/" });
+        var authProperties = new AuthenticationProperties 
+        { 
+            RedirectUri = "/" 
+        };
+
+        authProperties.SetParameter("first_screen", LogtoParameters.Authentication.FirstScreen.SignIn);
+        authProperties.SetParameter("identifiers", string.Join(",", new[] 
+        { 
+            LogtoParameters.Authentication.Identifiers.Username,
+        }));
+
+        return Challenge(authProperties);
     }
 
     // Use the `new` keyword to avoid conflict with the `ControllerBase.SignOut` method
diff --git a/samples/sample/Pages/Index.cshtml.cs b/samples/sample/Pages/Index.cshtml.cs
index ec836dc..48875ce 100644
--- a/samples/sample/Pages/Index.cshtml.cs
+++ b/samples/sample/Pages/Index.cshtml.cs
@@ -22,7 +22,18 @@ public async Task OnGetAsync()
 
     public async Task OnPostSignInAsync()
     {
-        await HttpContext.ChallengeAsync(new AuthenticationProperties { RedirectUri = "/" });
+        var authProperties = new AuthenticationProperties 
+        { 
+            RedirectUri = "/" 
+        };
+
+        authProperties.SetParameter("first_screen", LogtoParameters.Authentication.FirstScreen.Register);
+        authProperties.SetParameter("identifiers", string.Join(",", new[] 
+        { 
+            LogtoParameters.Authentication.Identifiers.Username,
+        }));
+
+        await HttpContext.ChallengeAsync(authProperties);
     }
 
     public async Task OnPostSignOutAsync()
diff --git a/src/Logto.AspNetCore.Authentication/LogtoParameters.cs b/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
index 86a4cca..c7e9c38 100644
--- a/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
+++ b/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
@@ -115,4 +115,57 @@ public static class Claims
     /// </summary>
     public const string Identities = "identities";
   }
+
+  /// <summary>
+  /// The authentication parameters for Logto sign-in experience customization.
+  /// </summary>
+  public static class Authentication
+  {
+    /// <summary>
+    /// The first screen to show in the sign-in experience.
+    /// </summary>
+    public static class FirstScreen
+    {
+      /// <summary>
+      /// Show the register form first.
+      /// </summary>
+      public const string Register = "identifier:register";
+
+      /// <summary>
+      /// Show the sign-in form first.
+      /// </summary>
+      public const string SignIn = "identifier:sign_in";
+
+      /// <summary>
+      /// Show the single sign-on form first.
+      /// </summary>
+      public const string SingleSignOn = "single_sign_on";
+
+      /// <summary>
+      /// Show the reset password form first.
+      /// </summary>
+      public const string ResetPassword = "reset_password";
+    }
+
+    /// <summary>
+    /// The identifiers to use for authentication.
+    /// </summary>
+    public static class Identifiers
+    {
+      /// <summary>
+      /// Use email for authentication.
+      /// </summary>
+      public const string Email = "email";
+      
+      /// <summary>
+      /// Use phone for authentication.
+      /// </summary>
+      public const string Phone = "phone";
+      
+      /// <summary>
+      /// Use username for authentication.
+      /// </summary>
+      public const string Username = "username";
+    }
+  }
 }
diff --git a/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs b/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs
index 4d4485f..b20cb28 100644
--- a/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs
+++ b/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs
@@ -9,6 +9,7 @@ namespace Logto.AspNetCore.Authentication;
 using Microsoft.IdentityModel.Tokens;
 using System;
 using System.Collections.Generic;
+using System.Threading.Tasks;
 
 /// <summary>
 /// Extension methods to configure Logto authentication.
@@ -101,15 +102,26 @@ private static void ConfigureOpenIdConnectOptions(OpenIdConnectOptions options,
     options.ClaimActions.MapAllExcept("nbf", "nonce", "c_hash", "at_hash");
     options.Events = new OpenIdConnectEvents
     {
+      OnRedirectToIdentityProvider = context =>
+      {
+        if (context.Properties.Parameters.TryGetValue("first_screen", out var firstScreen))
+        {
+          context.ProtocolMessage.Parameters.Add("first_screen", firstScreen?.ToString());
+        }
+
+        if (context.Properties.Parameters.TryGetValue("identifiers", out var identifiers))
+        {
+          context.ProtocolMessage.Parameters.Add("identifiers", identifiers?.ToString());
+        }
+
+        return Task.CompletedTask;
+      },
       OnRedirectToIdentityProviderForSignOut = async context =>
       {
-        // Clean up the cookie when signing out.
         await context.HttpContext.SignOutAsync(cookieScheme);
-
-        // Rebuild parameters since we use <c>client_id</c> for sign-out, no need to use <c>id_token_hint</c>.
         context.ProtocolMessage.Parameters.Remove(OpenIdConnectParameterNames.IdTokenHint);
         context.ProtocolMessage.Parameters.Add(OpenIdConnectParameterNames.ClientId, logtoOptions.AppId);
-      },
+      }
     };
     options.TokenValidationParameters = new TokenValidationParameters
     {

From 4bd263fcd399e087d9aa46e79ac66513576470c9 Mon Sep 17 00:00:00 2001
From: Darcy Ye <darcyye@silverhand.io>
Date: Mon, 11 Nov 2024 23:37:38 +0800
Subject: [PATCH 2/7] feat: support direct_sign_in and extra_params sign-in
 params

---
 samples/sample-blazor/Program.cs              | 16 ++++++++
 .../sample-mvc/Controllers/HomeController.cs  | 17 ++++++++-
 samples/sample/Pages/Index.cshtml.cs          | 15 ++++++++
 .../LogtoParameters.cs                        | 37 +++++++++++++++++++
 .../AuthenticationBuilderExtensions.cs        | 25 +++++++++++++
 5 files changed, 109 insertions(+), 1 deletion(-)

diff --git a/samples/sample-blazor/Program.cs b/samples/sample-blazor/Program.cs
index dcc1b95..823c10d 100644
--- a/samples/sample-blazor/Program.cs
+++ b/samples/sample-blazor/Program.cs
@@ -58,6 +58,22 @@
             LogtoParameters.Authentication.Identifiers.Username,
         }));
 
+        // Set `direct_sign_in`
+        var directSignIn = new LogtoParameters.Authentication.DirectSignIn
+        {
+            Target = "github",
+            Method = LogtoParameters.Authentication.DirectSignIn.Methods.Social
+        };
+        authProperties.SetParameter("direct_sign_in", System.Text.Json.JsonSerializer.Serialize(directSignIn));
+
+        // Set `extra_params`
+        var extraParams = new LogtoParameters.Authentication.ExtraParams
+        {
+            { "utm_source", "website" },
+            { "utm_medium", "organic" }
+        };
+        authProperties.SetParameter("extra_params", System.Text.Json.JsonSerializer.Serialize(extraParams));
+
         await context.ChallengeAsync(authProperties);
     } 
     else 
diff --git a/samples/sample-mvc/Controllers/HomeController.cs b/samples/sample-mvc/Controllers/HomeController.cs
index 57ecb5f..8bea667 100644
--- a/samples/sample-mvc/Controllers/HomeController.cs
+++ b/samples/sample-mvc/Controllers/HomeController.cs
@@ -3,6 +3,7 @@
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.AspNetCore.Mvc;
 using sample_mvc.Models;
+using System.Text.Json;
 
 namespace sample_mvc.Controllers;
 
@@ -30,12 +31,26 @@ public IActionResult SignIn()
             RedirectUri = "/" 
         };
 
-        authProperties.SetParameter("first_screen", LogtoParameters.Authentication.FirstScreen.SignIn);
+        authProperties.SetParameter("first_screen", LogtoParameters.Authentication.FirstScreen.Register);
         authProperties.SetParameter("identifiers", string.Join(",", new[] 
         { 
             LogtoParameters.Authentication.Identifiers.Username,
         }));
 
+        var directSignIn = new LogtoParameters.Authentication.DirectSignIn
+        {
+            Target = "github",
+            Method = LogtoParameters.Authentication.DirectSignIn.Methods.Social
+        };
+        authProperties.SetParameter("direct_sign_in", JsonSerializer.Serialize(directSignIn));
+
+        var extraParams = new LogtoParameters.Authentication.ExtraParams
+        {
+            { "utm_source", "website" },
+            { "utm_medium", "organic" }
+        };
+        authProperties.SetParameter("extra_params", JsonSerializer.Serialize(extraParams));
+
         return Challenge(authProperties);
     }
 
diff --git a/samples/sample/Pages/Index.cshtml.cs b/samples/sample/Pages/Index.cshtml.cs
index 48875ce..967524d 100644
--- a/samples/sample/Pages/Index.cshtml.cs
+++ b/samples/sample/Pages/Index.cshtml.cs
@@ -1,6 +1,7 @@
 using Logto.AspNetCore.Authentication;
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.AspNetCore.Mvc.RazorPages;
+using System.Text.Json;
 
 namespace sample.Pages;
 
@@ -33,6 +34,20 @@ public async Task OnPostSignInAsync()
             LogtoParameters.Authentication.Identifiers.Username,
         }));
 
+        var directSignIn = new LogtoParameters.Authentication.DirectSignIn
+        {
+            Target = "github",
+            Method = LogtoParameters.Authentication.DirectSignIn.Methods.Social
+        };
+        authProperties.SetParameter("direct_sign_in", JsonSerializer.Serialize(directSignIn));
+
+        var extraParams = new LogtoParameters.Authentication.ExtraParams
+        {
+            { "utm_source", "website" },
+            { "utm_medium", "organic" }
+        };
+        authProperties.SetParameter("extra_params", JsonSerializer.Serialize(extraParams));
+
         await HttpContext.ChallengeAsync(authProperties);
     }
 
diff --git a/src/Logto.AspNetCore.Authentication/LogtoParameters.cs b/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
index c7e9c38..1874e50 100644
--- a/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
+++ b/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
@@ -1,4 +1,5 @@
 using Microsoft.IdentityModel.Protocols.OpenIdConnect;
+using System.Collections.Generic;
 
 namespace Logto.AspNetCore.Authentication;
 
@@ -167,5 +168,41 @@ public static class Identifiers
       /// </summary>
       public const string Username = "username";
     }
+
+    /// <summary>
+    /// Direct sign-in configuration.
+    /// </summary>
+    public class DirectSignIn
+    {
+      /// <summary>
+      /// The target identifier for direct sign-in.
+      /// </summary>
+      public string Target { get; set; } = string.Empty;
+
+      /// <summary>
+      /// The sign-in method.
+      /// </summary>
+      public string Method { get; set; } = string.Empty;
+
+      public static class Methods
+      {
+        /// <summary>
+        /// Single sign-on method.
+        /// </summary>
+        public const string Sso = "sso";
+
+        /// <summary>
+        /// Social sign-in method.
+        /// </summary>
+        public const string Social = "social";
+      }
+    }
+
+    /// <summary>
+    /// Extra parameters to be passed to the authorization endpoint.
+    /// </summary>
+    public class ExtraParams : Dictionary<string, string>
+    {
+    }
   }
 }
diff --git a/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs b/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs
index b20cb28..684eb01 100644
--- a/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs
+++ b/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs
@@ -114,6 +114,31 @@ private static void ConfigureOpenIdConnectOptions(OpenIdConnectOptions options,
           context.ProtocolMessage.Parameters.Add("identifiers", identifiers?.ToString());
         }
 
+        if (context.Properties.Parameters.TryGetValue("direct_sign_in", out var directSignIn))
+        {
+          var directSignInOption = System.Text.Json.JsonSerializer.Deserialize<LogtoParameters.Authentication.DirectSignIn>(
+            directSignIn?.ToString() ?? "{}"
+          );
+          if (directSignInOption != null && !string.IsNullOrEmpty(directSignInOption.Method) && !string.IsNullOrEmpty(directSignInOption.Target))
+          {
+            context.ProtocolMessage.Parameters.Add("direct_sign_in", $"{directSignInOption.Method}:{directSignInOption.Target}");
+          }
+        }
+
+        if (context.Properties.Parameters.TryGetValue("extra_params", out var extraParams))
+        {
+          var parameters = System.Text.Json.JsonSerializer.Deserialize<LogtoParameters.Authentication.ExtraParams>(
+            extraParams?.ToString() ?? "{}"
+          );
+          if (parameters != null)
+          {
+            foreach (var param in parameters)
+            {
+              context.ProtocolMessage.Parameters.Add(param.Key, param.Value);
+            }
+          }
+        }
+
         return Task.CompletedTask;
       },
       OnRedirectToIdentityProviderForSignOut = async context =>

From d386cbd3db947f1651a364678937a6cc6ce8d494 Mon Sep 17 00:00:00 2001
From: Darcy Ye <darcyye@silverhand.io>
Date: Tue, 12 Nov 2024 12:43:25 +0800
Subject: [PATCH 3/7] chore: add comments

---
 samples/sample-blazor/Program.cs                   | 14 ++++----------
 samples/sample-mvc/Controllers/HomeController.cs   | 10 +++-------
 samples/sample/Pages/Index.cshtml.cs               | 10 +++-------
 .../LogtoParameters.cs                             |  1 +
 4 files changed, 11 insertions(+), 24 deletions(-)

diff --git a/samples/sample-blazor/Program.cs b/samples/sample-blazor/Program.cs
index 823c10d..cbc1090 100644
--- a/samples/sample-blazor/Program.cs
+++ b/samples/sample-blazor/Program.cs
@@ -52,28 +52,22 @@
             RedirectUri = "/" 
         };
 
+        // Set the first screen, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#first-screen.
         authProperties.SetParameter("first_screen", LogtoParameters.Authentication.FirstScreen.Register);
+        // Set the identifiers, should work with `first_screen`.
         authProperties.SetParameter("identifiers", string.Join(",", new[] 
-        { 
+        {
             LogtoParameters.Authentication.Identifiers.Username,
         }));
 
-        // Set `direct_sign_in`
         var directSignIn = new LogtoParameters.Authentication.DirectSignIn
         {
             Target = "github",
             Method = LogtoParameters.Authentication.DirectSignIn.Methods.Social
         };
+        // Set the direct sign-in, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#direct-sign-in.
         authProperties.SetParameter("direct_sign_in", System.Text.Json.JsonSerializer.Serialize(directSignIn));
 
-        // Set `extra_params`
-        var extraParams = new LogtoParameters.Authentication.ExtraParams
-        {
-            { "utm_source", "website" },
-            { "utm_medium", "organic" }
-        };
-        authProperties.SetParameter("extra_params", System.Text.Json.JsonSerializer.Serialize(extraParams));
-
         await context.ChallengeAsync(authProperties);
     } 
     else 
diff --git a/samples/sample-mvc/Controllers/HomeController.cs b/samples/sample-mvc/Controllers/HomeController.cs
index 8bea667..a594f43 100644
--- a/samples/sample-mvc/Controllers/HomeController.cs
+++ b/samples/sample-mvc/Controllers/HomeController.cs
@@ -31,7 +31,9 @@ public IActionResult SignIn()
             RedirectUri = "/" 
         };
 
+        // Set the first screen, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#first-screen.
         authProperties.SetParameter("first_screen", LogtoParameters.Authentication.FirstScreen.Register);
+        // Set the identifiers, should work with `first_screen`.
         authProperties.SetParameter("identifiers", string.Join(",", new[] 
         { 
             LogtoParameters.Authentication.Identifiers.Username,
@@ -42,15 +44,9 @@ public IActionResult SignIn()
             Target = "github",
             Method = LogtoParameters.Authentication.DirectSignIn.Methods.Social
         };
+        // Set the direct sign-in, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#direct-sign-in.
         authProperties.SetParameter("direct_sign_in", JsonSerializer.Serialize(directSignIn));
 
-        var extraParams = new LogtoParameters.Authentication.ExtraParams
-        {
-            { "utm_source", "website" },
-            { "utm_medium", "organic" }
-        };
-        authProperties.SetParameter("extra_params", JsonSerializer.Serialize(extraParams));
-
         return Challenge(authProperties);
     }
 
diff --git a/samples/sample/Pages/Index.cshtml.cs b/samples/sample/Pages/Index.cshtml.cs
index 967524d..e204c23 100644
--- a/samples/sample/Pages/Index.cshtml.cs
+++ b/samples/sample/Pages/Index.cshtml.cs
@@ -28,7 +28,9 @@ public async Task OnPostSignInAsync()
             RedirectUri = "/" 
         };
 
+        // Set the first screen, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#first-screen.
         authProperties.SetParameter("first_screen", LogtoParameters.Authentication.FirstScreen.Register);
+        // Set the identifiers, should work with `first_screen`.
         authProperties.SetParameter("identifiers", string.Join(",", new[] 
         { 
             LogtoParameters.Authentication.Identifiers.Username,
@@ -39,15 +41,9 @@ public async Task OnPostSignInAsync()
             Target = "github",
             Method = LogtoParameters.Authentication.DirectSignIn.Methods.Social
         };
+        // Set the direct sign-in, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#direct-sign-in.
         authProperties.SetParameter("direct_sign_in", JsonSerializer.Serialize(directSignIn));
 
-        var extraParams = new LogtoParameters.Authentication.ExtraParams
-        {
-            { "utm_source", "website" },
-            { "utm_medium", "organic" }
-        };
-        authProperties.SetParameter("extra_params", JsonSerializer.Serialize(extraParams));
-
         await HttpContext.ChallengeAsync(authProperties);
     }
 
diff --git a/src/Logto.AspNetCore.Authentication/LogtoParameters.cs b/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
index 1874e50..2f67563 100644
--- a/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
+++ b/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
@@ -150,6 +150,7 @@ public static class FirstScreen
 
     /// <summary>
     /// The identifiers to use for authentication.
+    /// Should work with <see cref="FirstScreen"/>.
     /// </summary>
     public static class Identifiers
     {

From 59da6a2800b2f634bdee5c9c3caab83e92419996 Mon Sep 17 00:00:00 2001
From: Darcy Ye <darcyye@silverhand.io>
Date: Tue, 12 Nov 2024 19:13:22 +0800
Subject: [PATCH 4/7] chore: update comments

---
 src/Logto.AspNetCore.Authentication/LogtoParameters.cs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Logto.AspNetCore.Authentication/LogtoParameters.cs b/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
index 2f67563..3c30818 100644
--- a/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
+++ b/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
@@ -150,7 +150,7 @@ public static class FirstScreen
 
     /// <summary>
     /// The identifiers to use for authentication.
-    /// Should work with <see cref="FirstScreen"/>.
+    /// This parameter MUST be used together with <see cref="FirstScreen"/>.
     /// </summary>
     public static class Identifiers
     {

From 17e2f9fe3fe82bac12fb04392752cd4351035b4e Mon Sep 17 00:00:00 2001
From: Darcy Ye <darcyye@silverhand.io>
Date: Wed, 13 Nov 2024 12:02:56 +0800
Subject: [PATCH 5/7] chore: update comments, notice that identifiers MUST work
 with first_screen

---
 samples/sample-blazor/Program.cs                 | 2 +-
 samples/sample-mvc/Controllers/HomeController.cs | 2 +-
 samples/sample/Pages/Index.cshtml.cs             | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/samples/sample-blazor/Program.cs b/samples/sample-blazor/Program.cs
index cbc1090..13f3129 100644
--- a/samples/sample-blazor/Program.cs
+++ b/samples/sample-blazor/Program.cs
@@ -54,7 +54,7 @@
 
         // Set the first screen, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#first-screen.
         authProperties.SetParameter("first_screen", LogtoParameters.Authentication.FirstScreen.Register);
-        // Set the identifiers, should work with `first_screen`.
+        // Set the `identifiers`, this parameter MUST be used together with `first_screen`.
         authProperties.SetParameter("identifiers", string.Join(",", new[] 
         {
             LogtoParameters.Authentication.Identifiers.Username,
diff --git a/samples/sample-mvc/Controllers/HomeController.cs b/samples/sample-mvc/Controllers/HomeController.cs
index a594f43..bb778f6 100644
--- a/samples/sample-mvc/Controllers/HomeController.cs
+++ b/samples/sample-mvc/Controllers/HomeController.cs
@@ -33,7 +33,7 @@ public IActionResult SignIn()
 
         // Set the first screen, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#first-screen.
         authProperties.SetParameter("first_screen", LogtoParameters.Authentication.FirstScreen.Register);
-        // Set the identifiers, should work with `first_screen`.
+        // Set the `identifiers`, this parameter MUST be used together with `first_screen`.
         authProperties.SetParameter("identifiers", string.Join(",", new[] 
         { 
             LogtoParameters.Authentication.Identifiers.Username,
diff --git a/samples/sample/Pages/Index.cshtml.cs b/samples/sample/Pages/Index.cshtml.cs
index e204c23..b203ee2 100644
--- a/samples/sample/Pages/Index.cshtml.cs
+++ b/samples/sample/Pages/Index.cshtml.cs
@@ -30,7 +30,7 @@ public async Task OnPostSignInAsync()
 
         // Set the first screen, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#first-screen.
         authProperties.SetParameter("first_screen", LogtoParameters.Authentication.FirstScreen.Register);
-        // Set the identifiers, should work with `first_screen`.
+        // Set the `identifiers`, this parameter MUST be used together with `first_screen`.
         authProperties.SetParameter("identifiers", string.Join(",", new[] 
         { 
             LogtoParameters.Authentication.Identifiers.Username,

From d5bc1eccfbcf6becbc44cb032e3da92eed9ef004 Mon Sep 17 00:00:00 2001
From: Darcy Ye <darcyye@silverhand.io>
Date: Wed, 13 Nov 2024 22:16:18 +0800
Subject: [PATCH 6/7] chore: update comments

---
 samples/sample-blazor/Program.cs                     | 10 +++++++---
 samples/sample-mvc/Controllers/HomeController.cs     | 12 ++++++++----
 samples/sample/Pages/Index.cshtml.cs                 | 12 ++++++++----
 .../extensions/AuthenticationBuilderExtensions.cs    |  5 ++++-
 4 files changed, 27 insertions(+), 12 deletions(-)

diff --git a/samples/sample-blazor/Program.cs b/samples/sample-blazor/Program.cs
index 13f3129..6022c9a 100644
--- a/samples/sample-blazor/Program.cs
+++ b/samples/sample-blazor/Program.cs
@@ -52,9 +52,11 @@
             RedirectUri = "/" 
         };
 
-        // Set the first screen, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#first-screen.
+        /// <see href="https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#first-screen"/>
+        /// <see cref="LogtoParameters.Authentication.FirstScreen"/>
         authProperties.SetParameter("first_screen", LogtoParameters.Authentication.FirstScreen.Register);
-        // Set the `identifiers`, this parameter MUST be used together with `first_screen`.
+        
+        // This parameter MUST be used together with `first_screen`.
         authProperties.SetParameter("identifiers", string.Join(",", new[] 
         {
             LogtoParameters.Authentication.Identifiers.Username,
@@ -65,7 +67,9 @@
             Target = "github",
             Method = LogtoParameters.Authentication.DirectSignIn.Methods.Social
         };
-        // Set the direct sign-in, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#direct-sign-in.
+        
+        /// <see href="https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#direct-sign-in"/>
+        /// <see cref="LogtoParameters.Authentication.DirectSignIn"/>
         authProperties.SetParameter("direct_sign_in", System.Text.Json.JsonSerializer.Serialize(directSignIn));
 
         await context.ChallengeAsync(authProperties);
diff --git a/samples/sample-mvc/Controllers/HomeController.cs b/samples/sample-mvc/Controllers/HomeController.cs
index bb778f6..b0c813d 100644
--- a/samples/sample-mvc/Controllers/HomeController.cs
+++ b/samples/sample-mvc/Controllers/HomeController.cs
@@ -31,11 +31,13 @@ public IActionResult SignIn()
             RedirectUri = "/" 
         };
 
-        // Set the first screen, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#first-screen.
+        /// <see href="https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#first-screen"/>
+        /// <see cref="LogtoParameters.Authentication.FirstScreen"/>
         authProperties.SetParameter("first_screen", LogtoParameters.Authentication.FirstScreen.Register);
-        // Set the `identifiers`, this parameter MUST be used together with `first_screen`.
+        
+        // This parameter MUST be used together with `first_screen`.
         authProperties.SetParameter("identifiers", string.Join(",", new[] 
-        { 
+        {
             LogtoParameters.Authentication.Identifiers.Username,
         }));
 
@@ -44,7 +46,9 @@ public IActionResult SignIn()
             Target = "github",
             Method = LogtoParameters.Authentication.DirectSignIn.Methods.Social
         };
-        // Set the direct sign-in, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#direct-sign-in.
+
+        /// <see href="https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#direct-sign-in"/>
+        /// <see cref="LogtoParameters.Authentication.DirectSignIn"/>
         authProperties.SetParameter("direct_sign_in", JsonSerializer.Serialize(directSignIn));
 
         return Challenge(authProperties);
diff --git a/samples/sample/Pages/Index.cshtml.cs b/samples/sample/Pages/Index.cshtml.cs
index b203ee2..1a94fc1 100644
--- a/samples/sample/Pages/Index.cshtml.cs
+++ b/samples/sample/Pages/Index.cshtml.cs
@@ -28,11 +28,13 @@ public async Task OnPostSignInAsync()
             RedirectUri = "/" 
         };
 
-        // Set the first screen, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#first-screen.
+        /// <see href="https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#first-screen"/>
+        /// <see cref="LogtoParameters.Authentication.FirstScreen"/>
         authProperties.SetParameter("first_screen", LogtoParameters.Authentication.FirstScreen.Register);
-        // Set the `identifiers`, this parameter MUST be used together with `first_screen`.
+        
+        // This parameter MUST be used together with `first_screen`
         authProperties.SetParameter("identifiers", string.Join(",", new[] 
-        { 
+        {
             LogtoParameters.Authentication.Identifiers.Username,
         }));
 
@@ -41,7 +43,9 @@ public async Task OnPostSignInAsync()
             Target = "github",
             Method = LogtoParameters.Authentication.DirectSignIn.Methods.Social
         };
-        // Set the direct sign-in, see https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#direct-sign-in.
+        
+        /// <see href="https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#direct-sign-in"/>
+        /// <see cref="LogtoParameters.Authentication.DirectSignIn"/>
         authProperties.SetParameter("direct_sign_in", JsonSerializer.Serialize(directSignIn));
 
         await HttpContext.ChallengeAsync(authProperties);
diff --git a/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs b/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs
index 684eb01..1ea2b59 100644
--- a/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs
+++ b/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs
@@ -143,10 +143,13 @@ private static void ConfigureOpenIdConnectOptions(OpenIdConnectOptions options,
       },
       OnRedirectToIdentityProviderForSignOut = async context =>
       {
+        // Clean up the cookie when signing out.
         await context.HttpContext.SignOutAsync(cookieScheme);
+        
+        // Rebuild parameters since we use <c>client_id</c> for sign-out, no need to use <c>id_token_hint</c>.
         context.ProtocolMessage.Parameters.Remove(OpenIdConnectParameterNames.IdTokenHint);
         context.ProtocolMessage.Parameters.Add(OpenIdConnectParameterNames.ClientId, logtoOptions.AppId);
-      }
+      },
     };
     options.TokenValidationParameters = new TokenValidationParameters
     {

From a7a4dc83d02f62e7885440dee29ef8b0fb61342a Mon Sep 17 00:00:00 2001
From: Darcy Ye <darcyye@silverhand.io>
Date: Thu, 14 Nov 2024 11:46:37 +0800
Subject: [PATCH 7/7] chore: add ref links

---
 src/Logto.AspNetCore.Authentication/LogtoParameters.cs          | 2 ++
 .../extensions/AuthenticationBuilderExtensions.cs               | 1 -
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/Logto.AspNetCore.Authentication/LogtoParameters.cs b/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
index 3c30818..58b62b2 100644
--- a/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
+++ b/src/Logto.AspNetCore.Authentication/LogtoParameters.cs
@@ -124,6 +124,7 @@ public static class Authentication
   {
     /// <summary>
     /// The first screen to show in the sign-in experience.
+    /// See <see href="https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#first-screen"/> for more details.
     /// </summary>
     public static class FirstScreen
     {
@@ -172,6 +173,7 @@ public static class Identifiers
 
     /// <summary>
     /// Direct sign-in configuration.
+    /// See <see href="https://docs.logto.io/docs/references/openid-connect/authentication-parameters/#direct-sign-in"/> for more details.
     /// </summary>
     public class DirectSignIn
     {
diff --git a/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs b/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs
index 1ea2b59..2688a3d 100644
--- a/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs
+++ b/src/Logto.AspNetCore.Authentication/extensions/AuthenticationBuilderExtensions.cs
@@ -145,7 +145,6 @@ private static void ConfigureOpenIdConnectOptions(OpenIdConnectOptions options,
       {
         // Clean up the cookie when signing out.
         await context.HttpContext.SignOutAsync(cookieScheme);
-        
         // Rebuild parameters since we use <c>client_id</c> for sign-out, no need to use <c>id_token_hint</c>.
         context.ProtocolMessage.Parameters.Remove(OpenIdConnectParameterNames.IdTokenHint);
         context.ProtocolMessage.Parameters.Add(OpenIdConnectParameterNames.ClientId, logtoOptions.AppId);