How to implement Certificate Authentication in ASP.NET Core

Certificate-based Authentication uses Digital Certificate to identify a client’s request and then grants it the access to a resource, network, application, etc. Certificate Authentication provides added security to web applications and Web APIs. Here I will tell how to implement Certificate Authentication in ASP.NET Core.

PowerShell Commands to create Certificates

Certificate Authentication requires 2 types of Certificates, these are:

• Certification Authority (CA)
• Child Certificate

Now let us create both these certificates in PowerShell.

Creating Certification Authority (CA) in PowerShell

First open the PowerShell as an adminstrator. Then run the following 3 commands one by one.

New-SelfSignedCertificate -DnsName "localhost", "localhost" -CertStoreLocation "cert:\LocalMachine\My" -NotAfter (Get-Date).AddYears(20) -FriendlyName "Rlocalhost" -KeyUsageProperty All -KeyUsage CertSign, CRLSign, DigitalSignature

I have kept the value of -DnsName parameter as localhost which is absolutely right since I am securing the app running locally. In production you will have to use the value of your domain. Example -DnsName "yogihosting".

This command will create the self-signed Certificate Authority and provide it’s thumbprint. Keep this thumbprint safe as we will use it to create child certificate.

I am keeping the password 1234.

$mypwd = ConvertTo-SecureString -String "1234" -Force -AsPlainText

We will now use the password which we set earlier and use it along with the thumbprint to export the certificate in a .pfx file.

Run the below command but before that change the text "thumbprint" with the thumbprint which you got earlier.

Get-ChildItem -Path cert:\localMachine\my\"thumbprint" | Export-PfxCertificate -FilePath D:\root.pfx -Password $mypwd

The command will export the certificate authority file called root.pfx on the “D” drive.

Creating Child Certificate in PowerShell

Let us create Child Certificate from root CA. So run the following 4 commands one by one. Note that:

• In the first command change the text "ca thumbprint" with the thumbprint of root certificate which you got earlier.
• After running the second command you will get the thumbprint of the child certificate. You have to change the text "thumbprint" in the fourth command with this thumbprint.

These 4 commands are given below.

$rootcert = ( Get-ChildItem -Path cert:\LocalMachine\My\"ca thumbprint" )

New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname "localhost" -Signer $rootcert -NotAfter (Get-Date).AddYears(20) -FriendlyName "Clocalhost"

$mypwd = ConvertTo-SecureString -String "1234" -Force -AsPlainText

Get-ChildItem -Path cert:\localMachine\my\"thumbprint" | Export-PfxCertificate -FilePath D:\child.pfx -Password $mypwd

The child certificate file called child.pfx will be created on the “D” drive.

In the following image I have shown both the certificate files that are created on my D drive.

Implementing Certificate Based Authentication

In your ASP.NET Core app, first add the package called Microsoft.AspNetCore.Authentication.Certificate from NuGet.

Next, add a validation class whose role is to validate the child Certificates of the clients which are making the request.

public class MyCertificateValidationService
{
    public bool ValidateCertificate(X509Certificate2 clientCertificate)
    {
        string[] allowedThumbprints = { "21A6E47A962C0E80A59517691FFA1D0500E3E548", "87A6E47A962C0E80A59517691FFA1D0500E3E548", "78A6E47A962C0E80A59517691FFA1D0500E3E548" };
        if (allowedThumbprints.Contains(clientCertificate.Thumbprint))
        {
            return true;
        }

        return false;
    }
}

The string array allowedThumbprints contains 3 thumbprints of the child certificates. Make sure to put the child certificate thumbprint else you will fail to authorize.

Next, on the Startup file ConfigureServices method, do 2 things:

• 1. Register this validation class using AddTransient method.
• 2. Tell app to use Certificate Authentication with the AddAuthentication method.

In the AddAuthentication() method provide a delegate for OnCertificateValidated and OnAuthenticationFailed events. These events will be called if certificate validation passes or fails.

Check the below highlighted code:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews();

    services.AddTransient<MyCertificateValidationService>();
    services.AddAuthentication(
        CertificateAuthenticationDefaults.AuthenticationScheme)
        .AddCertificate(options =>
        {
            options.AllowedCertificateTypes = CertificateTypes.SelfSigned;
            options.Events = new CertificateAuthenticationEvents
            {
                OnCertificateValidated = context =>
                {
                    var validationService = context.HttpContext.RequestServices.GetService<MyCertificateValidationService>();

                    if (validationService.ValidateCertificate(context.ClientCertificate))
                    {
                        context.Success();
                    }
                    else
                    {
                        context.Fail("invalid cert");
                    }

                    return Task.CompletedTask;
                },
                OnAuthenticationFailed = context =>
                {
                    context.Fail("invalid cert");
                    return Task.CompletedTask;
                }
            };
        });
}

Note that the code – options.AllowedCertificateTypes = CertificateTypes.SelfSigned must specifiy the certificate type which should be self signed in our case. It can have 3 values: All, Chained and SelfSigned.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

Configure Kestrel to require certificates

Finally, you have to configure Kestrel so that the application always require certificates. This is done by adding the below code to the Program.cs file:

public static IHostBuilder CreateHostBuilder(string[] args)
{
    return Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
            webBuilder.ConfigureKestrel(o =>
            {
                o.ConfigureHttpsDefaults(o => o.ClientCertificateMode = ClientCertificateMode.RequireCertificate);
            });
        });
}

This completes the integration.

Test Certificate Authentication in Web API

In my Certificate Authentication configured app, I created a simple web api controller which returns a text – “Welcome to Narnia”.

using Microsoft.AspNetCore.Mvc;

namespace Test1.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class HomeController : ControllerBase
    {
        [HttpGet]
        public string Get() => "Welcome to Narnia";
    }
}

Next on Visual Studio select the kestrel option from the run dropdown. I have shown this in the below image. This makes sure that when I run the app on visual studio then kestrel should run it instead of IIS.

Now run your app on visual studio and open the URL of the Web API which in my case is – https://localhost:5001/api/Home . You will see you cannot access the api as it is requiring a certificate for authentication. See the error message given by the browser.

Windows uses a utility called CertMgr to manage certificates. Search for “CertMgr” or “Manage Computer Certificates” in the windows search to open this utility. Next, right click on the “Certificates” folder which is under the “Trusted Root Certification Authorities” and select All Tasks ➤ Import and browse to the root.pfx file on the D drive.

Click on the Next button to reach the next screen where you are asked to enter the private key (password). Recall we used “1234” as the password.

Continue the process and your root CA certificate will be added.

Now we will add the child certificate to chrome browser. So go to settings and then click the Security section under “Privacy and security”. Here you will find Manage Certificates, click on it to open a dialog window.

In this window make sure you are on the “Personal” tab and then click the Import button. Simply import the child.pfx file. As previously, enter the password 1234 when asked.

Now once again run your app on Visual Studio and open the url of the web api. This time chrome will ask you to select the child certificate.

Click the OK button and this time you will be able to access the web api. See the below image which confirms this.

Implement HttpClient with Certificate Authentication

When using HttpClient class to call web apis (that are secured by certification authentciation) you have to add the client certificate to the request, you do this with HttpClientHandler. Check the highlighted code given below.

public async Task<IActionResult> Index()
{
    var cert = new X509Certificate2(Path.Combine(env.ContentRootPath, "child.pfx"), "1234");
    var handler = new HttpClientHandler();
    handler.ClientCertificates.Add(cert);

    string apiResponse = "";

    using (var httpClient = new HttpClient(handler))
    {
        using (var response = await httpClient.GetAsync("https://localhost:5001/api/Home"))
        {
            apiResponse = await response.Content.ReadAsStringAsync();
        }
    }
    return View((object)apiResponse);
}

Download full source codes:

Download