Add docs for remaining security items

src/Security/Authentication/Certificate/src/CertificateAuthenticationExtensions.cs

@@ -36,7 +36,7 @@ public static AuthenticationBuilder AddCertificate(this AuthenticationBuilder bu
         /// </para>
         /// </summary>
         /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
-        /// <param name="authenticationScheme"></param>
+        /// <param name="authenticationScheme">The authentication scheme.</param>
         /// <returns>The <see cref="AuthenticationBuilder"/>.</returns>
         public static AuthenticationBuilder AddCertificate(this AuthenticationBuilder builder, string authenticationScheme)
             => builder.AddCertificate(authenticationScheme, configureOptions: null);
@@ -50,7 +50,7 @@ public static AuthenticationBuilder AddCertificate(this AuthenticationBuilder bu
         /// </para>
         /// </summary>
         /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
-        /// <param name="configureOptions"></param>
+        /// <param name="configureOptions">A delegate to configure <see cref="CertificateAuthenticationOptions"/>.</param>
         /// <returns>The <see cref="AuthenticationBuilder"/>.</returns>
         public static AuthenticationBuilder AddCertificate(this AuthenticationBuilder builder, Action<CertificateAuthenticationOptions> configureOptions)
             => builder.AddCertificate(CertificateAuthenticationDefaults.AuthenticationScheme, configureOptions);
@@ -64,8 +64,8 @@ public static AuthenticationBuilder AddCertificate(this AuthenticationBuilder bu
         /// </para>
         /// </summary>
         /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
-        /// <param name="authenticationScheme"></param>
-        /// <param name="configureOptions"></param>
+        /// <param name="authenticationScheme">The authentication scheme.</param>
+        /// <param name="configureOptions">A delegate to configure <see cref="CertificateAuthenticationOptions"/>.</param>
         /// <returns>The <see cref="AuthenticationBuilder"/>.</returns>
         public static AuthenticationBuilder AddCertificate(
             this AuthenticationBuilder builder,
@@ -82,7 +82,7 @@ public static AuthenticationBuilder AddCertificate(
         /// </para>
         /// </summary>
         /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
-        /// <param name="configureOptions"></param>
+        /// <param name="configureOptions">A delegate to configure <see cref="CertificateValidationCacheOptions"/>.</param>
         /// <returns>The <see cref="AuthenticationBuilder"/>.</returns>
         public static AuthenticationBuilder AddCertificateCache(
             this AuthenticationBuilder builder,

src/Security/Authentication/Facebook/src/FacebookDefaults.cs

@@ -3,17 +3,37 @@
 
 namespace Microsoft.AspNetCore.Authentication.Facebook
 {
+    /// <summary>
+    /// Default values for the Facebook authentication handler.
+    /// </summary>
     public static class FacebookDefaults
     {
+        /// <summary>
+        /// The default scheme for Facebook authentication. The value is <c>Facebook</c>.
+        /// </summary>
         public const string AuthenticationScheme = "Facebook";
 
+        /// <summary>
+        /// The default display name for Facebook authentication. Defaults to <c>Facebook</c>.
+        /// </summary>
         public static readonly string DisplayName = "Facebook";
 
-        // https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow#login
+        /// <summary>
+        /// The default endpoint used to perform Facebook authentication.
+        /// </summary>
+        /// <remarks>
+        /// For more details about this endpoint, see https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow#login.
+        /// </remarks>
         public static readonly string AuthorizationEndpoint = "https://www.facebook.com/v8.0/dialog/oauth";
 
+        /// <summary>
+        /// The OAuth endpoint used to retrieve access tokens.
+        /// </summary>
         public static readonly string TokenEndpoint = "https://graph.facebook.com/v8.0/oauth/access_token";
 
+        /// <summary>
+        /// The Facebook Graph API endpoint that is used to gather additional user information.
+        /// </summary>
         public static readonly string UserInformationEndpoint = "https://graph.facebook.com/v8.0/me";
     }
 }

src/Security/Authentication/Facebook/src/FacebookExtensions.cs

@@ -7,17 +7,61 @@
 
 namespace Microsoft.Extensions.DependencyInjection
 {
+    /// <summary>
+    /// Extension methods to configure Facebook OAuth authentication.
+    /// </summary>
     public static class FacebookAuthenticationOptionsExtensions
     {
+        /// <summary>
+        /// Adds Facebook OAuth-based authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
+        /// The default scheme is specified by <see cref="FacebookDefaults.AuthenticationScheme"/>.
+        /// <para>
+        /// Facebook authentication allows application users to sign in with their Facebook account.
+        /// </para>
+        /// </summary>
+        /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
+        /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
         public static AuthenticationBuilder AddFacebook(this AuthenticationBuilder builder)
             => builder.AddFacebook(FacebookDefaults.AuthenticationScheme, _ => { });
 
+        /// <summary>
+        /// Adds Facebook OAuth-based authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
+        /// The default scheme is specified by <see cref="FacebookDefaults.AuthenticationScheme"/>.
+        /// <para>
+        /// Facebook authentication allows application users to sign in with their Facebook account.
+        /// </para>
+        /// </summary>
+        /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
+        /// <param name="configureOptions">A delegate to configure <see cref="FacebookOptions"/>.</param>
+        /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
         public static AuthenticationBuilder AddFacebook(this AuthenticationBuilder builder, Action<FacebookOptions> configureOptions)
             => builder.AddFacebook(FacebookDefaults.AuthenticationScheme, configureOptions);
 
+        /// <summary>
+        /// Adds Facebook OAuth-based authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
+        /// The default scheme is specified by <see cref="FacebookDefaults.AuthenticationScheme"/>.
+        /// <para>
+        /// Facebook authentication allows application users to sign in with their Facebook account.
+        /// </para>
+        /// </summary>
+        /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
+        /// <param name="authenticationScheme">The authentication scheme.</param>
+        /// <param name="configureOptions">A delegate to configure <see cref="FacebookOptions"/>.</param>
+        /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
         public static AuthenticationBuilder AddFacebook(this AuthenticationBuilder builder, string authenticationScheme, Action<FacebookOptions> configureOptions)
             => builder.AddFacebook(authenticationScheme, FacebookDefaults.DisplayName, configureOptions);
 
+        /// <summary>
+        /// Adds Facebook OAuth-based authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
+        /// The default scheme is specified by <see cref="FacebookDefaults.AuthenticationScheme"/>.
+        /// <para>
+        /// Facebook authentication allows application users to sign in with their Facebook account.
+        /// </para>
+        /// </summary>
+        /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
+        /// <param name="authenticationScheme">The authentication scheme.</param>
+        /// <param name="displayName">A display name for the authentication handler.</param>
+        /// <param name="configureOptions">A delegate to configure <see cref="FacebookOptions"/>.</param>
         public static AuthenticationBuilder AddFacebook(this AuthenticationBuilder builder, string authenticationScheme, string displayName, Action<FacebookOptions> configureOptions)
             => builder.AddOAuth<FacebookOptions, FacebookHandler>(authenticationScheme, displayName, configureOptions);
     }

src/Security/Authentication/Facebook/src/FacebookHandler.cs

@@ -17,12 +17,20 @@
 
 namespace Microsoft.AspNetCore.Authentication.Facebook
 {
+    /// <summary>
+    /// Authentication handler for Facebook's OAuth based authentication.
+    /// </summary>
     public class FacebookHandler : OAuthHandler<FacebookOptions>
     {
+        /// <summary>
+        /// Initializes a new instance of <see cref="FacebookHandler"/>.
+        /// </summary>
+        /// <inheritdoc />
         public FacebookHandler(IOptionsMonitor<FacebookOptions> options, ILoggerFactory logger, UrlEncoder encoder, ISystemClock clock)
             : base(options, logger, encoder, clock)
         { }
 
+        /// <inheritdoc />
         protected override async Task<AuthenticationTicket> CreateTicketAsync(ClaimsIdentity identity, AuthenticationProperties properties, OAuthTokenResponse tokens)
         {
             var endpoint = QueryHelpers.AddQueryString(Options.UserInformationEndpoint, "access_token", tokens.AccessToken);
@@ -64,6 +72,7 @@ private string GenerateAppSecretProof(string accessToken)
             }
         }
 
+        /// <inheritdoc />
         protected override string FormatScope(IEnumerable<string> scopes)
         {
             // Facebook deviates from the OAuth spec here. They require comma separated instead of space separated.
@@ -72,6 +81,7 @@ protected override string FormatScope(IEnumerable<string> scopes)
             return string.Join(",", scopes);
         }
 
+        /// <inheritdoc />
         protected override string FormatScope()
             => base.FormatScope();
     }

src/Security/Authentication/Facebook/src/FacebookOptions.cs

@@ -3,9 +3,8 @@
 
 using System;
 using System.Collections.Generic;
-using System.Security.Claims;
-using Microsoft.AspNetCore.Authentication;
 using System.Globalization;
+using System.Security.Claims;
 using Microsoft.AspNetCore.Authentication.OAuth;
 using Microsoft.AspNetCore.Http;
 
@@ -68,7 +67,7 @@ public override void Validate()
 
         // Facebook uses a non-standard term for this field.
         /// <summary>
-        /// Gets or sets the Facebook-assigned appId.
+        /// Gets or sets the Facebook-assigned App ID.
         /// </summary>
         public string AppId
         {
@@ -87,15 +86,19 @@ public string AppSecret
         }
 
         /// <summary>
-        /// Gets or sets if the appsecret_proof should be generated and sent with Facebook API calls.
-        /// This is enabled by default.
+        /// Gets or sets if the <c>appsecret_proof</c> should be generated and sent with Facebook API calls.
         /// </summary>
+        /// <remarks>See https://developers.facebook.com/docs/graph-api/securing-requests/#appsecret_proof for more details.</remarks>
+        /// <value>Defaults to <see langword="true"/>.</value>
         public bool SendAppSecretProof { get; set; }
 
         /// <summary>
         /// The list of fields to retrieve from the UserInformationEndpoint.
         /// https://developers.facebook.com/docs/graph-api/reference/user
         /// </summary>
+        /// <value>
+        /// Defaults to include the following fields if none are specified: "name", "email", "first_name", and "last_name".
+        /// </value>
         public ICollection<string> Fields { get; } = new HashSet<string>();
     }
 }

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

@@ -1,9 +1,9 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <Description>ASP.NET Core middleware that enables an application to support Facebook's OAuth 2.0 authentication workflow.</Description>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;authentication;security</PackageTags>
   </PropertyGroup>

src/Security/Authentication/Google/src/GoogleChallengeProperties.cs

@@ -1,8 +1,11 @@
-using System.Collections.Generic;
+using System.Collections.Generic;
 using Microsoft.AspNetCore.Authentication.OAuth;
 
 namespace Microsoft.AspNetCore.Authentication.Google
 {
+    /// <summary>
+    /// <see cref="AuthenticationProperties"/> for a Google OAuth challenge.
+    /// </summary>
     public class GoogleChallengeProperties : OAuthChallengeProperties
     {
         /// <summary>
@@ -30,13 +33,24 @@ public class GoogleChallengeProperties : OAuthChallengeProperties
         /// </summary>
         public static readonly string PromptParameterKey = "prompt";
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="GoogleChallengeProperties"/>.
+        /// </summary>
         public GoogleChallengeProperties()
         { }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="GoogleChallengeProperties"/>.
+        /// </summary>
+        /// <inheritdoc />
         public GoogleChallengeProperties(IDictionary<string, string> items)
             : base(items)
         { }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="GoogleChallengeProperties"/>.
+        /// </summary>
+        /// <inheritdoc />
         public GoogleChallengeProperties(IDictionary<string, string> items, IDictionary<string, object> parameters)
             : base(items, parameters)
         { }

src/Security/Authentication/Google/src/GoogleDefaults.cs

@@ -10,16 +10,35 @@ namespace Microsoft.AspNetCore.Authentication.Google
     /// </summary>
     public static class GoogleDefaults
     {
+        /// <summary>
+        /// The default scheme for Google authentication. Defaults to <c>Google</c>.
+        /// </summary>
         public const string AuthenticationScheme = "Google";
 
+        /// <summary>
+        /// The default display name for Google authentication. Defaults to <c>Google</c>.
+        /// </summary>
         public static readonly string DisplayName = "Google";
 
-        // https://developers.google.com/identity/protocols/oauth2/web-server#httprest
+        /// <summary>
+        /// The default endpoint used to perform Google authentication.
+        /// </summary>
+        /// <remarks>
+        /// For more details about this endpoint, see https://developers.google.com/identity/protocols/oauth2/web-server#httprest
+        /// </remarks>
         public static readonly string AuthorizationEndpoint = "https://accounts.google.com/o/oauth2/v2/auth";
 
+        /// <summary>
+        /// The OAuth endpoint used to exchange access tokens.
+        /// </summary>
         public static readonly string TokenEndpoint = "https://oauth2.googleapis.com/token";
 
-        // https://developers.google.com/apis-explorer/#search/oauth2/oauth2/v2/
+        /// <summary>
+        /// The Google endpoint that is used to gather additional user information.
+        /// </summary>
+        /// <remarks>
+        /// For more details about this endpoint, see https://developers.google.com/apis-explorer/#search/oauth2/oauth2/v2/.
+        /// </remarks>
         public static readonly string UserInformationEndpoint = "https://www.googleapis.com/oauth2/v2/userinfo";
     }
 }

src/Security/Authentication/Google/src/GoogleExtensions.cs

@@ -7,17 +7,62 @@
 
 namespace Microsoft.Extensions.DependencyInjection
 {
+    /// <summary>
+    /// Extension methods to configure Google OAuth authentication.
+    /// </summary>
     public static class GoogleExtensions
     {
+        /// <summary>
+        /// Adds Google OAuth-based authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
+        /// The default scheme is specified by <see cref="GoogleDefaults.AuthenticationScheme"/>.
+        /// <para>
+        /// Google authentication allows application users to sign in with their Google account.
+        /// </para>
+        /// </summary>
+        /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
+        /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
         public static AuthenticationBuilder AddGoogle(this AuthenticationBuilder builder)
             => builder.AddGoogle(GoogleDefaults.AuthenticationScheme, _ => { });
 
+        /// <summary>
+        /// Adds Google OAuth-based authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
+        /// The default scheme is specified by <see cref="GoogleDefaults.AuthenticationScheme"/>.
+        /// <para>
+        /// Google authentication allows application users to sign in with their Google account.
+        /// </para>
+        /// </summary>
+        /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
+        /// <param name="configureOptions">A delegate to configure <see cref="GoogleOptions"/>.</param>
+        /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
         public static AuthenticationBuilder AddGoogle(this AuthenticationBuilder builder, Action<GoogleOptions> configureOptions)
             => builder.AddGoogle(GoogleDefaults.AuthenticationScheme, configureOptions);
 
+        /// <summary>
+        /// Adds Google OAuth-based authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
+        /// The default scheme is specified by <see cref="GoogleDefaults.AuthenticationScheme"/>.
+        /// <para>
+        /// Google authentication allows application users to sign in with their Google account.
+        /// </para>
+        /// </summary>
+        /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
+        /// <param name="authenticationScheme">The authentication scheme.</param>
+        /// <param name="configureOptions">A delegate to configure <see cref="GoogleOptions"/>.</param>
+        /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
         public static AuthenticationBuilder AddGoogle(this AuthenticationBuilder builder, string authenticationScheme, Action<GoogleOptions> configureOptions)
             => builder.AddGoogle(authenticationScheme, GoogleDefaults.DisplayName, configureOptions);
 
+        /// <summary>
+        /// Adds Google OAuth-based authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
+        /// The default scheme is specified by <see cref="GoogleDefaults.AuthenticationScheme"/>.
+        /// <para>
+        /// Google authentication allows application users to sign in with their Google account.
+        /// </para>
+        /// </summary>
+        /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
+        /// <param name="authenticationScheme">The authentication scheme.</param>
+        /// <param name="displayName">A display name for the authentication handler.</param>
+        /// <param name="configureOptions">A delegate to configure <see cref="GoogleOptions"/>.</param>
+        /// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
         public static AuthenticationBuilder AddGoogle(this AuthenticationBuilder builder, string authenticationScheme, string displayName, Action<GoogleOptions> configureOptions)
             => builder.AddOAuth<GoogleOptions, GoogleHandler>(authenticationScheme, displayName, configureOptions);
     }