To serve encrypted traffic with HTTPS, Saltcorn needs an SSL certificate. The Let's Encrypt organisation issues these for free, and Saltcorn contains functionality to obtain such a certificate to enable HTTPS encrypted traffic. Alternatively, you can provide your own SSL certificate.
Warning: there is a risk in this process that you may "brick" your server, such that you will not be able to to contact it again through your browser. Make sure you backup the server before proceeding.
Securing single tenants with Let's Encrypt
To obtain a certificate, the following must be true:
- you have directed a domain to your server
- you are currently using this domain to administer your server using unencrypted HTTP traffic
- you have entered this domain as the Base URL in your Saltcorn configuration
- you do not use the multi-tenancy feature. Obtaining wildcard certificates with Lets encrypt is currently not supported
if this is all true, and you have backed up your instance, you can go to the settings menu where there should be an option to enable let's encrypt HTTPS. Click this button. If you receive a green notification that let's encrypt SSL is enabled, and you should restart the server, click the "restart server" button at the top of the admin page. The first time you reload after the restart there may be a delay because obtaining certificates can take some time. If you do not get a response try again in 15 seconds.
Disable Let's Encrypt
if you would like to disable the certificate from Let's Encrypt, go to the configuration page under settings, go to the very bottom where it says let's encrypt enabled, and then press the trash icon to the right for that line. After doing this you should restart the server under settings -> admin. You may then encounter the problem below:
Multi-tenancy / custom certificates
SSL certificates obtained directly from let's encrypt from within Saltcon are only for single domains. If you would like to secure a multi-tenancy installation, or for some other reason would like to use your own certificate that you may have purchased, you can enter the SSL certificate and the SSL private key in the Saltcorn configuration. To secure a multi-tenancy installation you need a wildcard certificate.
Go to the settings-> configuration menu, and under authentication you can enter the certificate and the private key for a custom SSL certificate. If your certificate has two parts, they need to be concatenated one after the other in the certificate field. When both of these two configurations fields (certificate and private key) have been filled, restart the server from the admin menu. You should then be able to contact the server using the HTTPS protocol.
Obtaining a free wildcard certificate from Let's Encrypt
Follow these instructions to generate a wildcard SSL certificate using Let's Encrypt. During this process, you will need to be able to modify your DNS entry with your registrar/nameserver.
As an example, to obtain a wildcard certificate for the domain openbrain.org I use the following procedure:
- on Ubuntu 20.04, logged in as root,
- with DNS A records for @ and * hosts pointing to the server's IP address
- run: apt install letsencrypt
- run, changing the blue parts: certbot certonly --manual --preferred-challenges=dns --email [email protected] --server https://acme-v02.api.letsencrypt.org/directory --agree-tos -d "*.openbrain.org" -d openbrain.org
- add a new DNS TXT entry as instructed. The host part of the entry probably should be _acme-challenge and the value should be the ~20 characters long random string
- if all is well, certbot will write two files with the certificate and the private key. Copy the contents to your Saltcorn configuration (you should simultaneously be logged in in your browser) for the certificate and private key, respectively.
- Restart your Saltcorn server through the admin menu
Help! I can no longer contact my server!
If let's encrypt has been set up, it sends a permanent redirect from HTTP to HTTPS to your browser. Your browser remembers this and every time you try to contact http://mydomain.com it will redirect to https://mydomain.com. If your SSL certificate was in fact incorrectly setup for some reason, you will now no longer be able to contact your server through your browser! To fix this, you need to make your browser "forget" the permanent redirect from HTTP to HTTPS. Clearing your browser cache should accomplish this, or you can use a private/incognito window.