Skip to content

Latest commit

 

History

History
137 lines (108 loc) · 5.71 KB

certbot_authenticators.md

File metadata and controls

137 lines (108 loc) · 5.71 KB
Raw

Certbot Authenticators

Certbot allows to use a number of authenticators to get certificates. By default, and this will be sufficient for most users, this container uses the webroot authenticator, which will provision certificates for your domain names by doing what is called HTTP-01 validation, where ownership of the domain name is proven by serving a specific content at a given URL.

Among the other authenticators available to certbot, the DNS authenticators are also available through this container. DNS authenticators allow you to prove ownership of a domain name by serving a challenge directly through a TXT record added in your DNS provider. This challenge is called DNS-01 and is a stronger proof of ownership than using HTTP-01, which is why this method also allow wildcard certificates (e.g. *.yourdomain.org).

Preparing the Container for DNS-01 Challenges

To use DNS-01 challenges, you will need to create the credentials file for the chosen authenticator.

You can find information about how to configure them by following those links for the supported authenticators:

You will need to setup the authenticator file at /etc/letsencrypt/<authenticator provider>.ini, so for e.g. Cloudflare you would need the file /etc/letsencrypt/cloudflare.ini with the following content:

# Cloudflare API token used by Certbot
dns_cloudflare_api_token = 0123456789abcdef0123456789abcdef01234567

Using a DNS-01 Authenticator by Default

You can use an authenticator solving DNS-01 challenges by default by setting the CERTBOT_AUTHENTICATOR environment variable with the value as the name of the authenticator you wish to use (e.g. dns-cloudflare).

All the certificates needing renewal or creation will then start using that authenticator. Make sure, of course, that you've setup the authenticator correctly, as described above.

Using a DNS-01 Authenticator for Specific Certificates Only

You might want to keep using the webroot authenticator in most cases, but need to use a DNS-01 challenge to setup a wildcard certificate for a given domain. Or you might even have a domain set up on Route53 while your other domains are on Cloudflare, and you thus are using dns-cloudflare as your default authenticator.

In such cases, you can specify the authenticator you wish to use in the certificate path that you are setting up as ssl_certificate_key in your server block of the nginx configuration. In our case, if we want to use dns-route53 for a specific certificate, we could be using the following:

server {
    listen              443 ssl;
    server_name         yourdomain.org *.yourdomain.org;
    ssl_certificate_key /etc/letsencrypt/live/test-name.dns-route53/privkey.pem;
    ...
}

The script running in the container to renew certificates will automatically identify that it needs to use the Route53 authenticator here. Of course, you will need that authenticator to be configured properly in order to be able to use it.

This setting is also compatible with the multi-certificate setup, so an RSA certificate via Clouflare's authenticator can be specified like this:

ssl_certificate_key /etc/letsencrypt/live/test-name.dns-cloudflare.rsa/privkey.pem;

Troubleshooting Tips

DNS propagation is usually quite fast, but depends a lot on caching. This means that if Let's Encrypt tried to read the challenge recently, it might still hit a cache returning an older value of the TXT record that was added by certbot.

If this happens often to you, you can set the CERTBOT_DNS_PROPAGATION_SECONDS environment variable in your docker configuration, to increase the time to wait for DNS propagation to happen.

When that environment variable is not set, certbot will use a default value, which can be found in the documentation of the authenticator of your chosing. At the time of writing, this default value is of 10 seconds for all of the DNS authenticators.