FEAT: add certificate based authentication filter & attribute

docs/features/certificate-authentication.md

@@ -0,0 +1,75 @@
+---
+title: "Authentication with certificate via ASP.NET Core authentication filters"
+layout: default
+---
+
+The `Arcus.WebApi.Security` package provides a mechanism that uses the client certificate of the request to grant access to a web application.
+This authentication process consists of following parts:
+
+1. Find the client certificate configured on the HTTP request
+2. Determine which properties of the received client certificate are used for authentication
+3. The property value(s) of the client certificate matches the value(s) determined via configured secret provider
+
+The package allows two ways to configure this type of authentication mechanism in an <span>ASP.NET</span> application:
+- [Globally enforce certificate authentication](#Globally-enforce-certificate-authentication)
+- [Enforce certificate authentication per controller or operation](#Enforce-certificate-authentication-per-controller-or-operation)
+
+## Globally enforce certificate authentication
+
+### Introduction
+
+The `CertificateAuthenticationFilter` can be added to the request filters in an <span>ASP.NET</span> Core application.
+This filter will then add authentication to all endpoints via one or many certificate properties configurable on the filter itself.
+
+### Usage
+
+The authentication requires an `ICachedSecretProvider` or `ISecretProvider` dependency to be registered with the services container of the <span>ASP.NET</span> request pipeline. This is typically done in the `ConfigureServices` method of the `Startup` class.
+Once this is done, the `CertificateAuthenticationFilter` can be added to the filters that will be applied to all actions:
+
+```csharp
+public void ConfigureServices(IServiceCollections services)
+{
+    services.AddScoped<ICachedSecretProvider(serviceProvider => new MyCachedSecretProvider());
+    services.AddMvc(
+        options => options.Filters.Add(
+            new CertificateAuthenticationFilter(
+                X509CertificateRequirement.SubjectName,
+                "key-to-certificate-subject-name"
+            )));
+}
+```
+
+## Enforce certificate authentication per controller or operation
+
+### Introduction
+
+The `CertificateAuthenticationAttribute` can be added on both controller- and operation level in an <span>ASP.NET</span> Core application.
+This certificate authentication will then be applied to the endpoint(s) that are decorated with the `CertificateAuthenticationAttribute`.
+
+### Usage
+
+The authentication requires an `ICachedSecretProvider` or `ISecretProvider` dependency to be registered with the services container of the <span>ASP.NET</span> request pipeline. This is typically done in the `ConfigureServices` method of the `Startup` class:
+
+```csharp
+public void ConfigureServices(IServiceCollections services)
+{
+    services.AddScoped<ICachedSecretProvider>(serviceProvider => new CachedSecretProvider(new MySecretProvider()));
+    services.AddMvc();
+}
+```
+
+After that, the `CertificateAuthenticationAttribute` attribute can be applied on the controllers, or if more fine-grained control is needed, on the operations that requires authentication:
+
+```csharp
+[ApiController]
+[CertificateAuthentication(X509CertificateRequirement.IssuerName, "key-to-certificate-issuer-name")]
+public class MyApiController : ControllerBase
+{
+    [HttpGet]
+    [Route("authz/certificate)]
+    public Task<IActionResult> AuthorizedGet()
+    {
+        return Task.FromResult<IActionResult>(Ok());
+    }
+}
+```

src/Arcus.WebApi.Security/Authentication/CertificateAuthenticationAttribute.cs

@@ -0,0 +1,26 @@
+using System;
+using System.Security.Cryptography.X509Certificates;
+using GuardNet;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Arcus.WebApi.Security.Authentication
+{
+    /// <summary>
+    /// Authentication filter to secure HTTP requests by allowing only certain values in the client certificate.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple = true)]
+    public class CertificateAuthenticationAttribute : TypeFilterAttribute
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CertificateAuthenticationAttribute"/> class.
+        /// </summary>
+        /// <param name="requirement">The property of the client <see cref="X509Certificate2"/> to validate.</param>
+        /// <param name="expectedValue">The expected value the property of the <see cref="X509Certificate2"/> should have.</param>
+        public CertificateAuthenticationAttribute(X509ValidationRequirement requirement, string expectedValue) : base(typeof(CertificateAuthenticationFilter))
+        {
+            Guard.NotNullOrWhitespace(expectedValue, nameof(expectedValue), "Expected value in certificate cannot be blank");
+
+            Arguments = new object[] { requirement, expectedValue };
+        }
+    }
+}

src/Arcus.WebApi.Security/Authentication/CertificateAuthenticationFilter.cs

@@ -0,0 +1,171 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Security.Cryptography.X509Certificates;
+using System.Threading.Tasks;
+using Arcus.Security.Secrets.Core.Interfaces;
+using GuardNet;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.Filters;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
+
+namespace Arcus.WebApi.Security.Authentication
+{
+    /// <summary>
+    /// Authentication filter to secure HTTP requests by allowing only certain values in the client certificate.
+    /// </summary>
+    public class CertificateAuthenticationFilter : IAsyncAuthorizationFilter
+    {
+        private readonly (X509ValidationRequirement requirement, string configurationKey)[] _requirements;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CertificateAuthenticationFilter"/> class.
+        /// </summary>
+        /// <param name="requirement">The property of the client <see cref="X509Certificate2"/> to validate.</param>
+        /// <param name="expectedValue">The expected value the property of the <see cref="X509Certificate2"/> should have.</param>
+        public CertificateAuthenticationFilter(X509ValidationRequirement requirement, string expectedValue)
+            : this((requirement, expectedValue)) { }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CertificateAuthenticationFilter"/> class.
+        /// </summary>
+        /// <param name="requirements">The sequence of requirement property of the client <see cref="X509Certificate2"/> and expected values it should have.</param>
+        public CertificateAuthenticationFilter(
+            params (X509ValidationRequirement requirement, string configurationKey)[] requirements)
+        {
+            Guard.NotNull(requirements, nameof(requirements), "Sequence of requirements and their expected values should not be 'null'");
+            Guard.For<ArgumentException>(() => requirements.Any(requirement => String.IsNullOrWhiteSpace(requirement.configurationKey)), "Sequence of requirements cannot contain any configuration key that is blank");
+
+            _requirements = requirements;
+        }
+
+        /// <summary>
+        /// Called early in the filter pipeline to confirm request is authorized.
+        /// </summary>
+        /// <param name="context">The <see cref="T:Microsoft.AspNetCore.Mvc.Filters.AuthorizationFilterContext" />.</param>
+        public async Task OnAuthorizationAsync(AuthorizationFilterContext context)
+        {
+            Guard.NotNull(context, nameof(context));
+            Guard.NotNull(context.HttpContext, nameof(context.HttpContext));
+            Guard.For<ArgumentException>(() => context.HttpContext.Connection is null, "Invalid action context given without any HTTP connection");
+            Guard.For<ArgumentException>(() => context.HttpContext.RequestServices is null, "Invalid action context given without any HTTP request services");
+
+            ILogger logger = 
+                context.HttpContext.RequestServices
+                       .GetService<ILoggerFactory>()
+                       ?.CreateLogger<CertificateAuthenticationFilter>() 
+                ?? (ILogger) NullLogger.Instance;
+
+            ISecretProvider userDefinedSecretProvider = 
+                context.HttpContext.RequestServices.GetService<ICachedSecretProvider>()
+                ?? context.HttpContext.RequestServices.GetService<ISecretProvider>();
+
+            if (userDefinedSecretProvider == null)
+            {
+                throw new KeyNotFoundException(
+                    $"No configured {nameof(ICachedSecretProvider)} or {nameof(ISecretProvider)} implementation found in the request service container. "
+                    + "Please configure such an implementation (ex. in the Startup) of your application");
+            }
+
+            X509Certificate2 clientCertificate = context.HttpContext.Connection.ClientCertificate;
+            if (clientCertificate == null)
+            {
+                logger.LogWarning(
+                    "No client certificate was specified in the HTTP request while this authentication filter "
+                    + $"requires a certificate to validate on the {String.Join(", ", _requirements.Select(item => item.requirement))}");
+
+                context.Result = new UnauthorizedResult();
+            }
+            else if (!await IsAllowedCertificate(clientCertificate, userDefinedSecretProvider, logger))
+            {
+                context.Result = new UnauthorizedResult();
+            }
+        }
+
+        private async Task<bool> IsAllowedCertificate(
+            X509Certificate2 clientCertificate, 
+            ISecretProvider provider,
+            ILogger logger)
+        {
+            var requirementValues = await Task.WhenAll(_requirements.Select(async item =>
+            {
+                string expected = await provider.Get(item.configurationKey);
+                return (requirement: item.requirement, key: item.configurationKey, expected: expected);
+            }));
+
+            return requirementValues.All(value =>
+            {
+                if (value.expected == null)
+                {
+                    logger.LogWarning($"Client certificate authentication failed: no configuration value found for key={value.key}");
+                    return false;
+                }
+
+                switch (value.requirement)
+                {
+                    case X509ValidationRequirement.SubjectName:
+                        return IsAllowedCertificateSubject(clientCertificate, value.expected, logger);
+                    case X509ValidationRequirement.IssuerName:
+                        return IsAllowedCertificateIssuer(clientCertificate, value.expected, logger);
+                    case X509ValidationRequirement.Thumbprint:
+                        return IsAllowedCertificateThumbprint(clientCertificate, value.expected, logger);
+                    default:
+                        throw new ArgumentOutOfRangeException(nameof(value.requirement), value.requirement, "Unknown validation type specified");
+                }
+            });
+        }
+
+        private static bool IsAllowedCertificateSubject(X509Certificate2 clientCertificate, string expected, ILogger logger)
+        {
+            IEnumerable<string> certificateSubjectNames =
+                clientCertificate.Subject
+                    .Split(new[] { ',' }, StringSplitOptions.RemoveEmptyEntries)
+                    .Select(subject => subject.Trim());
+
+            bool isAllowed = certificateSubjectNames.Any(subject => String.Equals(subject, expected));
+            if (!isAllowed)
+            {
+                logger.LogWarning(
+                    "Client certificate authentication failed on subject: "
+                    + $"no subject found (actual={String.Join(", ", certificateSubjectNames)}) in certificate that matches expected={expected}");
+            }
+
+            return isAllowed;
+        }
+
+        private static bool IsAllowedCertificateIssuer(X509Certificate2 clientCertificate, string expected, ILogger logger)
+        {
+            IEnumerable<string> issuerNames = 
+                clientCertificate.Issuer
+                    .Split(new[] { ',' }, StringSplitOptions.RemoveEmptyEntries)
+                    .Select(issuer => issuer.Trim());
+
+            bool isAllowed = issuerNames.Any(issuer => String.Equals(issuer, expected));
+            if (!isAllowed)
+            {
+                logger.LogWarning(
+                    "Client certificate authentication failed on issuer: "
+                    + $"no issuer found (actual={String.Join(", ", issuerNames)}) in certificate that matches expected={expected}");
+            }
+
+            return isAllowed;
+        }
+
+        private static bool IsAllowedCertificateThumbprint(X509Certificate2 clientCertificate, string expected, ILogger logger)
+        {
+            string actual = clientCertificate.Thumbprint?.Trim();
+
+            bool isAllowed = String.Equals(expected, actual);
+            if (!isAllowed)
+            {
+                logger.LogWarning(
+                    "Client certificate authentication failed on thumbprint: "
+                    + $"expected={expected} <> actual={actual}");
+            }
+
+            return isAllowed;
+        }
+    }
+}

src/Arcus.WebApi.Security/Authentication/X509ValidationRequirement.cs

@@ -0,0 +1,25 @@
+using System.Security.Cryptography.X509Certificates;
+
+namespace Arcus.WebApi.Security.Authentication 
+{
+    /// <summary>
+    /// Represents which value of the client <see cref="X509Certificate2"/> should be validated in the <see cref="CertificateAuthenticationFilter"/>.
+    /// </summary>
+    public enum X509ValidationRequirement
+    {
+        /// <summary>
+        /// Allow only certificates where the <see cref="X509Certificate.Subject"/> matches.
+        /// </summary>
+        SubjectName, 
+
+        /// <summary>
+        /// Allow only certificates where the <see cref="X509Certificate.Issuer"/> matches.
+        /// </summary>
+        IssuerName, 
+
+        /// <summary>
+        /// Allow only certificates where the <see cref="X509Certificate2.Thumbprint"/> matches.
+        /// </summary>
+        Thumbprint
+    }
+}

src/Arcus.WebApi.Unit/Arcus.WebApi.Unit.csproj

@@ -14,6 +14,8 @@
         <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     </PropertyGroup>
     <ItemGroup>
+      <PackageReference Include="BouncyCastle" Version="1.8.5" />
+      <PackageReference Include="BouncyCastle.NetCoreSdk" Version="1.9.0.1" />
       <PackageReference Include="System.Web.Http" Version="4.0.0" />
       <PackageReference Include="Microsoft.AspNetCore.App" />
       <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />

src/Arcus.WebApi.Unit/Hosting/CertificateConfiguration.cs

@@ -0,0 +1,41 @@
+using System;
+using System.Security.Cryptography.X509Certificates;
+using GuardNet;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+
+namespace Arcus.WebApi.Unit.Hosting
+{
+    /// <summary>
+    /// Security configuration addition to set the TLS client certificate on every call made via the <see cref="TestApiServer"/>.
+    /// </summary>
+    internal class CertificateConfiguration : IStartupFilter
+    {
+        private readonly X509Certificate2 _clientCertificate;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CertificateConfiguration"/> class.
+        /// </summary>
+        /// <param name="clientCertificate">The client certificate.</param>
+        public CertificateConfiguration(X509Certificate2 clientCertificate)
+        {
+            Guard.NotNull(clientCertificate, nameof(clientCertificate));
+
+            _clientCertificate = clientCertificate;
+        }
+
+        /// <inheritdoc />
+        public  Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
+        {
+            return builder =>
+            {
+                builder.Use((context, nxt) =>
+                {
+                    context.Connection.ClientCertificate = _clientCertificate;
+                    return nxt();
+                });
+                next(builder);
+            };
+        }
+    }
+}