Introduction
Deploying an HTTPS ASP.NET Core application with an SSL certificate may seem trivial at first glance, especially with services like Let's Encrypt making certificates free and accessible. In practice, however, it can quickly become complicated, especially when you combine this process with the deployment of modern applications in containerised environments.
Setting up SSL certificates requires a series of precise operations: you need to know how to mount certificate files correctly in a DOCKER container so that they can be accessed by the application, manage file formats such as PEM or RSA to ensure they are compatible with Kestrel (ASP .NET Core's integrated web server) and configure environment variables appropriately so that the application can use them correctly. Each of these steps, if not carried out carefully, can introduce errors or complications.
In this article, we'll focus solely on the process of configuring an ASP.NET Core application for HTTPS with an SSL certificate auto-generated by Let's Encrypt. We'll look at how to install Certbot, generate the SSL certificate, configure Kestrel for HTTPS, and deploy the application in a Docker container. To follow this guide, you'll need a Linux server with Docker already installed and configured, and you'll need to master the basic commands for creating and managing images. By following these steps, you can easily configure your applications using the HTTPS protocol.
Step 1- Install Certbot on a Linux server.
The first step in obtaining a free SSL certificate from Let's Encrypt is to install Certbot on your Linux server. CertBot is a command-line tool that makes it easy to request SSL/TLS certificates.
- Update your server and install Certbot.
# For Ubuntu/Debian
sudo apt update
sudo apt install certbot-y
Step 2- Generate the SSL Certificate with Let's Encrypt (CertBot).
To obtain an SSL certificate with Let's Encrypt using the DNS-01 challenge, you need to prove ownership of your domain by creating a specific DNS TXT record. Here's how to do it:
- Generate an SSL certificate with the DNS-01 challenge:
sudo certbot certonly --manual --manual-auth-hook /etc/letsencrypt/acme-dns-auth.py --preferred-challenges dns --debug-challenges -d your-domain.com --key-type rsa
This command uses certonly to just get the certificate without automatically configuring a web server, giving us full control over its use, especially for custom deployments like Docker.
The --Manual option is chosen to validate the certificate via a manually managed DNS challenge, useful when the DNS provider doesn't support automation, and --Manual-auth-hook specifies the script that helps automate the creation of the necessary DNS record.
Finally, using --preferred-challenges dns indicates that the DNS-01 challenge is preferred, as it is more flexible in many environments.
Once this command has been run, Certbot will ask you to create a specific DNS record to validate domain ownership. Follow the instructions provided.
- Follow Certbot's instructions for the DNS challenge:
After running the Certbot command, Certbot will ask you to create a DNS TXT record to validate the ownership of your domain. You should get output similar to this:
Please deploy a DNS TXT record under the name
_acme-challenge.your-domain.com with the following value:
ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789
- Add the DNS TXT record.
Go to the DNS management section of your domain provider and create a new TXT record with the details provided by Certbot.
Type : TXT
Nom : _acme-challenge.dev
Valeur : ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789
- Validate the DNS challenge with Certbot.
Return to the terminal where you launched Certbot and press Enter to continue. Let's Encrypt will check the DNS record, and if correctly configured, issue the SSL certificate.
💡By default, certificates are located here: /etc/letssencrypt/live/.
Step 3- Verify and convert the private key.
Once the certificate and private key have been generated, it is important to check that the PEM format files are correctly formatted and ready for use with Kestrel.
- Verify the private key generated by Certbot:
sudo openssl rsa -in /etc/letsencrypt/live/your-domain.com/privkey.pem -check
- Convert the private key to another format if necessary:
By default, the keys generated by Let's Encrypt with Certbot are in RSA format, as we specified in step 1. However, if you have specified another format or used another tool to generate the key, you can convert it to the RSA format expected by Kestrel with the following command:
sudo openssl rsa -in /etc/letsencrypt/live/your-domain.com/privkey.pem -out /etc/letsencrypt/live/your-domain.com/privkey-rsa.pem
This conversion ensures that the key is in the format expected by Kestrel in the ASP.NET CORE application.
Step 4 - Run the Docker Container with the PEM files.
When deploying your application in a Docker container, you need to mount the certificate and private key PEM files so that Kestrel can access them.
Use the following command to run the Docker container on your server:
sudo docker run -it -p 443:81 -p 80:80 \
-e ASPNETCORE_URLS="https://*:81;http://*:80" \
-v /etc/letsencrypt:/cert \
-e ASPNETCORE_Kestrel__Certificates__Default__Path=/cert/live/your-domain.com/fullchain.pem \
-e ASPNETCORE_Kestrel__Certificates__Default__KeyPath=/cert/live/your-domain.com/privkey.pem \
-e my-docker-repository/my-docker-image:latest
This command mounts the folder containing the PEM files (private key and certificate) in the Docker container ( -v /etc/letsencrypt:/cert), allowing the application to access them.
Environment variables specify the paths to the PEM files in the container for Kestrel to use on startup, ensuring secure HTTPS connections.
Step 5 - Run the Docker container with the PEM files.
Once you've followed all the steps, it's time to test your application to make sure everything is working properly. Go to the address https://your-domain.com in your web browser. If the SSL certificate has been correctly installed and configured, you should see a secure connection with the padlock icon displayed in the address bar. This indicates that traffic between your server and the client is now encrypted and secure.
If everything is configured correctly, your ASP.NET application is now successfully deployed in a secure environment using Docker and a Let's Encrypt SSL certificate.
With this approach, you can easily secure the production deployment of your .NET applications while taking advantage of the flexibility and efficiency of Docker, which enables portable deployment on any environment.
Quentin Destrade