Add docs for Negotiate, OAuth, OpenIdConnect

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>

src/Security/Authentication/OAuth/src/ClaimAction.cs

@@ -23,11 +23,13 @@ public ClaimAction(string claimType, string valueType)
         }
 
         /// <summary>
-        /// The value to use for Claim.Type when creating a Claim.
+        /// Gets the value to use for <see cref="Claim.Value"/>when creating a Claim.
         /// </summary>
         public string ClaimType { get; }
 
-        // The value to use for Claim.ValueType when creating a Claim.
+        /// <summary>
+        /// Gets the value to use for <see cref="Claim.ValueType"/> when creating a Claim. 
+        /// </summary>
         public string ValueType { get; }
 
         /// <summary>

src/Security/Authentication/OAuth/src/ClaimActionCollection.cs

@@ -1,4 +1,4 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
@@ -39,6 +39,7 @@ public void Add(ClaimAction action)
             Actions.Add(action);
         }
 
+        /// <inheritdoc />
         public IEnumerator<ClaimAction> GetEnumerator()
         {
             return Actions.GetEnumerator();
@@ -49,4 +50,4 @@ IEnumerator IEnumerable.GetEnumerator()
             return Actions.GetEnumerator();
         }
     }
-}
+}

src/Security/Authentication/OAuth/src/ClaimActionCollectionMapExtensions.cs

