When to use Let's Encrypt's webroot and standalone authorization
Learn the most used auth challenges and when to use them
Motivation
Probably the two most used custom authorizations when it comes to Let's Encrypt is the webroot and the standalone. The former is the preferred in many scenarios, but knowing when it falls short is essential when you analyze your requirements. But knowing about the latter makes some setups far easier to implement, and also to tackle some complicated ones.
In this post you'll learn how they work and when to use each of them.
Webroot
Webroot authentication works by designating a folder which contents are available publicly. Certbot then places a file there then pings a remote server that tries to fetch it. If it is successful, then Let's Encrypt issues the certificate, as you've proven ownership of the domain.
That's why it's called webroot, as you need to specify the root of the web-serving domain.
The path the remote server tries to fetch the file from is known, it is http://domain/.well-known/acme-challenge/<file>.
One important aspect is the http part. Event though all your visitors might use HTTPS only, Let's Encrypt uses
HTTP by default, and it can not be configured.
But it follows redirects. That means that if you have a redirection in place, which you are likely to have to make your users use the secure endpoint, then you don't need to reconfigure anything on that end. In the cases when HTTP and HTTPS behave differently, or you don't use HTTP at all, this needs some further considerations.
Also, Let's Encrypt auth does not respect HSTS, even when it's preloaded, nor it checks the validity of the certificates. In effect, even though no visitors uses HTTP, Let's Encrypt will. But you can use a self-signed certificate before a valid one is issued to you.
To specify webroot auth and the directory, use:
certbot certonly/renew --webroot -w /path/to/webroot ...
Use it if
-
You use HTTP, even for a simple redirection
-
And there is a folder that is served as the webroot
For static content, this is usually where the index.html is.
- Or you can configure your server to serve
/.well-known/acme-challengefrom a directory
Effectively, this way you have a webroot but with limited scope.
Standalone
This authorization temporarily starts a webserver on port 80, just for the time of the auth process. As this is a standalone and self-contained solution, this is the easiest to configure, if you don't use that port.
For an API endpoint, you might only use HTTPS, where port 80 is free, and you can use this to get the certificate.
But unfortunately, most of the time port 80 is in use.
Scenario #1: port 80 is free
In this case, standalone auth is the way to go. Basically, you have nothing to change in your app, and the certificate issuance/renewal process will just work.
Keep in mind that you need to restart the app when a new cert is issued, as most servers will continue to use the old ones.
To specify the standalone auth and restart the app on a new certificate, use:
certbot certonly/renew --standalone --deploy-hook="restart app..." ...
Scenario #2: port 80 is used
If port 80 is used, either use webroot auth instead, or shut down the app during renewals.
The latter sounds drastic, but in reality very few users will even notice. The renewals happen around every 2 months, and a new certificate usually requires an app restart, so you'll have some downtime either way.
As the whole auth process takes less than half a minute, it's usually better to just embrace this. But ultimately, this is your call whether or not that is acceptable.
To use standalone authorization and shut down the app during the process, use:
certbot certonly/renew --standalone --pre-hook "shut down app..." --post-hook "start app..." ...
Use it if
-
You don't use port 80
-
Or you don't mind a less than 1 minute downtime every two months
More complicated use cases
With these two auth challenges, you can easily configure an evergreen certificate for most use cases. But what if you need something more customized? Certbot supports several hooks that can adapt to most use cases, and we'll cover them in the next post. Stay tuned!
