Add docs for Negotiate, OAuth, OpenIdConnect (#26610)

* Add docs for Negotiate, OAuth, OpenIdConnect

Contributes to #26397

Author: pranavkm

src/Security/Authentication/MicrosoftAccount/src/Microsoft.AspNetCore.Authentication.MicrosoftAccount.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <Description>ASP.NET Core middleware that enables an application to support the Microsoft Account authentication workflow.</Description>

src/Security/Authentication/Negotiate/src/Events/AuthenticatedContext.cs

@@ -13,9 +13,7 @@ public class AuthenticatedContext : ResultContext<NegotiateOptions>
         /// <summary>
         /// Creates a new <see cref="AuthenticatedContext"/>.
         /// </summary>
-        /// <param name="context"></param>
-        /// <param name="scheme"></param>
-        /// <param name="options"></param>
+        /// <inheritdoc />
         public AuthenticatedContext(
             HttpContext context,
             AuthenticationScheme scheme,

src/Security/Authentication/Negotiate/src/Events/AuthenticationFailedContext.cs

@@ -14,9 +14,7 @@ public class AuthenticationFailedContext : RemoteAuthenticationContext<Negotiate
         /// <summary>
         /// Creates a <see cref="AuthenticationFailedContext"/>.
         /// </summary>
-        /// <param name="context"></param>
-        /// <param name="scheme"></param>
-        /// <param name="options"></param>
+        /// <inheritdoc />
         public AuthenticationFailedContext(
             HttpContext context,
             AuthenticationScheme scheme,

src/Security/Authentication/Negotiate/src/Events/ChallengeContext.cs

@@ -14,10 +14,7 @@ public class ChallengeContext : PropertiesContext<NegotiateOptions>
         /// <summary>
         /// Creates a new <see cref="ChallengeContext"/>.
         /// </summary>
-        /// <param name="context"></param>
-        /// <param name="scheme"></param>
-        /// <param name="options"></param>
-        /// <param name="properties"></param>
+        /// <inheritdoc />
         public ChallengeContext(
             HttpContext context,
             AuthenticationScheme scheme,
@@ -26,7 +23,8 @@ public ChallengeContext(
             : base(context, scheme, options, properties) { }
 
         /// <summary>
-        /// If true, will skip any default logic for this challenge.
+        /// Gets a value that determines if this challenge was handled.
+        /// If <see langword="true"/>, will skip any default logic for this challenge.
         /// </summary>
         public bool Handled { get; private set; }
 

src/Security/Authentication/Negotiate/src/Events/LdapContext.cs

@@ -13,10 +13,7 @@ public class LdapContext : ResultContext<NegotiateOptions>
         /// <summary>
         /// Creates a new <see cref="LdapContext"/>.
         /// </summary>
-        /// <param name="context"></param>
-        /// <param name="scheme"></param>
-        /// <param name="options"></param>
-        /// <param name="settings"></param>
+        /// <inheritdoc />
         public LdapContext(
             HttpContext context,
             AuthenticationScheme scheme,

src/Security/Authentication/Negotiate/src/LdapSettings.cs

@@ -76,6 +76,9 @@ public class LdapSettings
 
         internal MemoryCache ClaimsCache { get; set; }
 
+        /// <summary>
+        /// Validates the <see cref="LdapSettings"/>.
+        /// </summary>
         public void Validate()
         {
             if (EnableLdapClaimResolution)

src/Security/Authentication/Negotiate/src/Microsoft.AspNetCore.Authentication.Negotiate.csproj

@@ -3,6 +3,7 @@
   <PropertyGroup>
     <Description>ASP.NET Core authentication handler used to authenticate requests using Negotiate, Kerberos, or NTLM.</Description>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;authentication;security</PackageTags>
   </PropertyGroup>

src/Security/Authentication/Negotiate/src/NegotiateExtensions.cs

@@ -17,15 +17,23 @@ namespace Microsoft.Extensions.DependencyInjection
     public static class NegotiateExtensions
     {
         /// <summary>
-        /// Adds Negotiate authentication.
+        /// Configures the <see cref="AuthenticationBuilder"/> to use Negotiate (also known as Windows, Kerberos, or NTLM) authentication
+        /// using the default scheme from <see cref="NegotiateDefaults.AuthenticationScheme"/>.
+        /// <para>
+        /// This authentication handler supports Kerberos on Windows and Linux servers.
+        /// </para>
         /// </summary>
         /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
         /// <returns>The original builder.</returns>
         public static AuthenticationBuilder AddNegotiate(this AuthenticationBuilder builder)
             => builder.AddNegotiate(NegotiateDefaults.AuthenticationScheme, _ => { });
 
         /// <summary>
-        /// Adds and configures Negotiate authentication.
+        /// Configures the <see cref="AuthenticationBuilder"/> to use Negotiate (also known as Windows, Kerberos, or NTLM) authentication
+        /// using the default scheme. The default scheme is specified by <see cref="NegotiateDefaults.AuthenticationScheme"/>.
+        /// <para>
+        /// This authentication handler supports Kerberos on Windows and Linux servers.
+        /// </para>
         /// </summary>
         /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
         /// <param name="configureOptions">Allows for configuring the authentication handler.</param>
@@ -34,7 +42,11 @@ public static AuthenticationBuilder AddNegotiate(this AuthenticationBuilder buil
             => builder.AddNegotiate(NegotiateDefaults.AuthenticationScheme, configureOptions);
 
         /// <summary>
-        /// Adds and configures Negotiate authentication.
+        /// Configures the <see cref="AuthenticationBuilder"/> to use Negotiate (also known as Windows, Kerberos, or NTLM) authentication
+        /// using the specified authentication scheme.
+        /// <para>
+        /// This authentication handler supports Kerberos on Windows and Linux servers.
+        /// </para>
         /// </summary>
         /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
         /// <param name="authenticationScheme">The scheme name used to identify the authentication handler internally.</param>
@@ -44,7 +56,11 @@ public static AuthenticationBuilder AddNegotiate(this AuthenticationBuilder buil
             => builder.AddNegotiate(authenticationScheme, displayName: null, configureOptions: configureOptions);
 
         /// <summary>
-        /// Adds and configures Negotiate authentication.
+        /// Configures the <see cref="AuthenticationBuilder"/> to use Negotiate (also known as Windows, Kerberos, or NTLM) authentication
+        /// using the specified authentication scheme.
+        /// <para>
+        /// This authentication handler supports Kerberos on Windows and Linux servers.
+        /// </para>
         /// </summary>
         /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
         /// <param name="authenticationScheme">The scheme name used to identify the authentication handler internally.</param>

src/Security/Authentication/Negotiate/src/NegotiateHandler.cs

@@ -34,10 +34,7 @@ public class NegotiateHandler : AuthenticationHandler<NegotiateOptions>, IAuthen
         /// <summary>
         /// Creates a new <see cref="NegotiateHandler"/>
         /// </summary>
-        /// <param name="options"></param>
-        /// <param name="logger"></param>
-        /// <param name="encoder"></param>
-        /// <param name="clock"></param>
+        /// <inheritdoc />
         public NegotiateHandler(IOptionsMonitor<NegotiateOptions> options, ILoggerFactory logger, UrlEncoder encoder, ISystemClock clock)
             : base(options, logger, encoder, clock)
         { }
@@ -63,7 +60,7 @@ public NegotiateHandler(IOptionsMonitor<NegotiateOptions> options, ILoggerFactor
         /// <summary>
         /// Intercepts incomplete Negotiate authentication handshakes and continues or completes them.
         /// </summary>
-        /// <returns>True if a response was generated, false otherwise.</returns>
+        /// <returns><see langword="true" /> if a response was generated, otherwise <see langword="false"/>.</returns>
         public async Task<bool> HandleRequestAsync()
         {
             AuthPersistence persistence = null;

src/Security/Authentication/Negotiate/src/NegotiateOptions.cs

@@ -24,15 +24,15 @@ public class NegotiateOptions : AuthenticationSchemeOptions
         /// <summary>
         /// Indicates if Kerberos credentials should be persisted and re-used for subsquent anonymous requests.
         /// This option must not be used if connections may be shared by requests from different users.
-        /// The default is false.
         /// </summary>
+        /// <value>Defaults to <see langword="false"/>.</value>
         public bool PersistKerberosCredentials { get; set; } = false;
 
         /// <summary>
         /// Indicates if NTLM credentials should be persisted and re-used for subsquent anonymous requests.
         /// This option must not be used if connections may be shared by requests from different users.
-        /// The default is true.
         /// </summary>
+        /// <value>Defaults to <see langword="true"/>.</value>
         public bool PersistNtlmCredentials { get; set; } = true;
 
         /// <summary>