Add the Challenge event

Author: Tratcher

src/Security/Authentication/Certificate/samples/Certificate.Optional.Sample/Program.cs

@@ -7,6 +7,9 @@ namespace Certificate.Sample
 {
     public class Program
     {
+        public const string Host1 = "127.0.0.1";
+        public const string Host2 = "127.0.0.2";
+
         public static void Main(string[] args)
         {
             CreateHostBuilder(args).Build().Run();
@@ -19,17 +22,16 @@ public static IHostBuilder CreateHostBuilder(string[] args) =>
                     webBuilder.UseStartup<Startup>();
                     webBuilder.ConfigureKestrel((context, options) =>
                     {
-                        // Kestrel can't have different ssl settings on the same IP because there's no way to change them based on SNI.
+                        // Kestrel can't have different ssl settings for different hosts on the same IP because there's no way to change them based on SNI.
                         // https://github.com/dotnet/runtime/issues/31097
-                        // TODO: Provide a certificate that allows 127.0.0.1 as a host so we don't have to worry about setting up DNS, host files, etc..
-                        options.Listen(IPAddress.Parse("127.0.0.1"), 5001, listenOptions =>
+                        options.Listen(IPAddress.Parse(Host1), 5001, listenOptions =>
                         {
                             listenOptions.UseHttps(httpsOptions =>
                             {
                                 httpsOptions.ClientCertificateMode = ClientCertificateMode.NoCertificate;
                             });
                         });
-                        options.Listen(IPAddress.Parse("127.0.0.2"), 5001, listenOptions =>
+                        options.Listen(IPAddress.Parse(Host2), 5001, listenOptions =>
                         {
                             listenOptions.UseHttps(httpsOptions =>
                             {

src/Security/Authentication/Certificate/samples/Certificate.Optional.Sample/README.md

@@ -1,7 +1,7 @@
 Optional certificates sample
 ============================
 
-Client certificates are relatively easy to configure when they're required for requests, you configure it in the server bindings as required and add the auth handler to validate it. Things are much trickier when you only want to require client certifiates for some parts of your application.
+Client certificates are relatively easy to configure when they're required for all requests, you configure it in the server bindings as required and add the auth handler to validate it. Things are much trickier when you only want to require client certificates for some parts of your application.
 
 Client certificates are not an HTTP feature, they're a TLS feature. As such they're not included in the HTTP request structure like headers, they're negotiated when establishing the connection. This makes it impossible to require a certificate for some requests but not others on a given connection.
 

src/Security/Authentication/Certificate/samples/Certificate.Optional.Sample/Startup.cs

@@ -1,14 +1,10 @@
-using System.Security.Claims;
 using System.Threading.Tasks;
 using Microsoft.AspNetCore.Authentication.Certificate;
-using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Http.Extensions;
 using Microsoft.Extensions.DependencyInjection;
-using Microsoft.Extensions.Hosting;
-using Microsoft.Net.Http.Headers;
 
 namespace Certificate.Sample
 {
@@ -21,6 +17,20 @@ public void ConfigureServices(IServiceCollection services)
             services.AddAuthentication(CertificateAuthenticationDefaults.AuthenticationScheme)
                 .AddCertificate(options =>
                 {
+                    options.Events = new CertificateAuthenticationEvents()
+                    {
+                        // If there is no certificate we must be on Host1 that does not require one. Redirect to Host2 to prompt for a certificate.
+                        OnChallenge = context =>
+                        {
+                            var request = context.Request;
+                            var redirect = UriHelper.BuildAbsolute("https",
+                                new HostString(Program.Host2, context.HttpContext.Connection.LocalPort),
+                                request.PathBase, request.Path, request.QueryString);
+                            context.Response.Redirect(redirect, permanent: false, preserveMethod: true);
+                            context.HandleResponse(); // Don't do the default behavior that would send a 403 response.
+                            return Task.CompletedTask;
+                        }
+                    };
                 });
 
             services.AddAuthorization();
@@ -36,45 +46,14 @@ public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
 
             app.UseEndpoints(endpoints =>
             {
-                endpoints.Map("/required", context =>
-                {
-                    if (context.User.Identity.IsAuthenticated)
-                    {
-                        return context.Response.WriteAsync($"Hello {context.User.Identity.Name} at {context.Request.Host}");
-                    }
-                    else
-                    {
-                        var request = context.Request;
-                        var redirect = UriHelper.BuildAbsolute("https", new HostString("127.0.0.2", context.Connection.LocalPort), request.PathBase, request.Path, request.QueryString);
-                        context.Response.Redirect(redirect, permanent: false, preserveMethod: true);
-                        return Task.CompletedTask;
-                    }
-                });
-                endpoints.Map("/signout", context =>
+                endpoints.Map("/auth", context =>
                 {
-                    if (context.User.Identity.IsAuthenticated)
-                    {
-                        // Closing the connection doesn't reset Chrome's state, it still remembers which client cert was last used for which host until you close the browser.
-                        // context.Response.Headers[HeaderNames.Connection] = "close";
+                    return context.Response.WriteAsync($"Hello {context.User.Identity.Name} at {context.Request.Host}");
+                }).RequireAuthorization();
 
-                        // Sign out by switching back to the other host. This isn't a real sign-out because the browser has still cached the client certificate for this host.
-                        // The only real way to clear that is to close the browser.
-                        if (context.Request.Host.Host.Equals("127.0.0.2"))
-                        {
-                            var request = context.Request;
-                            var redirect = UriHelper.BuildAbsolute("https", new HostString("127.0.0.1", context.Connection.LocalPort), request.PathBase);
-                            context.Response.Redirect(redirect, permanent: false, preserveMethod: true);
-                        }
-                        return context.Response.WriteAsync($"Goodbye {context.User.Identity.Name} at {context.Request.Host}");
-                    }
-                    else
-                    {
-                        return context.Response.WriteAsync("Already signed out.");
-                    }
-                });
                 endpoints.Map("{*url}", context =>
                 {
-                    return context.Response.WriteAsync($"Hello {context.User.Identity.Name} at {context.Request.Host}");
+                    return context.Response.WriteAsync($"Hello {context.User.Identity.Name} at {context.Request.Host}. Try /auth");
                 });
             });
         }

src/Security/Authentication/Certificate/src/CertificateAuthenticationHandler.cs

@@ -130,11 +130,19 @@ protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
             }
         }
 
-        protected override Task HandleChallengeAsync(AuthenticationProperties properties)
+        protected override async Task HandleChallengeAsync(AuthenticationProperties properties)
         {
+            var authenticationChallengedContext = new CertificateChallengeContext(Context, Scheme, Options, properties);
+            await Events.Challenge(authenticationChallengedContext);
+
+            if (authenticationChallengedContext.Handled)
+            {
+                return;
+            }
+
             // Certificate authentication takes place at the connection level. We can't prompt once we're in
             // user code, so the best thing to do is Forbid, not Challenge.
-            return HandleForbiddenAsync(properties);
+            await HandleForbiddenAsync(properties);
         }
 
         private X509ChainPolicy BuildChainPolicy(X509Certificate2 certificate)

src/Security/Authentication/Certificate/src/Events/CertificateAuthenticationEvents.cs

@@ -28,6 +28,11 @@ public class CertificateAuthenticationEvents
         /// </remarks>
         public Func<CertificateValidatedContext, Task> OnCertificateValidated { get; set; } = context => Task.CompletedTask;
 
+        /// <summary>
+        /// Invoked before a challenge is sent back to the caller.
+        /// </summary>
+        public Func<CertificateChallengeContext, Task> OnChallenge { get; set; } = context => Task.CompletedTask;
+
         /// <summary>
         /// Invoked when a certificate fails authentication.
         /// </summary>
@@ -41,5 +46,10 @@ public class CertificateAuthenticationEvents
         /// <param name="context"></param>
         /// <returns></returns>
         public virtual Task CertificateValidated(CertificateValidatedContext context) => OnCertificateValidated(context);
+
+        /// <summary>
+        /// Invoked before a challenge is sent back to the caller.
+        /// </summary>
+        public virtual Task Challenge(CertificateChallengeContext context) => OnChallenge(context);
     }
 }

src/Security/Authentication/Certificate/src/Events/CertificateChallengeContext.cs

@@ -0,0 +1,37 @@
+// 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 Microsoft.AspNetCore.Http;
+
+namespace Microsoft.AspNetCore.Authentication.Certificate
+{
+    /// <summary>
+    /// State for the Challenge event.
+    /// </summary>
+    public class CertificateChallengeContext : PropertiesContext<CertificateAuthenticationOptions>
+    {
+        /// <summary>
+        /// Creates a new <see cref="CertificateChallengeContext"/>.
+        /// </summary>
+        /// <param name="context"></param>
+        /// <param name="scheme"></param>
+        /// <param name="options"></param>
+        /// <param name="properties"></param>
+        public CertificateChallengeContext(
+            HttpContext context,
+            AuthenticationScheme scheme,
+            CertificateAuthenticationOptions options,
+            AuthenticationProperties properties)
+            : base(context, scheme, options, properties) { }
+
+        /// <summary>
+        /// If true, will skip any default logic for this challenge.
+        /// </summary>
+        public bool Handled { get; private set; }
+
+        /// <summary>
+        /// Skips any default logic for this challenge.
+        /// </summary>
+        public void HandleResponse() => Handled = true;
+    }
+}