Using the webroot domain verification method

Server
1

The following is outdated!

See the comment below for notes updated on 2nd December 2015.

Some notes on using the webroot domain verification process with the test ACME server (don’t do this on a live server yet!) in case anyone else wants to have a play with this — this method will be best suited for use on servers that you don’t want any downtime on when renewing certs.

Checkout and install, initially using the standalone method, (note that the git clone URL will be outdated when the pull request is merged), these are the steps that you need to follow on Debian Jessie servers (haven’t tested on anything else)

# delete existing copies of the code if they exist
rm -rf /your/path/letsencrypt/ /etc/letsencrypt/ /var/lib/letsencrypt/
# install in /usr/local and run using standalone once
cd /usr/local
git clone -b simplefs https://github.com/kuba/letsencrypt 
cd letsencrypt/
bash bootstrap/debian.sh
virtualenv --no-site-packages -p python2 venv
./venv/bin/pip install -r requirements.txt acme/ . letsencrypt-apache/ letsencrypt-nginx/ 
/usr/local/letsencrypt/venv/bin/letsencrypt auth

Set up Apache (or whichever server you are running) create /etc/apache2/conf-available/letsencrypt.conf containing:

<IfModule mod_headers.c>
  <LocationMatch "/.well-known/acme-challenge/*">
    Header set Content-Type "application/jose+json"
  </LocationMatch>
</IfModule>

And then enable it:

a2enmod headers
a2enconf letsencrypt

Then generate a key and cert using the webroot method, optionally supplying multiple domain names to be used as subjectAltNames (SANs)

/usr/local/letsencrypt/venv/bin/letsencrypt --renew-by-default -a webroot --webroot-path /var/www/example.org --email example@example.org --text --agree-eula --agree-tos -d example.org -d example.org.uk auth

For the cert that was created using the standalone method to start with you can switch this to the webroot method for renewals by editing /etc/letsencrypt/renewal/example.org and editing:

authenticator = standalone
webroot_path = None
domains = None

Into:

authenticator = webroot
webroot_path = /var/www/example.org
domains = example.org,

Edit your server config or create symlinks to the cert.pem, privkey.pem and chain.pem in /etc/letsencrypt/live/example.org.

9 Likes
2

glad to see some more development on the web root method

fyi missing a space

--email example@example.org--text
3

@eve2000 thanks. typo fixed.

The only thing that the webroot plugin lacks at the moment is support for supplying --webroot-path multiple times, but this isn’t a feature I need — I’m happy with one cert per directory.

I think this method is going to be the simplest for people to script to work with existing servers as it doesn’t touch the web server config when run and also doesn’t require any downtime.

1 Like
4

Indeed, web root plugin is only thing I need. I just finished a guide for using Letsencrypt web root authentication for my Centmin Mod LEMP stack’s Nginx integration at https://community.centminmod.com/threads/letsencrypt-free-ssl-certificates-with-web-root-authentication-method.4635/ for CentOS 6.x/7.x :smile:

5

The webroot plugin has been merged so the instructions at the start of this thread are now out of date, rather than pulling the simplefs branch the main branch can be used:

git clone https://github.com/letsencrypt/letsencrypt
1 Like
6

YAY ! finally merged !

1 Like
7

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
8

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
9

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:

10

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

1 Like
11

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...

12

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
13

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

1 Like
14

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

15

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.

16

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

17

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.

18

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

19

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.

20

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.