"Client with the currently selected authenticator..." / "An authenticator script must be provided when..."

For several years, many people have come to this forum for help after receiving either of the following error messages:

Client with the currently selected authenticator does not support any combination of challenges that will satisfy the CA

An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively

If you search for these error messages in the forum search feature, you should find many excellent answers about them, but I wanted to try to write a single relatively authoritative and detailed answer to point people to in the future, in the hope of reducing duplication of effort.

(1) What do these errors mean?

Let's Encrypt offers three different ways that you can prove your control over a domain name when requesting a certificate. These are called "challenge types" and are all things that you, or your server, can only do if you currently control a domain or the domain's web server.

By Let's Encrypt certificate authority policy, only one of these three methods, called DNS-01 or "the DNS challenge", is permitted to be used when you are requesting a wildcard certificate (one that contains a name with a *. at the beginning, like *.example.com, in order to cover an unlimited number of subdomains).

The DNS-01 challenge is different from the other two because it isn't about the behavior of your web server at all, but rather about the contents of your DNS zone file, which is normally maintained by your DNS host, which may or may not be the same entity as your web host or domain registrar, depending on how your domain is set up. The DNS-01 challenge requires a specified DNS TXT record entry to be created in your DNS zone. This record is not permanent: its contents change for each and every renewal of your Let's Encrypt certificate, meaning that the DNS records must be updated at that time, too.

This makes renewals more difficult to automate with this method, because, while Certbot runs on your web server machine, your DNS zone file is normally kept somewhere else (on a different server, possibly intended to be updated via an interactive web control panel). When run on your web server, Certbot knows how to change content on your web server (to pass the HTTP-01 challenge), but commonly does not inherently know how to change a DNS record in your DNS zone file (to pass the DNS-01 challenge file).

The error messages above are saying that, because Certbot does not know how to do this on your system, your certificate could not be renewed automatically. In other situations, Certbot would have been able to renew your certificate automatically.

(2) What can I do about these errors (if I need to renew a wildcard certificate?)

If you need to renew a wildcard certificate from Let's Encrypt, you will have to pass the DNS-01 challenge, by creating an appropriate DNS TXT record (again, its contents will be different from the contents of one that you may have had to create in the past!).

You can do this manually or automatically. Automatically is usually preferable, but may require more work to set up, and may not always be possible in certain web server or DNS configurations.

To renew your certificate manually, find the relevant certificate name by running

sudo certbot certificates

Suppose the relevant certificate is called example.com; then you can renew it manually by running

sudo certbot certonly --cert-name example.com

(The more familiar and usual command sudo certbot renew does not work in this specific case for reasons having to do with Certbot's internal design. In particular, sudo certbot renew only works when Certbot doesn't need to interact with the human user at all. For an interactive manual renewal, it does need to interact with you, the user, and sudo certbot renew is not able to do this.)

The command above should then prompt you to go through all of the necessary manual steps involving creating a DNS TXT record. Note that if your single certificate includes both a wildcard (like *.example.com) and the base domain name (like example.com), you will be prompted to add two different DNS TXT records during the renewal process. Both of these can, and should, exist in your DNS zone file at the same time; you should not replace one in order to add the other, but should add both together.

To renewal your certificate automatically, you'll need to install a Certbot DNS plugin that's compatible with your DNS host's API, or write your own shell script (called an "authenticator hook" or "auth-hook") that can make changes to your DNS zone file. The existing Certbot DNS plugins are listed at

https://certbot.eff.org/docs/using.html#dns-plugins

and information about installing them is available at

Information about how to write an authenticator hook script is provided at

https://certbot.eff.org/docs/using.html#pre-and-post-validation-hooks

These options may not be available or suitable for all DNS hosting environments, and your existing DNS host might not provide a compatible API interface. In that case, you could consider switching DNS hosts, or search on the forum for more information about acme-dns, which may provide an alternative option.

Note that acme.sh, which is a Let's Encrypt client application that is an alternative to Certbot, supports a larger number of DNS provider APIs (currently over 100 of them).

If you're a Certbot user and no Certbot integration is readily available for your DNS host, you could also evaluate acme.sh to see if it meets your needs.

(3) What can I do about these errors (if I don't need a wildcard certificate?)

If you don't need a wildcard certificate, you might not need to use the DNS-01 challenge method. In that case, if your web server can receive incoming connections from the Internet on port 80, Certbot may be able to automate your renewals using its existing integrations, using the --nginx, --apache, --webroot, or --standalone methods instead of the --manual method.

Consider following the Certbot instructions from the beginning using a more automated integration method for your web server, and not requesting a wildcard certificate. You can check

and

https://certbot.eff.org/docs/using.html#getting-certificates-and-choosing-plugins

for more information about how to choose a Certbot authenticator plugin.

Because Certbot knows how to make the necessary changes itself using these plugins, automated renewal of your (non-wildcard) certificate will usually work out-of-the-box in the future. If it doesn't, feel free to ask for help with your specific situation here on the Let's Encrypt Community Forum.

4 Likes

Regarding acme.sh as a certbot alternative, note that it has now switched over to using ZeroSSL, instead of Let's Encrypt, by default.

5 Likes

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.