Skip to main content

Providers (Challenge Solvers)

Providers AKA Challenge Solvers are how you prove to the ACME Server that you actually control the domain(s) you're requesting certificates for.

There are two main methods to accomplish this. One is http-01 and the other is dns-01.

The Providers page shows all current providers. It also allows adding, editing, and deleting of providers.

Challenge Types​

http-01​

The http-01 method works by running an http server that provides a specfic reply to the ACME Server when it reaches out to the http server. The http response MUST be provided by the domain name you're requesting a certificate for and it must be served from internet facing port 80.

This tends to prove challenging for a number of reasons so most people use the dns-01 method instead. If you do want to use http-01, Cert Warden provides a built-in http server specifically for this purpose.

This method does NOT support wildcards.

dns-01​

The dns-01 method works by provisioning a dns TXT record that the ACME Server checks for. Since no internet facing http service is required, this tends to be the preferred method, though it does have its own risks such as usually requiring API keys capable of adding and deleting dns records, which if compromised could be substantially harmful.

Cert Warden has a number of dns-01 options built-in, but the most common for users is likely to be the acme.sh method as it supports the most dns providers.

Configuration​

Domains​

You can add as many providers as you need. Each provider's configuration requires a list of the domains the provider should be used for. If you only have one provider or if you have a provider that handles most domains, you can configure one wildcard provider using a single domain of * which directs Cert Warden to use the provider for all domains that aren't explicitly defined on another provider.

caution

Do not use wildcards here. The provider will be selected for all subdomains (including the wildcard subdomain) of the specified domains.

Domain Aliases​

tip

Domain Aliases are an advanced feature. You do not need to use domain alises to use Cert Warden. In fact, most users probably won't use this feature.

Background​

In an effort to further secure an environment, some folks do not like to grant API access for their primary domain to Cert Warden (or any other ACME client for that matter). Instead, the ACME Client is given API access to an alternate domain, perhaps even one with the sole purpose of ACME challenge solving. The user then manually creates static CNAME records on the primary domain that point at the alternate domain. This allows the ACME client to provision records to the alternate domain automatically, which the ACME server will use for validation (via the CNAME) without providing the ACME client with full access to the primary domain.

This function is the same as what acme.sh offers via DNS alias mode, which you can read more about here.

Usage​

First, in Cert Warden, create a challenge provider for the alternate domain that Cert Warden will provision text records on (e.g., insecure-example.com).

Second, manually login to your DNS Provider and create a CNAME record for each domain or subdomain you want a certificate for (e.g., _acme-challenge.myapp.example.com CNAME _acme-challenge.myapp.insecure-example.com). You must include the _acme-challenge portion of the name.

warning

Do NOT skip the Second step! If you do not manually create every CNAME record that you need, validation will not succeed and you will not be able to acquire certificates.

Third, under Providers -> Domain Aliases in Cert Warden, add the alias. Aliases automatically include all subdomains, so you do not need to create an alias for every subdomain you want a certificate for. For example, the alias in the image would alias _acme-challenge.example.com to _acme-challenge.insecure-example.com as well as aliasing _acme-challenge.myapp.example.com to _acme-challenge.myapp.insecure-example.com.

Challenge Domain is the domain you are acquiring certificates for. Provision Domain is the domain Cert Warden will create DNS records on.

Edit Account Page

In this example, Cert Warden will provision a TXT dns record on _acme-challenge.myapp.insecure-example.com when a certificate has a domain name set to myapp.example.com. When the ACME server tries to validate control of this domain, it will encounter your manually create CNAME record when it queries _acme-challenge.myapp.example.com and will the subsequently query the TXT record on _acme-challenge.myapp.insecure-example.com.

Provider Specific Options​

Select your provider for more detailed configuration information.