Adding development cert to ASP.NET Core on Linux

Trusting is hard. Knowing who to trust, even harder

Maria V. Snyder

Web security is very important topic for web development. Hackers can find creative ways to take advantage of unprotected resources. Majority of the browsers are already marking unsafe websites and doesn’t allow you to proceed to that website. Also, if you have SSL cert enabled, you get better ranking in search engines results. In production we usually buy SSL cert, wire everything up or use Let’s Encrypt automatic procedure (certbot) to do that instead of us.

If you are developing locally and want to test accordingly (http and https), you will need to setup development environment with SSL enabled.

The problem

To run ASP.NET Core Web Application on specific url, you can pass the environment variable ASPNETCORE_URLS (environment variables) and define your desired URL to be passed to Kestrel (it’s a listening web server and a command-line interface). In below case, we are making Kestrel listening on localhost port 5002.

Run dialog in Jetbrains Rider to define on which URL to run

If Kestrel is not aware of SSL cert, first run can be surprising and your website is a potential risk. We can continue of course, but doing this each time we run an application for developing, can hinder our productivity.

First run on HTTPS on Kestrel via JetBrains Rider

ASP.NET Core Framework has a nice utility, which helps you configure the whole SSL bootstrapping, which works awesome on Windows, but fails on Linux.

Utility you say?

ASP.NET Core has a great CLI support and an awesome list of global tools (special nuget package, that contains console application). From simple counter to complex one, like enabling certificates to be used in ASP.NET Core during development.

To install the tool for enabling certificates you can use the following command:

dotnet tool install -g dotnet-dev-certs
Dotnet global tool to install dev certs

The problem with this tool is, that it only works on Windows and MacOS. If you run this on Linux, nothing happens.

How to solve the problem on Linux?

Kestrel settings

Kestrel is open-source (source code available on GitHub), event-driven, asynchronous I/O based server used to host ASP.NET applications on any platform You can check the Kestrel samples here, if you want to see different options for ASP.NET Core application configuration.

Let’s configure Kestrel to use SSL cert to verify the secure connection. Kestrel has an option to define default path for certificates, which is what we can leverage to define path to our SSL cert.

We can use environment variables (preferred) or put it in the configuration file appsettings.json – Kestrel__Certificates__Default__Path. Default password is changeit.

"Kestrel": {
"Certificates": {
"Default": {
"Path": "pathtossl",
"Password": "changeit"
}
}
}

How to get the ssl certificate or where should we look?

mkcert

The easiest and the best way to generate a development certificate is to leverage mkcert cli utility. It is a simple tool for making locally-trusted development certificates. It requires no configuration and it is easy to install (follow instructions on the website).

When mkcert is installed, you need to create .p12 file (also known as pfx) to map it to Kestrel. mkcert utility has flag -pkcs12, which enables you to generate desired output (check flags here). If you manually compiled mkcert, don’t forget to make the utility executable (chmod +x mkcert)

Navigate to the folder, where you installed mkcert (you can use find utility to find it quickly).

mkcert folder and files

Run the following command on the first run:

mkcert -install

That should create new local certificate authority for us to issue certificates. Let’s create pfx certificate to map it to Kestrel.

./mkcert -pkcs12 localhost 127.0.0.1 ::1
create certificate for localhost

As you can see, we have the default password changeit, which we can change (the simplest way is to install the certificate and then exporting it from browser).

I will create a folder DemoTest in Documents folder and move certificate to that folder.

copy to demo folder

Let us set the certificate in the application.

Usage in ASP.NET Core Web Application

As written above, the easiest way to set the certificate is to define environment variable. In JetBrains Rider this is an easy task. Open Launch Configuration Dialog and edit environment variables section (or just double press SHIFT and start writing Run debug configurations).

Set environment variable

If you don’t know the path, just do pwd (print working directory) in the certificate directory. In my case, newly created DemoTest directory.

pwd output

Let’s see this in action. Press CTRL+F5 to run the application to see, if the app has picked up the ssl cert.

Successful run

You can check the video in action here.

Conclusion

Adding development certificate to Kestrel is an easy task, but IMHO should be done automatically as it is on Windows and MacOsx.

Maybe in the future this task will not be necessary and we will have support in global tool with one click of a button.