@@ -8,13 +8,16 @@
 
 namespace Microsoft.AspNetCore.Authentication
 {
+    /// <summary>
+    /// Extension methods for <see cref="ClaimActionCollection"/>.
+    /// </summary>
     public static class ClaimActionCollectionMapExtensions
     {
         /// <summary>
         /// Select a top level value from the json user data with the given key name and add it as a Claim.
         /// This no-ops if the key is not found or the value is empty.
         /// </summary>
-        /// <param name="collection"></param>
+        /// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
         /// <param name="claimType">The value to use for Claim.Type when creating a Claim.</param>
         /// <param name="jsonKey">The top level key to look for in the json user data.</param>
         public static void MapJsonKey(this ClaimActionCollection collection, string claimType, string jsonKey)
@@ -26,7 +29,7 @@ public static void MapJsonKey(this ClaimActionCollection collection, string clai
         /// Select a top level value from the json user data with the given key name and add it as a Claim.
         /// This no-ops if the key is not found or the value is empty.
         /// </summary>
-        /// <param name="collection"></param>
+        /// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
         /// <param name="claimType">The value to use for Claim.Type when creating a Claim.</param>
         /// <param name="jsonKey">The top level key to look for in the json user data.</param>
         /// <param name="valueType">The value to use for Claim.ValueType when creating a Claim.</param>
@@ -39,7 +42,7 @@ public static void MapJsonKey(this ClaimActionCollection collection, string clai
         /// Select a second level value from the json user data with the given top level key name and second level sub key name and add it as a Claim.
         /// This no-ops if the keys are not found or the value is empty.
         /// </summary>
-        /// <param name="collection"></param>
+        /// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
         /// <param name="claimType">The value to use for Claim.Type when creating a Claim.</param>
         /// <param name="jsonKey">The top level key to look for in the json user data.</param>
         /// <param name="subKey">The second level key to look for in the json user data.</param>
@@ -52,7 +55,7 @@ public static void MapJsonSubKey(this ClaimActionCollection collection, string c
         /// Select a second level value from the json user data with the given top level key name and second level sub key name and add it as a Claim.
         /// This no-ops if the keys are not found or the value is empty.
         /// </summary>
-        /// <param name="collection"></param>
+        /// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
         /// <param name="claimType">The value to use for Claim.Type when creating a Claim.</param>
         /// <param name="jsonKey">The top level key to look for in the json user data.</param>
         /// <param name="subKey">The second level key to look for in the json user data.</param>
@@ -66,7 +69,7 @@ public static void MapJsonSubKey(this ClaimActionCollection collection, string c
         /// Run the given resolver to select a value from the json user data to add as a claim.
         /// This no-ops if the returned value is empty.
         /// </summary>
-        /// <param name="collection"></param>
+        /// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
         /// <param name="claimType">The value to use for Claim.Type when creating a Claim.</param>
         /// <param name="resolver">The Func that will be called to select value from the given json user data.</param>
         public static void MapCustomJson(this ClaimActionCollection collection, string claimType, Func<JsonElement, string> resolver)
@@ -78,7 +81,7 @@ public static void MapCustomJson(this ClaimActionCollection collection, string c
         /// Run the given resolver to select a value from the json user data to add as a claim.
         /// This no-ops if the returned value is empty.
         /// </summary>
-        /// <param name="collection"></param>
+        /// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
         /// <param name="claimType">The value to use for Claim.Type when creating a Claim.</param>
         /// <param name="valueType">The value to use for Claim.ValueType when creating a Claim.</param>
         /// <param name="resolver">The Func that will be called to select value from the given json user data.</param>
@@ -90,7 +93,7 @@ public static void MapCustomJson(this ClaimActionCollection collection, string c
         /// <summary>
         /// Clears any current ClaimsActions and maps all values from the json user data as claims, excluding duplicates.
         /// </summary>
-        /// <param name="collection"></param>
+        /// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
         public static void MapAll(this ClaimActionCollection collection)
         {
             collection.Clear();
@@ -100,8 +103,8 @@ public static void MapAll(this ClaimActionCollection collection)
         /// <summary>
         /// Clears any current ClaimsActions and maps all values from the json user data as claims, excluding the specified types.
         /// </summary>
-        /// <param name="collection"></param>
-        /// <param name="exclusions"></param>
+        /// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
+        /// <param name="exclusions">The types to exclude.</param>
         public static void MapAllExcept(this ClaimActionCollection collection, params string[] exclusions)
         {
             collection.MapAll();
@@ -111,8 +114,8 @@ public static void MapAllExcept(this ClaimActionCollection collection, params st
         /// <summary>
         /// Delete all claims from the given ClaimsIdentity with the given ClaimType.
         /// </summary>
-        /// <param name="collection"></param>
-        /// <param name="claimType"></param>
+        /// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
+        /// <param name="claimType">The claim type to delete</param>
         public static void DeleteClaim(this ClaimActionCollection collection, string claimType)
         {
             collection.Add(new DeleteClaimAction(claimType));
@@ -121,8 +124,8 @@ public static void DeleteClaim(this ClaimActionCollection collection, string cla
         /// <summary>
         /// Delete all claims from the ClaimsIdentity with the given claimTypes.
         /// </summary>
-        /// <param name="collection"></param>
-        /// <param name="claimTypes"></param>
+        /// <param name="collection">The <see cref="ClaimActionCollection"/>.</param>
+        /// <param name="claimTypes">The claim types to delete.</param>
         public static void DeleteClaims(this ClaimActionCollection collection, params string[] claimTypes)
         {
             if (claimTypes == null)

src/Security/Authentication/OAuth/src/Events/OAuthCreatingTicketContext.cs

@@ -108,8 +108,16 @@ public TimeSpan? ExpiresIn
         /// </summary>
         public ClaimsIdentity Identity => Principal?.Identity as ClaimsIdentity;
 
+        /// <summary>
+        /// Examines <see cref="User"/>, determine if the requisite data is present, and optionally add it
+        /// to <see cref="Identity"/>.
+        /// </summary>
         public void RunClaimActions() => RunClaimActions(User);
 
+        /// <summary>
+        /// Examines the specified <paramref name="userData"/>, determine if the requisite data is present, and optionally add it
+        /// to <see cref="Identity"/>.
+        /// </summary>
         public void RunClaimActions(JsonElement userData)
         {
             foreach (var action in Options.ClaimActions)

src/Security/Authentication/OAuth/src/MapAllClaimsAction.cs

@@ -13,10 +13,14 @@ namespace Microsoft.AspNetCore.Authentication.OAuth.Claims
     /// </summary>
     public class MapAllClaimsAction : ClaimAction
     {
+        /// <summary>
+        /// Initializes a new instance of <see cref="MapAllClaimsAction"/>.
+        /// </summary>
         public MapAllClaimsAction() : base("All", ClaimValueTypes.String)
         {
         }
 
+        /// <inheritdoc />
         public override void Run(JsonElement userData, ClaimsIdentity identity, string issuer)
         {
             foreach (var pair in userData.EnumerateObject())

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

@@ -4,7 +4,7 @@
     <Description>ASP.NET Core middleware that enables an application to support any standard OAuth 2.0 authentication workflow.</Description>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;authentication;security</PackageTags>
     <IsPackable>false</IsPackable>