Add docs for Auth, Auth.Cookies, Auth.Certificate (#26503)

* Add docs for Auth, Auth.Cookies, Auth.Certificate

Contributes to #26397

* Also add JWT

* Apply suggestions from code review

Co-authored-by: Hao Kung <[email protected]>
Co-authored-by: Chris Ross <[email protected]>

* Update src/Security/Authentication/Core/src/TicketSerializer.cs

* Update src/Security/Authentication/Core/src/TicketSerializer.cs

* Update src/Security/Authentication/Core/src/TicketSerializer.cs

* Apply suggestions from code review

Co-authored-by: Hao Kung <[email protected]>
Co-authored-by: Chris Ross <[email protected]>

Author: 3 people

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

@@ -2,6 +2,7 @@
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
+using System.Security.Claims;
 using Microsoft.AspNetCore.Authentication;
 
 using Microsoft.AspNetCore.Authentication.Certificate;
@@ -15,6 +16,11 @@ public static class CertificateAuthenticationAppBuilderExtensions
     {
         /// <summary>
         /// Adds certificate authentication.
+        /// <para>
+        /// Certificate authentication uses a authentication handler that validates client certificate and
+        /// raises an event where the certificate is resolved to a <see cref="ClaimsPrincipal"/>.
+        /// See https://tools.ietf.org/html/rfc5246#section-7.4.4 to read more about certicate authentication.
+        /// </para>
         /// </summary>
         /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
         /// <returns>The <see cref="AuthenticationBuilder"/>.</returns>
@@ -23,6 +29,11 @@ public static AuthenticationBuilder AddCertificate(this AuthenticationBuilder bu
 
         /// <summary>
         /// Adds certificate authentication.
+        /// <para>
+        /// Certificate authentication uses a authentication handler that validates client certificate and
+        /// raises an event where the certificate is resolved to a <see cref="ClaimsPrincipal"/>.
+        /// See https://tools.ietf.org/html/rfc5246#section-7.4.4 to read more about certicate authentication.
+        /// </para>
         /// </summary>
         /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
         /// <param name="authenticationScheme"></param>
@@ -32,6 +43,11 @@ public static AuthenticationBuilder AddCertificate(this AuthenticationBuilder bu
 
         /// <summary>
         /// Adds certificate authentication.
+        /// <para>
+        /// Certificate authentication uses a authentication handler that validates client certificate and
+        /// raises an event where the certificate is resolved to a <see cref="ClaimsPrincipal"/>.
+        /// See https://tools.ietf.org/html/rfc5246#section-7.4.4 to read more about certicate authentication.
+        /// </para>
         /// </summary>
         /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
         /// <param name="configureOptions"></param>
@@ -41,6 +57,11 @@ public static AuthenticationBuilder AddCertificate(this AuthenticationBuilder bu
 
         /// <summary>
         /// Adds certificate authentication.
+        /// <para>
+        /// Certificate authentication uses a authentication handler that validates client certificate and
+        /// raises an event where the certificate is resolved to a <see cref="ClaimsPrincipal"/>.
+        /// See https://tools.ietf.org/html/rfc5246#section-7.4.4 to read more about certicate authentication.
+        /// </para>
         /// </summary>
         /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
         /// <param name="authenticationScheme"></param>
@@ -54,6 +75,11 @@ public static AuthenticationBuilder AddCertificate(
 
         /// <summary>
         /// Adds certificate authentication.
+        /// <para>
+        /// Certificate authentication uses a authentication handler that validates client certificate and
+        /// raises an event where the certificate is resolved to a <see cref="ClaimsPrincipal"/>.
+        /// See https://tools.ietf.org/html/rfc5246#section-7.4.4 to read more about certicate authentication.
+        /// </para>
         /// </summary>
         /// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
         /// <param name="configureOptions"></param>

src/Security/Authentication/Certificate/src/CertificateAuthenticationOptions.cs

@@ -13,6 +13,9 @@ public class CertificateAuthenticationOptions : AuthenticationSchemeOptions
         /// <summary>
         /// Value indicating the types of certificates accepted by the authentication middleware.
         /// </summary>
+        /// <value>
+        /// Defaults to <see cref="CertificateTypes.Chained"/>.
+        /// </value>
         public CertificateTypes AllowedCertificateTypes { get; set; } = CertificateTypes.Chained;
 
         /// <summary>
@@ -23,6 +26,9 @@ public class CertificateAuthenticationOptions : AuthenticationSchemeOptions
         /// <summary>
         /// Method used to validate certificate chains against <see cref="CustomTrustStore"/>.
         /// </summary>
+        /// <value>
+        /// Defaults to <see cref="X509ChainTrustMode.System"/>.
+        /// </value>
         /// <remarks>This property must be set to <see cref="X509ChainTrustMode.CustomRootTrust"/> to enable <see cref="CustomTrustStore"/> to be used in certificate chain validation.</remarks>
         public X509ChainTrustMode ChainTrustValidationMode { get; set; } = X509ChainTrustMode.System;
 
@@ -32,21 +38,33 @@ public class CertificateAuthenticationOptions : AuthenticationSchemeOptions
         /// at all. If the certificate chains to a root CA all certificates in the chain must be validated
         /// for the client authentication EKU.
         /// </summary>
+        /// <value>
+        /// Defaults to <see langword="true" />.
+        /// </value>
         public bool ValidateCertificateUse { get; set; } = true;
 
         /// <summary>
         /// Flag indicating whether the client certificate validity period should be checked.
         /// </summary>
+        /// <value>
+        /// Defaults to <see langword="true" />.
+        /// </value>
         public bool ValidateValidityPeriod { get; set; } = true;
 
         /// <summary>
         /// Specifies which X509 certificates in the chain should be checked for revocation.
         /// </summary>
+        /// <value>
+        /// Defaults to <see cref="X509RevocationFlag.ExcludeRoot" />.
+        /// </value>
         public X509RevocationFlag RevocationFlag { get; set; } = X509RevocationFlag.ExcludeRoot;
 
         /// <summary>
         /// Specifies conditions under which verification of certificates in the X509 chain should be conducted.
         /// </summary>
+        /// <value>
+        /// Defaults to <see cref="X509RevocationMode.Online" />.
+        /// </value>
         public X509RevocationMode RevocationMode { get; set; } = X509RevocationMode.Online;
 
         /// <summary>

src/Security/Authentication/Certificate/src/CertificateValidationCache.cs

@@ -14,9 +14,13 @@ namespace Microsoft.AspNetCore.Authentication.Certificate
     /// </summary>
     public class CertificateValidationCache : ICertificateValidationCache
     {
-        private MemoryCache _cache;
-        private CertificateValidationCacheOptions _options;
+        private readonly MemoryCache _cache;
+        private readonly CertificateValidationCacheOptions _options;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="CertificateValidationCache"/>.
+        /// </summary>
+        /// <param name="options">An accessor to <see cref="CertificateValidationCacheOptions"/></param>
         public CertificateValidationCache(IOptions<CertificateValidationCacheOptions> options)
         {
             _options = options.Value;

src/Security/Authentication/Certificate/src/CertificateValidationCacheOptions.cs

@@ -1,9 +1,6 @@
 // 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.
 
-// 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;
 
 namespace Microsoft.AspNetCore.Authentication.Certificate
@@ -14,14 +11,18 @@ namespace Microsoft.AspNetCore.Authentication.Certificate
     public class CertificateValidationCacheOptions
     {
         /// <summary>
-        /// The expiration that should be used for entries in the MemoryCache, defaults to 2 minutes.
+        /// Gets or sets the expiration that should be used for entries in the MemoryCache.
         /// This is a sliding expiration that will extend each time the certificate is used, so long as the certificate is valid (see X509Certificate2.NotAfter).
         /// </summary>
+        /// <value>Defaults to 2 minutes.</value>
         public TimeSpan CacheEntryExpiration { get; set; } = TimeSpan.FromMinutes(2);
 
         /// <summary>
-        /// How many validated certificate results to store in the cache, defaults to 1024.
+        /// Gets or sets the maximum number of validated certificate results that are allowed to cached.
         /// </summary>
+        /// <value>
+        /// Defaults to 1024.
+        /// </value>
         public int CacheSize { get; set; } = 1024;
     }
 }

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

@@ -1,11 +1,12 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <Description>ASP.NET Core middleware that enables an application to support certificate authentication.</Description>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
     <DefineConstants>$(DefineConstants);SECURITY</DefineConstants>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;authentication;security;x509;certificate</PackageTags>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/Security/Authentication/Cookies/src/CookieAuthenticationEvents.cs

@@ -9,34 +9,32 @@
 namespace Microsoft.AspNetCore.Authentication.Cookies
 {
     /// <summary>
-    /// This default implementation of the ICookieAuthenticationEvents may be used if the
-    /// application only needs to override a few of the interface methods. This may be used as a base class
-    /// or may be instantiated directly.
+    /// Allows subscribing to events raised during cookie authentication.
     /// </summary>
     public class CookieAuthenticationEvents
     {
         /// <summary>
-        /// A delegate assigned to this property will be invoked when the related method is called.
+        /// Invoked to validate the principal.
         /// </summary>
         public Func<CookieValidatePrincipalContext, Task> OnValidatePrincipal { get; set; } = context => Task.CompletedTask;
 
         /// <summary>
-        /// A delegate assigned to this property will be invoked when the related method is called.
+        /// Invoked on signing in.
         /// </summary>
         public Func<CookieSigningInContext, Task> OnSigningIn { get; set; } = context => Task.CompletedTask;
 
         /// <summary>
-        /// A delegate assigned to this property will be invoked when the related method is called.
+        /// Invoked after sign in has completed.
         /// </summary>
         public Func<CookieSignedInContext, Task> OnSignedIn { get; set; } = context => Task.CompletedTask;
 
         /// <summary>
-        /// A delegate assigned to this property will be invoked when the related method is called.
+        /// Invoked on signing out.
         /// </summary>
         public Func<CookieSigningOutContext, Task> OnSigningOut { get; set; } = context => Task.CompletedTask;
 
         /// <summary>
-        /// A delegate assigned to this property will be invoked when the related method is called.
+        /// Invoked when the client needs to be redirected to the sign in url.
         /// </summary>
         public Func<RedirectContext<CookieAuthenticationOptions>, Task> OnRedirectToLogin { get; set; } = context =>
         {
@@ -53,7 +51,7 @@ public class CookieAuthenticationEvents
         };
 
         /// <summary>
-        /// A delegate assigned to this property will be invoked when the related method is called.
+        /// Invoked when the client needs to be redirected to the access denied url.
         /// </summary>
         public Func<RedirectContext<CookieAuthenticationOptions>, Task> OnRedirectToAccessDenied { get; set; } = context =>
         {
@@ -70,7 +68,7 @@ public class CookieAuthenticationEvents
         };
 
         /// <summary>
-        /// A delegate assigned to this property will be invoked when the related method is called.
+        /// Invoked when the client is to be redirected to logout.
         /// </summary>
         public Func<RedirectContext<CookieAuthenticationOptions>, Task> OnRedirectToLogout { get; set; } = context =>
         {
@@ -86,7 +84,7 @@ public class CookieAuthenticationEvents
         };
 
         /// <summary>
-        /// A delegate assigned to this property will be invoked when the related method is called.
+        /// Invoked when the client is to be redirected after logout.
         /// </summary>
         public Func<RedirectContext<CookieAuthenticationOptions>, Task> OnRedirectToReturnUrl { get; set; } = context =>
         {
@@ -108,52 +106,51 @@ private static bool IsAjaxRequest(HttpRequest request)
         }
 
         /// <summary>
-        /// Implements the interface method by invoking the related delegate method.
+        /// Invoked to validate the prinicipal.
         /// </summary>
-        /// <param name="context"></param>
-        /// <returns></returns>
+        /// <param name="context">The <see cref="CookieValidatePrincipalContext"/>.</param>
         public virtual Task ValidatePrincipal(CookieValidatePrincipalContext context) => OnValidatePrincipal(context);
 
         /// <summary>
-        /// Implements the interface method by invoking the related delegate method.
+        /// Invoked during sign in.
         /// </summary>
-        /// <param name="context"></param>
+        /// <param name="context">The <see cref="CookieSigningInContext"/>.</param>
         public virtual Task SigningIn(CookieSigningInContext context) => OnSigningIn(context);
 
         /// <summary>
-        /// Implements the interface method by invoking the related delegate method.
+        /// Invoked after sign in has completed.
         /// </summary>
-        /// <param name="context"></param>
+        /// <param name="context">The <see cref="CookieSignedInContext"/>.</param>
         public virtual Task SignedIn(CookieSignedInContext context) => OnSignedIn(context);
 
         /// <summary>
-        /// Implements the interface method by invoking the related delegate method.
+        /// Invoked on sign out.
         /// </summary>
-        /// <param name="context"></param>
+        /// <param name="context">The <see cref="CookieSigningOutContext"/>.</param>
         public virtual Task SigningOut(CookieSigningOutContext context) => OnSigningOut(context);
 
         /// <summary>
-        /// Implements the interface method by invoking the related delegate method.
+        /// Invoked when the client is being redirected to the log out url.
         /// </summary>
-        /// <param name="context">Contains information about the event</param>
+        /// <param name="context">The <see cref="RedirectContext{TOptions}"/>.</param>
         public virtual Task RedirectToLogout(RedirectContext<CookieAuthenticationOptions> context) => OnRedirectToLogout(context);
 
         /// <summary>
-        /// Implements the interface method by invoking the related delegate method.
+        /// Invoked when the client is being redirected to the log in url.
         /// </summary>
-        /// <param name="context">Contains information about the event</param>
+        /// <param name="context">The <see cref="RedirectContext{TOptions}"/>.</param>
         public virtual Task RedirectToLogin(RedirectContext<CookieAuthenticationOptions> context) => OnRedirectToLogin(context);
 
         /// <summary>
-        /// Implements the interface method by invoking the related delegate method.
+        /// Invoked when the client is being redirected after log out.
         /// </summary>
-        /// <param name="context">Contains information about the event</param>
+        /// <param name="context">The <see cref="RedirectContext{TOptions}"/>.</param>
         public virtual Task RedirectToReturnUrl(RedirectContext<CookieAuthenticationOptions> context) => OnRedirectToReturnUrl(context);
 
         /// <summary>
-        /// Implements the interface method by invoking the related delegate method.
+        /// Invoked when the client is being redirected to the access denied url.
         /// </summary>
-        /// <param name="context">Contains information about the event</param>
+        /// <param name="context">The <see cref="RedirectContext{TOptions}"/>.</param>
         public virtual Task RedirectToAccessDenied(RedirectContext<CookieAuthenticationOptions> context) => OnRedirectToAccessDenied(context);
     }
 }

src/Security/Authentication/Cookies/src/CookieAuthenticationHandler.cs

@@ -15,6 +15,9 @@
 
 namespace Microsoft.AspNetCore.Authentication.Cookies
 {
+    /// <summary>
+    /// Implementation for the cookie-based authentication handler.
+    /// </summary>
     public class CookieAuthenticationHandler : SignInAuthenticationHandler<CookieAuthenticationOptions>
     {
         private const string HeaderValueNoCache = "no-cache";
@@ -32,6 +35,13 @@ public class CookieAuthenticationHandler : SignInAuthenticationHandler<CookieAut
         private Task<AuthenticateResult>? _readCookieTask;
         private AuthenticationTicket? _refreshTicket;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="CookieAuthenticationHandler"/>.
+        /// </summary>
+        /// <param name="options">Accessor to <see cref="CookieAuthenticationOptions"/>.</param>
+        /// <param name="logger">The <see cref="ILoggerFactory"/>.</param>
+        /// <param name="encoder">The <see cref="UrlEncoder"/>.</param>
+        /// <param name="clock">The <see cref="ISystemClock"/>.</param>
         public CookieAuthenticationHandler(IOptionsMonitor<CookieAuthenticationOptions> options, ILoggerFactory logger, UrlEncoder encoder, ISystemClock clock)
             : base(options, logger, encoder, clock)
         { }
@@ -46,6 +56,7 @@ public CookieAuthenticationHandler(IOptionsMonitor<CookieAuthenticationOptions>
             set { base.Events = value; }
         }
 
+        /// <inheritdoc />
         protected override Task InitializeHandlerAsync()
         {
             // Cookies needs to finish the response
@@ -169,6 +180,7 @@ private async Task<AuthenticateResult> ReadCookieTicket()
             return AuthenticateResult.Success(ticket);
         }
 
+        /// <inheritdoc />
         protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
         {
             var result = await EnsureCookieTicket();
@@ -203,6 +215,7 @@ private CookieOptions BuildCookieOptions()
             return cookieOptions;
         }
 
+        /// <inheritdoc />
         protected virtual async Task FinishResponseAsync()
         {
             // Only renew if requested, and neither sign in or sign out was called
@@ -254,6 +267,7 @@ protected virtual async Task FinishResponseAsync()
             }
         }
 
+        /// <inheritdoc />
         protected async override Task HandleSignInAsync(ClaimsPrincipal user, AuthenticationProperties? properties)
         {
             if (user == null)
@@ -346,6 +360,7 @@ protected async override Task HandleSignInAsync(ClaimsPrincipal user, Authentica
             Logger.AuthenticationSchemeSignedIn(Scheme.Name);
         }
 
+        /// <inheritdoc />
         protected async override Task HandleSignOutAsync(AuthenticationProperties? properties)
         {
             properties = properties ?? new AuthenticationProperties();
@@ -426,6 +441,7 @@ private static bool IsHostRelative(string path)
             return path[0] == '/' && path[1] != '/' && path[1] != '\\';
         }
 
+        /// <inheritdoc />
         protected override async Task HandleForbiddenAsync(AuthenticationProperties properties)
         {
             var returnUrl = properties.RedirectUri;
@@ -438,6 +454,7 @@ protected override async Task HandleForbiddenAsync(AuthenticationProperties prop
             await Events.RedirectToAccessDenied(redirectContext);
         }
 
+        /// <inheritdoc />
         protected override async Task HandleChallengeAsync(AuthenticationProperties properties)
         {
             var redirectUri = properties.RedirectUri;