feat: change certificate auth target type

docs/preview/features/security/auth/certificate.md

@@ -74,10 +74,10 @@ builder.Services.AddSingleton(certificateValidator);
 builder.Services.AddControllers(mvcOptions => 
 {
     // Adds certificate authentication to the request pipeline.
-    mvcOptions.Filters.AddCertificateAuthentication();
+    mvcOptions.AddCertificateAuthenticationFilter();
 
     // Additional consumer-configurable options to change the behavior of the authentication filter.
-    mvcOptions.Filters.AddCertificateAuthentication(configureOptions: options =>
+    mvcOptions.AddCertificateAuthenticationFilter(configureOptions: options =>
     {
         // Adds certificate authentication to the request pipeline with emitting security events during the authorization of the request.
         // (default: `false`)
@@ -173,7 +173,4 @@ public class SystemController : ControllerBase
         return Ok();
     }
 }
-```
-
-
-[← back](/)
+```

src/Arcus.WebApi.Security/Authentication/Certificates/CertificateAuthenticationConfigBuilder.cs

@@ -137,6 +137,13 @@ private static IX509ValidationLocation GetValidationLocationImplementation(X509V
         /// </summary>
         public CertificateAuthenticationConfig Build()
         {
+            if (_locationAndKeyByRequirement.Count <= 0)
+            {
+                throw new InvalidOperationException(
+                    "Cannot build up the certificate authentication validation because there's nothing configured to be validated on the client certificate, "
+                    + $"please configure the certificate validation requirements with methods like {nameof(WithThumbprint)}, {nameof(WithIssuer)}");
+            }
+
             return new CertificateAuthenticationConfig(_locationAndKeyByRequirement);
         }
     }

src/Arcus.WebApi.Security/Authentication/Certificates/Extensions/FilterCollectionExtensions.cs

@@ -1,6 +1,7 @@
 using System;
 using Arcus.WebApi.Security.Authentication.Certificates;
 using GuardNet;
+using Microsoft.Extensions.DependencyInjection;
 
 // ReSharper disable once CheckNamespace
 namespace Microsoft.AspNetCore.Mvc.Filters
@@ -16,13 +17,14 @@ public static partial class FilterCollectionExtensions
         /// <param name="filters">The current MVC filters of the application.</param>
         /// <returns></returns>
         /// <exception cref="ArgumentNullException">Thrown when the <paramref name="filters"/> is <c>null</c>.</exception>
+        [Obsolete("Use the " + nameof(MvcOptionsExtensions.AddCertificateAuthenticationFilter) + " instead via the services.AddControllers(options => options." + nameof(MvcOptionsExtensions.AddCertificateAuthenticationFilter) + "())")]
         public static FilterCollection AddCertificateAuthentication(this FilterCollection filters)
         {
             Guard.NotNull(filters, nameof(filters), "Requires a set of MVC filters to add the certificate authentication MVC filter");
 
             return AddCertificateAuthentication(filters, configureOptions: null);
         }
-        
+
         /// <summary>
         /// Adds an certificate authentication MVC filter to the given <paramref name="filters"/> that authenticates the incoming HTTP request.
         /// </summary>
@@ -32,6 +34,7 @@ public static FilterCollection AddCertificateAuthentication(this FilterCollectio
         /// </param>
         /// <returns></returns>
         /// <exception cref="ArgumentNullException">Thrown when the <paramref name="filters"/> is <c>null</c>.</exception>
+        [Obsolete("Use the " + nameof(MvcOptionsExtensions.AddCertificateAuthenticationFilter) + " instead via the services.AddControllers(options => options." + nameof(MvcOptionsExtensions.AddCertificateAuthenticationFilter) + "(...))")]
         public static FilterCollection AddCertificateAuthentication(
             this FilterCollection filters,
             Action<CertificateAuthenticationOptions> configureOptions)

src/Arcus.WebApi.Security/Authentication/Certificates/Extensions/MvcOptionsExtensions.cs

@@ -0,0 +1,49 @@
+using System;
+using Arcus.WebApi.Security.Authentication.Certificates;
+using GuardNet;
+using Microsoft.AspNetCore.Mvc;
+
+// ReSharper disable once CheckNamespace
+namespace Microsoft.Extensions.DependencyInjection
+{
+    /// <summary>
+    /// Extensions on the <see cref="MvcOptions"/> related to authentication.
+    /// </summary>
+    public static partial class MvcOptionsExtensions
+    {
+         /// <summary>
+        /// Adds an certificate authentication MVC filter to the given <paramref name="options"/> that authenticates the incoming HTTP request.
+        /// </summary>
+        /// <param name="options">The current MVC options of the application.</param>
+        /// <returns></returns>
+        /// <exception cref="ArgumentNullException">Thrown when the <paramref name="options"/> is <c>null</c>.</exception>
+        public static MvcOptions AddCertificateAuthenticationFilter(this MvcOptions options)
+        {
+            Guard.NotNull(options, nameof(options), "Requires a set of MVC filters to add the certificate authentication MVC filter");
+
+            return AddCertificateAuthenticationFilter(options, configureOptions: null);
+        }
+
+        /// <summary>
+        /// Adds an certificate authentication MVC filter to the given <paramref name="options"/> that authenticates the incoming HTTP request.
+        /// </summary>
+        /// <param name="options">The current MVC options of the application.</param>
+        /// <param name="configureOptions">
+        ///     The optional function to configure the set of additional consumer-configurable options to change the behavior of the certificate authentication.
+        /// </param>
+        /// <returns></returns>
+        /// <exception cref="ArgumentNullException">Thrown when the <paramref name="options"/> is <c>null</c>.</exception>
+        public static MvcOptions AddCertificateAuthenticationFilter(
+            this MvcOptions options,
+            Action<CertificateAuthenticationOptions> configureOptions)
+        {
+            Guard.NotNull(options, nameof(options), "Requires a set of MVC filters to add the certificate authentication MVC filter");
+
+            var authOptions = new CertificateAuthenticationOptions();
+            configureOptions?.Invoke(authOptions);
+
+            options.Filters.Add(new CertificateAuthenticationFilter(authOptions));
+            return options;
+        }
+    }
+}