Using the webroot domain verification method

Here’s a little trick we’re using with nginx and the webroot validator to automate letsencrypt with software that isn’t a webserver. This allows you to validate any domain pointed at your server regardless of whether there’s a website behind it and without having to have a free port 443 for the standalone authenticator.

Create /etc/letsencrypt/webrootauth/

In /etc/nginx/snippets/letsencryptauth.conf

location /.well-known/acme-challenge {
    alias /etc/letsencrypt/webrootauth/.well-known/acme-challenge;
    location ~ /.well-known/acme-challenge/(.*) {
        add_header Content-Type application/jose+json;
    }
}

In /etc/nginx/sites-enabled/default (or wherever your default server block is. You DO have one, right?)

server {
    listen 80 default_server;
    root /etc/letsencrypt/webrootauth;
    include snippets/letsencryptauth.conf;
}

server {
    listen 443 ssl spdy default_server;
    ssl on;
    # This can be any cert on your system, it doesn't matter.
    # I think the letsencrypt DV accepts a self-signed cert.
    ssl_certificate ssl/default/default.crt;
    ssl_certificate_key ssl/default/default.key;

    root /etc/letsencrypt/webrootauth;
    include snippets/letsencryptauth.conf;
}

Then just use the letsencrypt client + webroot authenticator normally with

--webroot-path /etc/letsencrypt/webrootauth

included in the parameters.

You can also include snippets/letsencryptauth.conf in your other server configs to allow using your “global” webroot for them too, it won’t break anything.

2 Likes

Thanks Leliana I have been doing the same kind of thing with Apache, in my case I want to be able to password protect an entire site using a .htaccess file and still have a Let’s Encrypt cert for it, I have been using /var/www/well-known for the Let’s Encrypt generated files. In the Apache config for the VirtualHost you simply need an Alias, for example:

Alias "/.well-known/acme-challenge" "/var/www/well-known/example.org/.well-known/acme-challenge"

Make sure the directory exists:

mkdir -p /var/www/well-known/example.org

And run the client with:

--webroot-path /var/www/well-known/example.org
2 Likes

looks like latest version changed the path to letsencrypt binary has changed from letsencrypt/venv/bin/letsencrypt to relative .local/share/letsencrypt/bin/letsencrypt and options have been removed for --agree-eula and new option --agree-dev-preview added

changes for me in Centmin Mod Nginx server for letencrypt web root authentication https://community.centminmod.com/posts/19859/

so @chrisc might need to update your above guide :slight_smile:

BTW here is the official doc: https://letsencrypt.readthedocs.org/en/latest/api/plugins/webroot.html?highlight=webroot#module-letsencrypt.plugins.webroot

1 Like

At first: Can someone just explain the basic facts of this "webroot authentication method". What makes it different from other authentication methods? What is it advantage/goal and in what cases can/should it be used?

And can it be used in this case - because it looks like it does not require many(/any?) command line usage.

All docs I could found about this only show how to use this method, but not why...

I actually outlined webroot authentication at Letsencrypt Webroot Authentication Tested on Beta invited/whitelisted domain

As to why use webroot, I mentioned my thoughts here Preventing Letsencrypt 3rd party clients going the Android way? - #3 by kelunik

unfortunately webroot authentication does require SSH access to run so not suited for shared hosting

My vision for webroot authentication is to make it easier for control panels, or folks who know their web server/OS environments best to pre-create their https vhost configurations prior to running webroot authentication.

1 Like

Nice. So the information were just spread about several topics…
Good to have them here finally.

1 Like

yeah bit spread out :slight_smile:

also webroot authentication useful for non-standard nginx/apache or other web server setups where paths to web server config files and structure are unknown to letsencrypt

how does webroot require SSH I read that manual mode + webroot is the perfect way to get a cert from your home PC and push the challenge and later the cert to the server.

webroot still runs letsencrypt client which is run in ssh. see my example at https://community.centminmod.com/posts/19914/

well the client itself doesnt need SSH but rather terminal access at any server (at least that’s what I read) so you can us4e a VM, raspi or anything that runs linux let it run the auth in manual mode you get the challenge, upload it to your server and get your cert.

well SSH = terminal as you’d still need to point domain dns to ip of the terminal accessed server for webroot

as seen in the quote,manual mode does not need SSH on the target server, just a way to get files (for webroot) and the cert (obviously) on it. so you can use any computer that is compatible with LE to get your cert.

As far as I understood it you can use the LE on your desktop computer e.g., but you (temporarily) have to change the ip associated with the domain you want to generate a cert for, so that it points to your desktop computer.
If it is like this this is not really different than just using any other normal authentication method after you change the DNS entry.

but I dont see any need to change the DNS it just checks whether the challenge lies on the domain so if the user puts the challenge from the LE client (which doesnt have any DNS entries) to the Webserver (obviously in the domain DNS) then LE just checks “here’s the challenge, so I am happy” doesnt it?

maybe not with DVSNI (I dont even know what that means) but when you use webroot and manual mode together then we have it.

You don’t have to change anything in your DNS configuration for manual mode. Just your webserver config.

yes if user manually setups up the .well-known uri and proper content-type response as application/jose+json on the web server, then LE client should be able validate the domain.

well that sounds well and chnging a mime type is just some htaccess so that sounds easy to me.

(but why does it actually need to be changed doesnt it need to just get the text and read it? especially if the type is already known LE should check for plausibility [valid json+jose file], what should be done anyway since any file could be marked as some mime type and if that check succeeds just read the contents of it and get the challenge.

Thanks to these instructions, I was able to use the webroot method successfully. Works well!

I didn’t find out about the switch “-a” elsewhere. I think it should be added to the documentation. It’s also not mentioned in the output give when using “–help”.

Is application/jose+json still a thing? The spec changed to text/plain, but it’s also in discussion to change it and give it an extension: https://github.com/ietf-wg-acme/acme/issues/9

1 Like