Certificate Authentication in ASP.NET Core 3.0

This article shows how Certificate Authentication can be implemented in ASP.NET Core 3.0. In this example, a shared self signed certificate is used to authenticate one application calling an API on a second ASP.NET Core application.

Code https://github.com/damienbod/AspNetCoreCertificateAuth

Posts in this series


2019-09-06: Updated Nuget packages, .NET Core 3 preview 9

Setting up the Server

Add the Certificate Authentication using the Microsoft.AspNetCore.Authentication.Certificate NuGet package to the server ASP.NET Core application.

This can also be added directly in the csproj file.

<Project Sdk="Microsoft.NET.Sdk.Web">


    <PackageReference Include="Microsoft.AspNetCore.Authentication.Certificate" 
      Version="3.0.0-preview6.19307.2" />

    <None Update="sts_dev_cert.pfx">


The authentication can be added in the ConfigureServices method in the Startup class. This example was built using the ASP.NET Core documentation. The AddAuthentication extension method is used to define the default scheme as “Certificate” using the CertificateAuthenticationDefaults.AuthenticationScheme string. The AddCertificate method then adds the configuration for the certificate authentication. At present, all certificates are excepted which is not good and the MyCertificateValidationService class is used to do extra validation of the client certificate. If the validation fails, the request is failed and the request for the resource will be rejected.

public void ConfigureServices(IServiceCollection services)

		.AddCertificate(options => // code from ASP.NET Core sample
			options.AllowedCertificateTypes = CertificateTypes.All;
			options.Events = new CertificateAuthenticationEvents
				OnCertificateValidated = context =>
					var validationService =

					if (validationService.ValidateCertificate(context.ClientCertificate))
						var claims = new[]
							new Claim(ClaimTypes.NameIdentifier, context.ClientCertificate.Subject, ClaimValueTypes.String, context.Options.ClaimsIssuer),
							new Claim(ClaimTypes.Name, context.ClientCertificate.Subject, ClaimValueTypes.String, context.Options.ClaimsIssuer)

						context.Principal = new ClaimsPrincipal(new ClaimsIdentity(claims, context.Scheme.Name));
						context.Fail("invalid cert");

					return Task.CompletedTask;



The AddCertificateForwarding method is used so that the client header can be specified and how the certificate is to be loaded using the HeaderConverter option. When sending the certificate with the HttpClient using the default settings, the ClientCertificate was always be null. The X-ARR-ClientCert header is used to pass the client certificate, and the cert is passed as a string to work around this.

services.AddCertificateForwarding(options =>
	options.CertificateHeader = "X-ARR-ClientCert";
	options.HeaderConverter = (headerValue) =>
		X509Certificate2 clientCertificate = null;
			byte[] bytes = StringToByteArray(headerValue);
			clientCertificate = new X509Certificate2(bytes);

		return clientCertificate;

The Configure method then adds the middleware. UseCertificateForwarding is added before the UseAuthentication and the UseAuthorization.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)


	app.UseEndpoints(endpoints =>

The MyCertificateValidationService is used to implement validation logic. Because we are using self signed certificates, we need to ensure that only our certificate can be used. We validate that the thumbprints of the client certificate and also the server one match, otherwise any certificate can be used and will be be enough to authenticate.

using System.IO;
using System.Security.Cryptography.X509Certificates;

namespace AspNetCoreCertificateAuthApi
    public class MyCertificateValidationService
        public bool ValidateCertificate(X509Certificate2 clientCertificate)
            var cert = new X509Certificate2(Path.Combine("sts_dev_cert.pfx"), "1234");
            if (clientCertificate.Thumbprint == cert.Thumbprint)
                return true;

            return false;

The API ValuesController is then secured using the Authorize attribute.

public class ValuesController : ControllerBase


The ASP.NET Core server project is deployed in this example as an out of process application using kestrel. To use the service, a certificate is required. This is defined using the ClientCertificateMode.RequireCertificate option.

public static IWebHost BuildWebHost(string[] args)
  => WebHost.CreateDefaultBuilder(args)
  .ConfigureKestrel(options =>
	var cert = new X509Certificate2(Path.Combine("sts_dev_cert.pfx"), "1234");
	options.ConfigureHttpsDefaults(o =>
		o.ServerCertificate = cert;
		o.ClientCertificateMode = ClientCertificateMode.RequireCertificate;

Implementing the HttpClient

The client of the API uses a HttpClient which was create using an instance of the IHttpClientFactory. This does not provide a way to define a handler for the HttpClient and so we use a HttpRequestMessage to add the Certificate to the “X-ARR-ClientCert” request header. The cert is added as a string using the GetRawCertDataString method.

private async Task<JArray> GetApiDataAsync()
		var cert = new X509Certificate2(Path.Combine(_environment.ContentRootPath, "sts_dev_cert.pfx"), "1234");

		var client = _clientFactory.CreateClient();

		var request = new HttpRequestMessage()
			RequestUri = new Uri("https://localhost:44379/api/values"),
			Method = HttpMethod.Get,

		request.Headers.Add("X-ARR-ClientCert", cert.GetRawCertDataString());
		var response = await client.SendAsync(request);

		if (response.IsSuccessStatusCode)
			var responseContent = await response.Content.ReadAsStringAsync();
			var data = JArray.Parse(responseContent);

			return data;

		throw new ApplicationException($"Status code: {response.StatusCode}, Error: {response.ReasonPhrase}");
	catch (Exception e)
		throw new ApplicationException($"Exception {e}");

If the correct certificate is sent to the server, the data will be returned. If no certificate is sent, or the wrong certificate, then a 403 will be returned. It would be nice if the IHttpClientFactory would have a way of defining a handler for the HttpClient. I also believe a non valid certificates should fail per default and not require extra validation for this. The AddCertificateForwarding should also not be required to use for a default HTTPClient client calling the service.

Certificate Authentication is great, and helps add another security layer which can be used together with other solutions. See the code and ASP.NET Core src code for further documentation and examples. Links underneath.






  1. […] Certificate Authentication in ASP.NET Core 3.0 – Damien Bowden […]

  2. […] Certificate Authentication in ASP.NET Core 3.0 (Damien Bowden) […]

  3. […] Certificate Authentication in ASP.NET Core 3.0 (Self Signed) […]

  4. Hi Damien, thank you for all these guides into the wonderful world of .Net core and authentication. Can you email me at av@validators.com – if you can help me (paid work) with some certificates in dotnet core. Thanks.

  5. Michael Lüthi · · Reply

    I’ve got downloaded the sample and it starts fine when using IIS Express. Switching to kestrel standalone (command line) let the browser reject the connection because of invalid cn. Ignoring this on browser level let the browser ask vor any client certificate but even if i choose the right one handlers never get reached. Do you have any idea why?

    PS: the client application therminates the http-contection imediatly by throwing an Exception

  6. Hi Michael

    I never tested this, will have a look at it, and get back to you.

    Greetings Damien

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: