Implement an Auth Provider

Certbot requires an Auth Provider to validate the owner of a domain when allocating certificates.

Generally there are two types of auth providers.

1) the standard http auth mechanism

2) dns based authentication.

The http auth mechanism is built into nginx-le and is suitable for all public facing websites.

The dns based authentication mechanism is required for private web servers (no public ip address).

For dns authentication you need to be able to create a special dns record for your domain during the certificate acquisition and renewal phases. This means that you need to use your DNS providers API to create the required DNS entry.

Certbot supports a large number of DNS providers:

The problem is that currently nginx-le only supports a limited no. of Certbot Auth Providers.

This guide provide details on implementing additional Certbot Auth Providers (or even full custom providers) into nginx-le.

We would welcome contributions of additional Auth Providers.

You can add a Certbot supported DNS Auth Providers to Nginx-LE with a fairly low effort.

To add a new Auth Providers the following changes would need to be made:

1. Update Dockerfile

Modify the Nginx-LE docker file by changing the apt install command to include the additional packages required to support the selected Certbot Auth provider.

Find the following section.

RUN apt  update && apt install --no-install-recommends -y \
    ca-certificates \
    certbot \
    dnsutils \
    gnupg \
    nginx \
    openssl \
    python3-certbot-dns-cloudflare \
    python3-certbot-nginx \
    software-properties-common \
    tzdata \

Additional packages as required.

2. Implement an Auth Provider

We provide a base class AuthProvider. Your new Auth Provider should be derived from this class.


The shared/lib/src/auth_providers/dns_auth_providers/cloudlfare/cloudflare_provider.dart provider should be a good example to work from.

3. Register your new Auth Provider

Add you new auth provider to the AuthProviders class:


Find this section:

  /// Add new auth providers to this list.
  var providers = <AuthProvider>[

4. Build Nginx-LE

nginx-le build --image=repo/image:version

5. Run config

Run nginx-le config to confirm that you new provider is listed.

6. Raise a PR on our github page.

job done.

Last updated