Customizing ASP.NET Core Part 4: HTTPS

HTTPS is on by default now and a first-class feature. In Windows, the certificate which is needed to enable HTTPS is loaded from the Windows Certificate Store. If you create a project on Linux and Mac the certificate is loaded from a certificate file.

Even if you want to create a project to run it behind and IIS or an NGinX webserver HTTPS is enabled. Usually you would manage the certificate on the IIS or NGinX webserver in that case. But this shouldn't be a problem and you shouldn't disable HTTPS in the ASP.NET Core settings.

Managing the certificate within the ASP.NET Core application directly makes sense if you run services behind the firewall, services which are not accessible from the internet. Services like background services for a microservice-based application, or services in a self-hosted ASP.NET Core application.

There are some scenarios where it makes sense to also load the certificate from a file on Windows. This could be in an application that you will run on Docker for Windows, and also on Docker for Linux.

Personally, I like the flexible way to load the certificate from a file.

The Series Topics

• Customizing ASP.NET Core Part 01: Logging
• Customizing ASP.NET Core Part 02: Configuration
• Customizing ASP.NET Core Part 03: Dependency Injection
• Customizing ASP.NET Core Part 04: HTTPS - This article
• Customizing ASP.NET Core Part 05: HostedServices
• Customizing ASP.NET Core Part 06: MiddleWares
• Customizing ASP.NET Core Part 07: OutputFormatter
• Customizing ASP.NET Core Part 08: ModelBinder
• Customizing ASP.NET Core Part 09: ActionFilter
• Customizing ASP.NET Core Part 10: TagHelpers

Setup Kestrel

As well as in the first to parts of this blog series, we need to override the default WebHostBuilder a little bit. With ASP.NET Core it is possible to replace the default Kestrel-based hosting with a hosting based on an HttpListener. This means the Kestrel web server is configured somehow to the host builder. You are able to add and configure Kestrel manually by using it. That means by calling the UseKestrel() method on the IWebHostBuilder:

public class Program
{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseKestrel(options => 
{
})
.UseStartup<Startup>();
}

This method accepts an action to configure the Kestrel web server. What we actually need to do is to configure the addresses and ports the web server is listening on. For the HTTPS port, we also need to configure how the certificate should be loaded.

.UseKestrel(options => 
{
options.Listen(IPAddress.Loopback, 5000);
options.Listen(IPAddress.Loopback, 5001, listenOptions =>
{
listenOptions.UseHttps("certificate.pfx", "topsecret");
});
})

In this snippet, we add to addresses and ports to listen on. The second one is defined as secure endpoint configured to use HTTPS. The method UseHttps() is overloaded multiple times, to load certificates from the Windows Certificate Store as well as from files. In this case, we use a file called certificate.pfx located in the project folder.

To create such a certificate file to just play around with, this configuration opens the certificate store and exports the development certificate created by Visual Studio.

For Your Safety

Use the following line ONLY to play around with this configuration:

listenOptions.UseHttps("certificate.pfx", "topsecret"); 

The problem is the hard-coded password. Never ever store a password in a code file that gets pushed to any source code repository. Ensure you load the password through the configuration API of ASP.NET Core. Use the user secrets on your local development machine and use environment variables on a server. In Azure, use the Application Settings to store the passwords. Passwords will be hidden on the Azure Portal UI if they are marked as passwords.

Conclusion

This is just a small customization. Anyway, this helps if you want to share the code between different platforms, if you want to run your application on Docker and don't want to care about certificate stores, etc.

Usually, if you run your application behind a web server like IIS or NGinX, you don't need to care about certificates in your ASP.NET Core application. But you need to if you host your application inside another application, on Docker or without an IIS or NGinX.