How to Setup Certificate Authentication in ASP.NET Core

Have you ever wondered how to set up ASP.NET Core with a straightforward yet secure authentication method? Continue reading!

In order to configure certificate-based authentication in ASP.NET Core, this article aims to provide you with the bare minimum set of instructions.

Who is certificate authentication for?

Here are some examples of typical scenarios where certificate-based authentication will be advantageous:

• Authenticating users in a corporate (intranet) environment
• Communication between applications or APIs
• Identifying IoT devices for server resources access

Steps to Implement It

1. Configure IIS

Inside of IIS, a client certificate is actually validated and verified. In order for IIS to recognize and accept certificates, the proper configuration is required.

Activate the IIS Manager. Locate the web application that needs configuration. Open SSL Settings in the Features View.

Check the box next to “Require SSL” in the SSL Settings, then choose the “Client certificates: Require” option.

With this command, IIS will be told to accept (and demand) client certificates and to validate them before transferring the request to our ASP.NET Core application.

Note: My test setup uses IIS as the host for the website.

2. Installing a Client Certificate

We then need to get the client certificates ready. Using certificates from a browser-trusted CA (Comodo, etc.) would be the simplest solution. However, in the case of an intranet application, we can simply use self-signed certificates without any risk.

The installation of the self-signed certificate will be completed in two steps. We will first issue a fresh client certificate that is self-signed. The certificate will then become trusted on the webserver after the second step.

The following PowerShell script will create a fresh, two-year self-signed client certificate and store it in the user’s private certificates store:

New-SelfSignedCertificate -certstorelocation cert:\CurrentUser\my `
    -Subject "Test User" -FriendlyName "Test client certificate" `
    -NotAfter (Get-Date).AddYears(2) -KeyUsageProperty Sign `
    -KeyUsage CertSign, CRLSign, DigitalSignature

Now that a new certificate has been created inside the Personal certificates store, you can see it in the User Certificates control panel:

From this point, you can export the client certificate’s public key as a .cer file.

You must install the certificate contained in the CER file and add it to the Computer Certificates’ Trusted roots store on the webserver where IIS is installed.

Great! The client certificate has been prepared and is now ready for use on both the client and server sides.

3. Setup ASP.NET Core Authentication

In our ASP.NET Core application, we will lastly configure certificate authentication.

There is a separate NuGet package that contains the support for certificate authentication. So let’s start by including the Microsoft.AspNetCore.Authentication.Certificate package in our application.

The only step left is correctly configuring our authentication pipeline now that we have certificate support. To accomplish this, we add the following code to our Startup.Method ConfigureServices

services
    .AddAuthentication(CertificateAuthenticationDefaults.AuthenticationScheme)
    .AddCertificate(options =>
    {
        options.AllowedCertificateTypes = CertificateTypes.All;
    });

It is possible to customize the behavior of the certificate authentication handler using a number of options. To accept both chained and self-signed certificates in our case (only chained certificates are accepted by default), we only changed the AllowedCertificateTypes option.

Keep in mind that ASP.NET Core v3.0 includes the Microsoft.AspNetCore.Authentication.Certificate package. You must use a compatibility package named idunno.Authentication.Certificate, developed by Barry Dorrans, if your version of ASP.NET Core is older than 3.0.

Remember to actually include the authentication middleware in your ASP.NET Core request processing pipeline as well. Execute this within Startup.Configure the execution of the method:

app.UseAuthentication();

Testing

A client certificate is required when using a browser, such as Chrome, to access the Web API:

The certificate will then be verified by the webserver, and if everything is good, the request will be sent to your ASP.NET Core Web API. An illustration of the response will resemble this:

Test API call successful! Certificate Subject Name: Test User

On the other hand, you will get an error response if you don’t specify a certificate or if you choose an invalid/untrusted certificate:

HTTP Error 403

or

ERR_BAD_SSL_CLIENT_AUTH_CERT

Other References

Microsoft Docs article describing Certificate Authentication:

Configure certificate authentication in ASP.NET Core

A neat article explaining the general benefits of using certificate-based authentication:

What Is Certificate-Based Authentication and Why Should I Use It?

Conclusion

By limiting access to your ASP.NET Core controllers to clients who possess the client certificate, you can secure access to them using these 3 simple steps.

Pro Tip: You can experiment with the AddCertificate() call’s many options to implement custom validation based on a certificate property for an even more secure setup.

Do you think client certificates for authentication are useful? Comment below and let me know. Please share this article with your friends if you like it.