From e7ff63e486b7475fd094c86441f869fab25dac11 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Chalet?= <kevinchalet@gmail.com>
Date: Wed, 25 Feb 2026 17:41:49 +0100
Subject: [PATCH] Update the XML documentation to discourage using the implicit
 flow and the resource owner password credentials grant

---
 src/OpenIddict.Client/OpenIddictClientBuilder.cs | 10 ++++++++++
 src/OpenIddict.Server/OpenIddictServerBuilder.cs | 10 ++++++++++
 2 files changed, 20 insertions(+)

diff --git a/src/OpenIddict.Client/OpenIddictClientBuilder.cs b/src/OpenIddict.Client/OpenIddictClientBuilder.cs
index 860345cd..6a58d41a 100644
--- a/src/OpenIddict.Client/OpenIddictClientBuilder.cs
+++ b/src/OpenIddict.Client/OpenIddictClientBuilder.cs
@@ -982,6 +982,11 @@ public sealed class OpenIddictClientBuilder
     /// https://tools.ietf.org/html/rfc6749#section-4.2 and
     /// http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth.
     /// </summary>
+    /// <remarks>
+    /// Note: the implicit flow is not recommended for new applications due to
+    /// its inherent limitations and should only be used in legacy scenarios.
+    /// When possible, consider using the authorization code flow instead.
+    /// </remarks>
     /// <returns>The <see cref="OpenIddictClientBuilder"/> instance.</returns>
     public OpenIddictClientBuilder AllowImplicitFlow()
         => Configure(options =>
@@ -1013,6 +1018,11 @@ public sealed class OpenIddictClientBuilder
     /// Enables password flow support. For more information about this specific
     /// OAuth 2.0 flow, visit https://tools.ietf.org/html/rfc6749#section-4.3.
     /// </summary>
+    /// <remarks>
+    /// Note: the password flow is not recommended for new applications due to its
+    /// inherent limitations and should only be used in legacy scenarios. When possible,
+    /// consider using an interactive user flow like the authorization code flow instead.
+    /// </remarks>
     /// <returns>The <see cref="OpenIddictClientBuilder"/> instance.</returns>
     public OpenIddictClientBuilder AllowPasswordFlow()
         => Configure(options => options.GrantTypes.Add(GrantTypes.Password));
diff --git a/src/OpenIddict.Server/OpenIddictServerBuilder.cs b/src/OpenIddict.Server/OpenIddictServerBuilder.cs
index 48005fe5..1f802afe 100644
--- a/src/OpenIddict.Server/OpenIddictServerBuilder.cs
+++ b/src/OpenIddict.Server/OpenIddictServerBuilder.cs
@@ -955,6 +955,11 @@ public sealed class OpenIddictServerBuilder
     /// https://tools.ietf.org/html/rfc6749#section-4.2 and
     /// http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth.
     /// </summary>
+    /// <remarks>
+    /// Note: the implicit flow is not recommended for new applications due to
+    /// its inherent limitations and should only be used in legacy scenarios.
+    /// When possible, consider using the authorization code flow instead.
+    /// </remarks>
     /// <returns>The <see cref="OpenIddictServerBuilder"/> instance.</returns>
     public OpenIddictServerBuilder AllowImplicitFlow()
         => Configure(options =>
@@ -978,6 +983,11 @@ public sealed class OpenIddictServerBuilder
     /// Enables password flow support. For more information about this specific
     /// OAuth 2.0 flow, visit https://tools.ietf.org/html/rfc6749#section-4.3.
     /// </summary>
+    /// <remarks>
+    /// Note: the password flow is not recommended for new applications due to its
+    /// inherent limitations and should only be used in legacy scenarios. When possible,
+    /// consider using an interactive user flow like the authorization code flow instead.
+    /// </remarks>
     /// <returns>The <see cref="OpenIddictServerBuilder"/> instance.</returns>
     public OpenIddictServerBuilder AllowPasswordFlow()
         => Configure(options => options.GrantTypes.Add(GrantTypes.Password));