Add docs for Authentication.Abstractions

Contributes to #26397

Author: pranavkm

src/Http/Authentication.Abstractions/src/AuthenticationHttpContextExtensions.cs

@@ -14,15 +14,16 @@ namespace Microsoft.AspNetCore.Authentication
     public static class AuthenticationHttpContextExtensions
     {
         /// <summary>
-        /// Extension method for authenticate using the <see cref="AuthenticationOptions.DefaultAuthenticateScheme"/> scheme.
+        /// Authenticate the current request using the default authentication scheme.
+        /// The default authentication scheme can be configured using <see cref="AuthenticationOptions.DefaultAuthenticateScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <returns>The <see cref="AuthenticateResult"/>.</returns>
         public static Task<AuthenticateResult> AuthenticateAsync(this HttpContext context) =>
             context.AuthenticateAsync(scheme: null);
 
         /// <summary>
-        /// Extension method for authenticate.
+        /// Authenticate the current request using the specified scheme.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -31,7 +32,8 @@ public static Task<AuthenticateResult> AuthenticateAsync(this HttpContext contex
             context.RequestServices.GetRequiredService<IAuthenticationService>().AuthenticateAsync(context, scheme);
 
         /// <summary>
-        /// Extension method for Challenge.
+        /// Challenge the current request using the specified scheme.
+        /// An authentication challenge can be issued when an unauthenticated user requests an endpoint that requires authentication.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -40,15 +42,19 @@ public static Task ChallengeAsync(this HttpContext context, string? scheme) =>
             context.ChallengeAsync(scheme, properties: null);
 
         /// <summary>
-        /// Extension method for authenticate using the <see cref="AuthenticationOptions.DefaultChallengeScheme"/> scheme.
+        /// Challenge the current request using the default challenge scheme.
+        /// An authentication challenge can be issued when an unauthenticated user requests an endpoint that requires authentication.
+        /// The default challenge scheme can be configured using <see cref="AuthenticationOptions.DefaultChallengeScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <returns>The task.</returns>
         public static Task ChallengeAsync(this HttpContext context) =>
             context.ChallengeAsync(scheme: null, properties: null);
 
         /// <summary>
-        /// Extension method for authenticate using the <see cref="AuthenticationOptions.DefaultChallengeScheme"/> scheme.
+        /// Challenge the current request using the default challenge scheme.
+        /// An authentication challenge can be issued when an unauthenticated user requests an endpoint that requires authentication.
+        /// The default challenge scheme can be configured using <see cref="AuthenticationOptions.DefaultChallengeScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="properties">The <see cref="AuthenticationProperties"/> properties.</param>
@@ -57,7 +63,8 @@ public static Task ChallengeAsync(this HttpContext context, AuthenticationProper
             context.ChallengeAsync(scheme: null, properties: properties);
 
         /// <summary>
-        /// Extension method for Challenge.
+        /// Challenge the current request using the specified scheme.
+        /// An authentication challenge can be issued when an unauthenticated user requests an endpoint that requires authentication.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -67,7 +74,8 @@ public static Task ChallengeAsync(this HttpContext context, string? scheme, Auth
             context.RequestServices.GetRequiredService<IAuthenticationService>().ChallengeAsync(context, scheme, properties);
 
         /// <summary>
-        /// Extension method for Forbid.
+        /// Forbid the current request using the specified scheme.
+        /// Forbid is used when an authenticated user attempts to access a resource they are not permitted to access.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -76,15 +84,19 @@ public static Task ForbidAsync(this HttpContext context, string? scheme) =>
             context.ForbidAsync(scheme, properties: null);
 
         /// <summary>
-        /// Extension method for Forbid using the <see cref="AuthenticationOptions.DefaultForbidScheme"/> scheme..
+        /// Forbid the current request using the default forbid scheme.
+        /// Forbid is used when an authenticated user attempts to access a resource they are not permitted to access.
+        /// The default forbid scheme can be configured using <see cref="AuthenticationOptions.DefaultForbidScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <returns>The task.</returns>
         public static Task ForbidAsync(this HttpContext context) =>
             context.ForbidAsync(scheme: null, properties: null);
 
         /// <summary>
-        /// Extension method for Forbid.
+        /// Forbid the current request using the default forbid scheme.
+        /// Forbid is used when an authenticated user attempts to access a resource they are not permitted to access.
+        /// The default forbid scheme can be configured using <see cref="AuthenticationOptions.DefaultForbidScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="properties">The <see cref="AuthenticationProperties"/> properties.</param>
@@ -93,7 +105,8 @@ public static Task ForbidAsync(this HttpContext context, AuthenticationPropertie
             context.ForbidAsync(scheme: null, properties: properties);
 
         /// <summary>
-        /// Extension method for Forbid.
+        /// Forbid the current request using the specified scheme.
+        /// Forbid is used when an authenticated user attempts to access a resource they are not permitted to access.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -103,7 +116,7 @@ public static Task ForbidAsync(this HttpContext context, string? scheme, Authent
             context.RequestServices.GetRequiredService<IAuthenticationService>().ForbidAsync(context, scheme, properties);
 
         /// <summary>
-        /// Extension method for SignIn.
+        /// Sign in a principal for the specified scheme.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -113,7 +126,8 @@ public static Task SignInAsync(this HttpContext context, string? scheme, ClaimsP
             context.SignInAsync(scheme, principal, properties: null);
 
         /// <summary>
-        /// Extension method for SignIn using the <see cref="AuthenticationOptions.DefaultSignInScheme"/>.
+        /// Sign in a principal for the default authentication scheme.
+        /// The default scheme for signing in can be configured using <see cref="AuthenticationOptions.DefaultSignInScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="principal">The user.</param>
@@ -122,7 +136,8 @@ public static Task SignInAsync(this HttpContext context, ClaimsPrincipal princip
             context.SignInAsync(scheme: null, principal: principal, properties: null);
 
         /// <summary>
-        /// Extension method for SignIn using the <see cref="AuthenticationOptions.DefaultSignInScheme"/>.
+        /// Sign in a principal for the default authentication scheme.
+        /// The default scheme for signing in can be configured using <see cref="AuthenticationOptions.DefaultForbidScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="principal">The user.</param>
@@ -132,7 +147,7 @@ public static Task SignInAsync(this HttpContext context, ClaimsPrincipal princip
             context.SignInAsync(scheme: null, principal: principal, properties: properties);
 
         /// <summary>
-        /// Extension method for SignIn.
+        /// Sign in a principal for the specified scheme.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -143,30 +158,32 @@ public static Task SignInAsync(this HttpContext context, string? scheme, ClaimsP
             context.RequestServices.GetRequiredService<IAuthenticationService>().SignInAsync(context, scheme, principal, properties);
 
         /// <summary>
-        /// Extension method for SignOut using the <see cref="AuthenticationOptions.DefaultSignOutScheme"/>.
+        /// Sign out a principal for the default authentication scheme.
+        /// The default scheme for signing out can be configured using <see cref="AuthenticationOptions.DefaultSignOutScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <returns>The task.</returns>
         public static Task SignOutAsync(this HttpContext context) => context.SignOutAsync(scheme: null, properties: null);
 
         /// <summary>
-        /// Extension method for SignOut using the <see cref="AuthenticationOptions.DefaultSignOutScheme"/>.
+        /// Sign out a principal for the default authentication scheme.
+        /// The default scheme for signing out can be configured using <see cref="AuthenticationOptions.DefaultSignOutScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="properties">The <see cref="AuthenticationProperties"/> properties.</param>
         /// <returns>The task.</returns>
         public static Task SignOutAsync(this HttpContext context, AuthenticationProperties? properties) => context.SignOutAsync(scheme: null, properties: properties);
 
         /// <summary>
-        /// Extension method for SignOut.
+        /// Sign out a principal for the specified scheme.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
         /// <returns>The task.</returns>
         public static Task SignOutAsync(this HttpContext context, string? scheme) => context.SignOutAsync(scheme, properties: null);
 
         /// <summary>
-        /// Extension method for SignOut.
+        /// Sign out a principal for the specified scheme.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -176,21 +193,22 @@ public static Task SignOutAsync(this HttpContext context, string? scheme, Authen
             context.RequestServices.GetRequiredService<IAuthenticationService>().SignOutAsync(context, scheme, properties);
 
         /// <summary>
-        /// Extension method for getting the value of an authentication token.
+        /// Authenticates the request using the specified scheme and returns the value for the token.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
         /// <param name="tokenName">The name of the token.</param>
-        /// <returns>The value of the token.</returns>
+        /// <returns>The value of the token if present.</returns>
         public static Task<string?> GetTokenAsync(this HttpContext context, string? scheme, string tokenName) =>
             context.RequestServices.GetRequiredService<IAuthenticationService>().GetTokenAsync(context, scheme, tokenName);
 
         /// <summary>
-        /// Extension method for getting the value of an authentication token.
+        /// Authenticates the request using the default authentication scheme and returns the value for the token.
+        /// The default authentication scheme can be configured using <see cref="AuthenticationOptions.DefaultAuthenticateScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="tokenName">The name of the token.</param>
-        /// <returns>The value of the token.</returns>
+        /// <returns>The value of the token if present.</returns>
         public static Task<string?> GetTokenAsync(this HttpContext context, string tokenName) =>
             context.RequestServices.GetRequiredService<IAuthenticationService>().GetTokenAsync(context, tokenName);
     }

src/Http/Authentication.Abstractions/src/AuthenticationOptions.cs

@@ -9,6 +9,9 @@
 
 namespace Microsoft.AspNetCore.Authentication
 {
+    /// <summary>
+    /// Options to configure authentication.
+    /// </summary>
     public class AuthenticationOptions
     {
         private readonly IList<AuthenticationSchemeBuilder> _schemes = new List<AuthenticationSchemeBuilder>();
@@ -93,7 +96,8 @@ public void AddScheme(string name, Action<AuthenticationSchemeBuilder> configure
         public string? DefaultForbidScheme { get; set; }
 
         /// <summary>
-        /// If true, SignIn should throw if attempted with a ClaimsPrincipal.Identity.IsAuthenticated = false.
+        /// If true, SignIn should throw if attempted with a user is not authenticated.
+        /// A user is considered authenticated if <see cref="ClaimsIdentity.IsAuthenticated"/> returns <see langword="true" /> for the <see cref="ClaimsPrincipal"/> associated with the HTTP request.
         /// </summary>
         public bool RequireAuthenticatedSignIn { get; set; } = true;
     }

src/Http/Authentication.Abstractions/src/AuthenticationProperties.cs

@@ -3,7 +3,6 @@
 
 using System;
 using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
 using System.Globalization;
 
 namespace Microsoft.AspNetCore.Authentication
@@ -122,10 +121,10 @@ public bool? AllowRefresh
         }
 
         /// <summary>
-        /// Set a string value in the <see cref="Items"/> collection.
+        /// Sets or remove a string value from the <see cref="Items"/> collection.
         /// </summary>
         /// <param name="key">Property key.</param>
-        /// <param name="value">Value to set or <c>null</c> to remove the property.</param>
+        /// <param name="value">Value to set or <see langword="null" /> to remove the property.</param>
         public void SetString(string key, string? value)
         {
             if (value != null)
@@ -157,10 +156,10 @@ public void SetParameter<T>(string key, T value)
             => Parameters[key] = value;
 
         /// <summary>
-        /// Get a bool value from the <see cref="Items"/> collection.
+        /// Get a nullable <see cref="bool"/> from the <see cref="Items"/> collection.
         /// </summary>
         /// <param name="key">Property key.</param>
-        /// <returns>Retrieved value or <c>null</c> if the property is not set.</returns>
+        /// <returns>Retrieved value or <see langword="null" /> if the property is not set.</returns>
         protected bool? GetBool(string key)
         {
             if (Items.TryGetValue(key, out var value) && bool.TryParse(value, out var boolValue))
@@ -171,10 +170,10 @@ public void SetParameter<T>(string key, T value)
         }
 
         /// <summary>
-        /// Set a bool value in the <see cref="Items"/> collection.
+        /// Set or removes a <see cref="bool"/> value in the <see cref="Items"/> collection.
         /// </summary>
         /// <param name="key">Property key.</param>
-        /// <param name="value">Value to set or <c>null</c> to remove the property.</param>
+        /// <param name="value">Value to set or <see langword="null" /> to remove the property.</param>
         protected void SetBool(string key, bool? value)
         {
             if (value.HasValue)
@@ -188,10 +187,10 @@ protected void SetBool(string key, bool? value)
         }
 
         /// <summary>
-        /// Get a DateTimeOffset value from the <see cref="Items"/> collection.
+        /// Get a nullable <see cref="DateTimeOffset"/> value from the <see cref="Items"/> collection.
         /// </summary>
         /// <param name="key">Property key.</param>
-        /// <returns>Retrieved value or <c>null</c> if the property is not set.</returns>
+        /// <returns>Retrieved value or <see langword="null" /> if the property is not set.</returns>
         protected DateTimeOffset? GetDateTimeOffset(string key)
         {
             if (Items.TryGetValue(key, out var value)
@@ -203,10 +202,10 @@ protected void SetBool(string key, bool? value)
         }
 
         /// <summary>
-        /// Set a DateTimeOffset value in the <see cref="Items"/> collection.
+        /// Sets or removes a <see cref="DateTimeOffset" /> value in the <see cref="Items"/> collection.
         /// </summary>
         /// <param name="key">Property key.</param>
-        /// <param name="value">Value to set or <c>null</c> to remove the property.</param>
+        /// <param name="value">Value to set or <see langword="null" /> to remove the property.</param>
         protected void SetDateTimeOffset(string key, DateTimeOffset? value)
         {
             if (value.HasValue)

src/Http/Authentication.Abstractions/src/AuthenticationScheme.cs

@@ -13,7 +13,7 @@ namespace Microsoft.AspNetCore.Authentication
     public class AuthenticationScheme
     {
         /// <summary>
-        /// Constructor.
+        /// Initializes a new instance of <see cref="AuthenticationScheme"/>.
         /// </summary>
         /// <param name="name">The name for the authentication scheme.</param>
         /// <param name="displayName">The display name for the authentication scheme.</param>

src/Http/Authentication.Abstractions/src/AuthenticationSchemeBuilder.cs

@@ -21,25 +21,25 @@ public AuthenticationSchemeBuilder(string name)
         }
 
         /// <summary>
-        /// The name of the scheme being built.
+        /// Gets the name of the scheme being built.
         /// </summary>
         public string Name { get; }
 
         /// <summary>
-        /// The display name for the scheme being built.
+        /// Gets or sets the display name for the scheme being built.
         /// </summary>
         public string? DisplayName { get; set; }
 
         /// <summary>
-        /// The <see cref="IAuthenticationHandler"/> type responsible for this scheme.
+        /// Gets or sets the <see cref="IAuthenticationHandler"/> type responsible for this scheme.
         /// </summary>
         [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)]
         public Type? HandlerType { get; set; }
 
         /// <summary>
         /// Builds the <see cref="AuthenticationScheme"/> instance.
         /// </summary>
-        /// <returns></returns>
+        /// <returns>The <see cref="AuthenticationScheme"/>.</returns>
         public AuthenticationScheme Build()
         {
             if (HandlerType is null)