Update the XML documentation to discourage using client secrets when possible

src/OpenIddict.Abstractions/Descriptors/OpenIddictApplicationDescriptor.cs

@@ -24,6 +24,12 @@ public class OpenIddictApplicationDescriptor
     /// Note: depending on the application manager used when creating it,
     /// this property may be hashed or encrypted for security reasons.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     public string? ClientSecret { get; set; }
 
     /// <summary>

src/OpenIddict.Abstractions/Managers/IOpenIddictApplicationManager.cs

@@ -76,6 +76,12 @@ public interface IOpenIddictApplicationManager
     /// Note: the default implementation automatically hashes the client
     /// secret before storing it in the database, for security reasons.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     /// <param name="application">The application to create.</param>
     /// <param name="secret">The client secret associated with the application, if applicable.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> that can be used to abort the operation.</param>
@@ -496,13 +502,19 @@ public interface IOpenIddictApplicationManager
     /// Note: the default implementation automatically hashes the client
     /// secret before storing it in the database, for security reasons.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     /// <param name="application">The application to update.</param>
     /// <param name="secret">The client secret associated with the application.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> that can be used to abort the operation.</param>
     /// <returns>
     /// A <see cref="ValueTask"/> that can be used to monitor the asynchronous operation.
     /// </returns>
-    ValueTask UpdateAsync(object application, string secret, CancellationToken cancellationToken = default);
+    ValueTask UpdateAsync(object application, string? secret, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Validates the application to ensure it's in a consistent state.
@@ -515,6 +527,12 @@ public interface IOpenIddictApplicationManager
     /// <summary>
     /// Validates the client_secret associated with an application.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     /// <param name="application">The application.</param>
     /// <param name="secret">The secret that should be compared to the client_secret stored in the database.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> that can be used to abort the operation.</param>

src/OpenIddict.Abstractions/Primitives/OpenIddictRequest.cs

@@ -218,6 +218,12 @@ public class OpenIddictRequest : OpenIddictMessage
     /// <summary>
     /// Gets or sets the "client_secret" parameter.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     public string? ClientSecret
     {
         get => (string?) GetParameter(OpenIddictConstants.Parameters.ClientSecret);

src/OpenIddict.Abstractions/Stores/IOpenIddictApplicationStore.cs

@@ -139,6 +139,12 @@ public interface IOpenIddictApplicationStore<TApplication> where TApplication :
     /// Note: depending on the manager used to create the application,
     /// the client secret may be hashed for security reasons.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     /// <param name="application">The application.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> that can be used to abort the operation.</param>
     /// <returns>
@@ -334,6 +340,12 @@ public interface IOpenIddictApplicationStore<TApplication> where TApplication :
     /// Note: depending on the manager used to create the application,
     /// the client secret may be hashed for security reasons.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     /// <param name="application">The application.</param>
     /// <param name="secret">The client secret associated with the application.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> that can be used to abort the operation.</param>

src/OpenIddict.Client/OpenIddictClientRegistration.cs

@@ -30,6 +30,12 @@ public sealed class OpenIddictClientRegistration
     /// <summary>
     /// Gets or sets the client secret assigned by the authorization server, if applicable.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     public string? ClientSecret { get; set; }
 
     /// <summary>

src/OpenIddict.Core/Managers/OpenIddictApplicationManager.cs

@@ -122,6 +122,12 @@ public class OpenIddictApplicationManager<TApplication> : IOpenIddictApplication
     /// Note: the default implementation automatically hashes the client
     /// secret before storing it in the database, for security reasons.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     /// <param name="application">The application to create.</param>
     /// <param name="secret">The client secret associated with the application, if applicable.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> that can be used to abort the operation.</param>
@@ -1157,6 +1163,12 @@ public class OpenIddictApplicationManager<TApplication> : IOpenIddictApplication
     /// Note: the default implementation automatically hashes the client
     /// secret before storing it in the database, for security reasons.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     /// <param name="application">The application to update.</param>
     /// <param name="secret">The client secret associated with the application.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> that can be used to abort the operation.</param>
@@ -1334,6 +1346,12 @@ public class OpenIddictApplicationManager<TApplication> : IOpenIddictApplication
     /// <summary>
     /// Validates the client_secret associated with an application.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     /// <param name="application">The application.</param>
     /// <param name="secret">The secret that should be compared to the client_secret stored in the database.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> that can be used to abort the operation.</param>

src/OpenIddict.EntityFramework.Models/OpenIddictEntityFrameworkApplication.cs

@@ -50,6 +50,12 @@ public class OpenIddictEntityFrameworkApplication<TKey, TAuthorization, TToken>
     /// Note: depending on the application manager used to create this instance,
     /// this property may be hashed or encrypted for security reasons.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     public virtual string? ClientSecret { get; set; }
 
     /// <summary>

src/OpenIddict.EntityFrameworkCore.Models/OpenIddictEntityFrameworkCoreApplication.cs

@@ -58,6 +58,12 @@ public class OpenIddictEntityFrameworkCoreApplication<TKey, TAuthorization, TTok
     /// Note: depending on the application manager used to create this instance,
     /// this property may be hashed or encrypted for security reasons.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     public virtual string? ClientSecret { get; set; }
 
     /// <summary>

src/OpenIddict.MongoDb.Models/OpenIddictMongoDbApplication.cs

@@ -32,6 +32,12 @@ public class OpenIddictMongoDbApplication
     /// Note: depending on the application manager used to create this instance,
     /// this property may be hashed or encrypted for security reasons.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     [BsonElement("client_secret"), BsonIgnoreIfNull]
     public virtual string? ClientSecret { get; set; }
 

src/OpenIddict.Server/OpenIddictServerEvents.cs

@@ -148,6 +148,12 @@ public static partial class OpenIddictServerEvents
         /// The authorization server application is responsible for
         /// validating this value to ensure it identifies a registered client.
         /// </summary>
+        /// <remarks>
+        /// Note: client authentication based on shared secrets is not recommended and should
+        /// only be used for backward compatibility with legacy applications that only support
+        /// client secrets. When possible, consider using public/private key pairs or TLS client
+        /// certificates instead, as these client authentication methods are significantly safer.
+        /// </remarks>
         public string? ClientSecret => Transaction.Request?.ClientSecret;
     }
 

src/OpenIddict.Validation/OpenIddictValidationBuilder.cs

@@ -672,6 +672,12 @@ public sealed class OpenIddictValidationBuilder
     /// Sets the client identifier client_secret used when communicating
     /// with the remote authorization server (e.g for introspection).
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     /// <param name="secret">The client secret.</param>
     /// <returns>The <see cref="OpenIddictValidationBuilder"/> instance.</returns>
     public OpenIddictValidationBuilder SetClientSecret(string secret)

src/OpenIddict.Validation/OpenIddictValidationOptions.cs

@@ -85,6 +85,12 @@ public sealed class OpenIddictValidationOptions
     /// <summary>
     /// Gets or sets the client secret sent to the authorization server when using remote validation.
     /// </summary>
+    /// <remarks>
+    /// Note: client authentication based on shared secrets is not recommended and should
+    /// only be used for backward compatibility with legacy applications that only support
+    /// client secrets. When possible, consider using public/private key pairs or TLS client
+    /// certificates instead, as these client authentication methods are significantly safer.
+    /// </remarks>
     public string? ClientSecret { get; set; }
 
     /// <summary>