How to Secure a Custom Experience Domain with Let's Encrypt
Securing your Losant Experience Domain with an SSL certificate is crucial to ensuring the safe and encrypted transfer of data using your custom domain. All Experience Slugs are encrypted automatically, therefore obtaining an SSL certificate is only required to secure your custom domain.
Let’s Encrypt allows developers to obtain the digital certificates needed to enable HTTPS (SSL/TLS) for their custom domains for free. It is not required to use Let’s Encrypt to obtain an SSL; you have the flexibility to use any Certificate Authority you choose.
This guide will describe how to obtain an SSL certificate from Let’s Encrypt, and how to implement that certificate to secure your Experience Domain.
Here’s what you’ll need:
- A domain from any registrar.
- Docker, which we’ll use to generate the certificate.
- An Application Experience.
Before you can set up an SSL and secure requests to your Experience Domain, you’ll need to first point your domain to your Application Experience. See our guide on configuring DNS records to point a custom domain with your Losant Experience.
Once you’ve configured your domain in Losant and added the proper DNS Records, and DNS propagation has completed (can take anywhere from 5 minutes to 24 hours), you can visit your domain in a web browser and see your Experience!
Certbot is a free, open-source software tool for generating Let’s Encrypt SSL certificates. They provide a Docker container that, once run, allows you to save your SSL certificate right to your computer for easy transfer to Losant.
Here’s the command:
docker run -it --rm --name certbot \ -v "$PWD/my-ssl-certificates:/etc/letsencrypt" \ -v "$PWD/my-ssl-certificates:/var/lib/letsencrypt" \ certbot/certbot certonly --manual --preferred-challenges dns
This command mounts a volume on your computer to a directory inside the Certbot container so that the output from the container will be accessible.
$PWD in the directory path represents the Present Working Directory of your machine. If the directory
my-ssl-certificates does not exist in your Present Working Directory, Docker will create that directory when you run this command.
Once you press
Enter on the Docker command, you will be walked through creating your SSL certificate.
Once you get to the option to enter your domain name, make sure to include the subdomain you pointed your domain’s CNAME record to (i.e.
Then, you will be prompted to add a DNS TXT Record in your domain registrar to verify you have control of this domain. Create a new DNS TXT Record …
- Set the “host” to
YOUR_SUBDOMAINis the subdomain used when pointing a CNAME record to your experience (i.e. “www” or “my-iot-application”).
- Set the value to what is provided in the prompt (i.e. “Q6rTXKAyjEk3a8vESCm7Syiho5z5VQttsAqZGKcXVoo”).
After you save the new TXT Record in your domain registrar, wait a few minutes (up to 24 hours) for the record to propagate, and then press
Enter in your terminal.
Now that you’ve successfully created an SSL key and certificate, it’s time to add it to your Losant Experience.
In Step 1, you referenced a directory on your computer with
$PWD/my-ssl-certificates, or a different directory. Go to the directory you used, and you’ll find a series of directories, including one called ‘live’:
live directory, and you’ll find another directory matching the domain name you entered:
In the directory named after your domain, you’ll find a few files. The ones you’ll need to enter into your Losant application are “privkey.pem” and “cert.pem”:
privkey.pem file in a text editor of your choice, copy the contents of
privkey.pem and paste them into the SSL Key section on the domain configuration page (including the
BEGIN KEY line and
END KEY lines):
Then do the same for the
cert.pem file. Open the file in a text editor of your choice, copy and paste the contents of the
cert.pem file into the SSL Certificate field, then press “Save Domain”. In this guide, it is not necessary to put anything into the SSL Bundle field.
You will be redirected back to the Domains page of your experiences, where you will notice a latched lock next to your domain:
If you click on your domain, and go to the domain configuration page, you will see a green box that says your domain is secure:
When running the Docker container, it is important to note that Docker only recognizes certain paths for folders. If you ran the Docker command in Step 2 with a tilde to represent your home directory (instead of
$PWD), or did not provide a directory that is allowable by Docker, you will receive the following error:
docker: Error response from daemon: create ~/my-ssl-certificates: "~/my-ssl-certificates" includes invalid characters for a local volume name, only "[a-zA-Z0-9][a-zA-Z0-9_.-]" are allowed. If you intended to pass a host directory, use absolute path.
If you are using MacOS/Linux, you can replace the tilde with
$PWD if you would like to create the
my-ssl-certificates directory in the directory you are currently in. Alternatively, as Docker suggests, you can use an absolute path for the home directory instead of
$PWD. For instance,
If you change your directory, or attempt to run the Certbot Docker container again, you may receive the following error:
docker: Error response from daemon: Conflict. The container name "/certbot" is already in use by container "17d2cf9d0318156c5993115e22fcf124ebc3a5bda9fc4bf712815a67f03b913e". You have to remove (or rename) that container to be able to reuse that name.
You can resolve this issue in one of two ways:
- Rename the container in the docker command from step one. Specifically, change
--name. So the first line of the new command would look similar to
docker run -it --rm --name certbot-2 \.......
- Delete the previously used container. You can do this by running
docker container rm <container-name>where
<container-name>is the name of the container you ran. If you ran the Docker command given in Step 1.
When attempting to verify that you have control of the domain name, and have created a TXT record with the correct information, you can get the following error:
This can mean a few things:
- The host for the TXT record is not correct
- For example instead of
_acme-challenge.wwwfor the host, you entered
- For example instead of
- The DNS hasn’t propagated yet. DNS propagation can take up to 24 hours.
When attempting to save your domain in Losant, you get an error that the certificate does not match the domain you’ve provided.
In this case, you will need to ensure that you copied and pasted the certificate correctly. Once you have confirmed that you have, you will need start over at Step 2 and ensure that you enter the domain name into your terminal correctly.