How to use a Cloudflare API Token for LetsEncrypt Validation on Ubuntu 20.04

Cloudflare API authentication Options

Cloudflare offers users two types of programmatic authentication. The biggest difference between the two is blast radius.

When I say blast radius I mean: how much stuff could get blown up if the credentials fall into the wrong hands.

The option with the largest blast radius is the API Key offering

Your Cloudflare Global API key allows full access to the entire Cloudflare API. You can add domains, delete domains, change DNS zone records, etc. Also, this API key does not expire until you manually change it.

You DO NOT want to leave this key sitting in an insecure location!

The second option, with a MUCH smaller blast radius is called API Tokens.

As you can see here I have two different API Tokens defined. Each of them are for different scripts and they have a very limited scope and duration.

Using API Tokens for things like LetsEncrypt just makes sense because if someone gets a hold of these keys, the worst thing they can do is mess with DNS records for a single zone.

Cloudflare API Tokens for LetsEncrypt

My preferred flavor of Linux for server purposes is Ubuntu. Unfortunately, the Python modules and the apt installable packaged versions of certbot do not satisfy the minimum version to use API Tokens for Cloudflare DNS validation.

So to make it work, we need to install certbot and its dependencies on our own.

Installing pip

We will install certbot directly from Python’s package repository. Out of the box Ubuntu 20.04 has Python3 but it doesn’t have pip installed. We can do that with this command:

sudo apt install python3-pip -y

Once we have pip installed we can install the certbot package with pip.

Installing certbot

To install certbot we not use pip. We will also install the Cloudflare module, although it is not new enough to support API Tokens, so we will overwrite part of it later. This just gets all of the other stuff installed for us too.

sudo python3 -m pip install certbot certbot-dns-cloudflare

If we wanted to use API keys we would have everything we need to do it. But we already dicussed why we want to use tokens.

If you were to try to use a token now, you will get an error.

Installing the latest Cloudflare python module from source

Until pip has a newer version of python-cloudflare, we can just install it from source.

git clone
cd python-cloudflare
python3 build
sudo python3 install
pip3 freeze | grep cloudflare

The final output of pip3 freeze should show you that you now have version 2.8.13 of cloudflare and the 1.8.0 of certbot-dns-cloudflare.

Validation with Cloudflare

Now we can create our INI file for the API Token and run the command to get our certificate.

You can put your ini file where ever you want, but I recommend putting it somewhere only the root user can read. I use nano, if you prefer vi or something else use that.

echo "dns_cloudflare_api_token = ${TOKEN}" | sudo tee /root/cf-api-token.ini

The file should look something like this:

dns_cloudflare_api_token = PutYourApiTokenHere

Make sure it’s all on one line.

Now we can run our certbot command to validate our certificate.

sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials /root/cf-api-token.ini -d

Again this is a one line command. If all goes well you will find your new certificates in the /etc/letsencrypt/live directory.

From here you can either manually move/link to your application or if you want to get real fancy you can create hooks.

That’s a whole article on its own though!


Share This Post

2 Responses to "How to use a Cloudflare API Token for LetsEncrypt Validation on Ubuntu 20.04"

Post Comment