You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/dns/validation.md
+61-36Lines changed: 61 additions & 36 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,31 +5,46 @@ title: DNS Domain Validation (dns-01)
5
5
6
6
## Why use DNS Validation?
7
7
8
-
To request a certificate from Let's Encrypt (or any Certificate Authority), you need to provide some kind of proof that you are entitled to receive the certificate for given domain(s). Let's Encrypt supports two methods of validation to prove control of your domain, `http-01` ([validation over HTTP](http-validation.md)) and `dns-01` (validation over DNS).
8
+
To request a certificate from Let's Encrypt (or any Certificate Authority), you must prove control of the domain names on the certificate. Two ACME challenge types are commonly used:
9
9
10
-
**Wildcard domain certificates (those covering `*.yourdomain.com`) can only be requested using DNS validation.** DNS Validation is also especially useful if the domains you are trying to get certification for are not public websites, or cannot serve http requests on port 80.
10
+
-`http-01` – [validation over HTTP](http-validation.md)
11
+
-`dns-01` – validation over DNS (TXT records)
12
+
13
+
**Wildcard certificates** (for example, `*.yourdomain.com`) can only be requested using DNS validation. DNS validation is also useful when:
14
+
15
+
- Your domains are not public websites.
16
+
- Port 80 (HTTP) cannot be used for validation.
11
17
12
18
## How to use DNS Validation
13
19
14
-
In order to validate your control of your domains to the certificate authority you will be required to create a specified TXT record in your domain's DNS zone.
20
+
To validate control of your domains, you create a specific TXT record in the domain's DNS zone for each name on the certificate.
21
+
22
+
Notes:
23
+
24
+
- The TXT value is different for every order/renewal, so automation is strongly recommended.
25
+
- The app includes built‑in integrations for many popular DNS providers with APIs the app can use.
15
26
16
-
To do this you may need to get the API credentials for the (hosted) DNS from your DNS providers control panel, store these credentials in the app then select them to be used for specific certificate requests. DNS credentials are encrypted at rest using Windows DAPI, but where possible you should use limited privilege credentials.
27
+
If your DNS provider (or custom DNS setup) does not have a supported API, you can either:
17
28
18
-
If your DNS provider (or custom DNS setup) does not have an API we can talk to, you can write your own DNS update script or use the Manual DNS option (the request pauses while you manually update DNS).
29
+
- Provide your own DNS update script, or
30
+
- Use the Manual DNS option (the request pauses while you update DNS records yourself).
19
31
20
32
### Certify DNS
21
33
22
34
Certify DNS is a cloud hosted version of the acme-dns standard (CNAME delegation of acme challenge TXT records to a dedicated challenge response service). This service can be enabled through the https://certifytheweb.com License Keys tab when signed in. The service is compatible with most existing _acme-dns_ clients so it can be used with other ACME clients on all operating systems. Read more about [Certify DNS](providers/certifydns.md).
23
35
24
-
### DNS API Providers
36
+
### DNS API providers
25
37
26
-
Current Built-In DNS API providers include:
38
+
Current built‑in DNS API providers include:
27
39
28
40
- ACME DNS (see below), Aliyun \*, [AWS Route53](providers/awsroute53.md), [Azure DNS](providers/azuredns.md), [Cloudflare](providers/cloudflare.md), [DNS Made Easy](providers/dnsmadeeasy.md), [GoDaddy](providers/godaddy.md), Microsoft DNS \*, IONOS \*, [OVH](providers/dns-ovh.md)\*, Simple DNS Plus \*, TransIP \*
29
41
30
-
_\* marked providers are contributed and tested by users._
42
+
_\*Providers marked with an asterisk are community‑contributed and tested by users._
31
43
32
-
In addition we implement a number of DNS providers courtesy of the Posh-ACME: https://github.com/rmbolger/Posh-ACME project. If you encounter any issues with these you should verify they work normally within Posh-ACME and then raise an issue on our [github page](https://github.com/webprofusion/certify) :
44
+
In addition, several providers are supported via the Posh‑ACME project (https://github.com/rmbolger/Posh-ACME). If you encounter issues with these plugins:
45
+
46
+
1. Verify the provider works as expected in Posh‑ACME.
47
+
2. Then raise an issue on our [GitHub page](https://github.com/webprofusion/certify).
**If you change API credentials, you need to replace the credential settings in Certify under 'Settings > Stored Credentials' to ensure renewals keep working. Once saved, there is also a 'Test' option so you can try out the credentials to check they still work.**
100
+
**If you change API credentials**, update them under Settings > Stored Credentials so renewals continue to work. Use the Test button to confirm connectivity.
101
+
102
+
### Propagation delay (seconds)
103
+
104
+
When using DNS validation, the CA checks your `_acme-challenge` TXT record via your authoritative name servers. After you update a TXT record, it can take time for all name servers to agree. The app waits for this window, called the **propagation delay**.
105
+
106
+
- Default: 60 seconds
107
+
- If validation is unreliable or your DNS provider is slow to propagate, increase to 120–300 seconds (or more if required)
86
108
87
-
### Propagation Delay Seconds
109
+
### CNAME delegation
88
110
89
-
When using DNS validation, the certificate authority will check your DNS TXT record using your authoritative nameserver to see if they agree on the expected value of the corresponding `_acme-challenge` record for each domain/subdomain identifier. When the TXT record is updated it can often take up to a minute or two for all your nameservers to agree, we refer to the time we wait to allow for this as *Propagation Delay*. The default propagation delay is 60 seconds, but you can increase this if you are having trouble with validation. If you are using a DNS provider which has a very long propagation delay you may need to increase this value e.g. to 300 seconds (5 minutes).
111
+
To avoid updating your primary DNS zone directly, you can use CNAME delegation:
90
112
91
-
### CNAME Delegation
113
+
1. In your primary zone, create an `_acme-challenge.<name>` CNAME for each domain/subdomain.
114
+
2. Point each CNAME at a corresponding `_acme-challenge.<name>` TXT record in a different (delegated) zone that you can automate.
92
115
93
-
An optional advanced approach to DNS validation which removes the need to update your primary domain DNS is to use CNAME delegation, this is where you create an `_acme-challenge.yourdomain.com`CNAME record for each domain/subdomain and point it at a corresponding TXT record in another DNS zone. This allows you to have a dedicated domain or subdomain which specifically handles DNS challenge requests (because it can be automated).
116
+
In the Authorization configuration UI, set the `CNAME Delegation Rule`for each authorization configuration.
94
117
95
-
In the Authorization configuration UI, you can specify the `CNAME Delegation Rule` for each authorization configuration.
118
+
Rule format: `*.source.domain:*.destination.domain` (use `;` to separate multiple rules).
96
119
97
-
The rule format is: `*.source.domain:*.destination.domain`, you can specify multiple rules by separating rules with `;`.
120
+
Example: your site `example.com` includes `example.com` and `www.example.com`. Normally you would create TXT records for `_acme-challenge.example.com` and `_acme-challenge.www.example.com`. Instead, you can delegate both to a dedicated zone such as `auth.example.org`.
98
121
99
-
So if for example your website `example.com` has names `example.com` and `www.example.com` these would normally require a challenge TXT record be automatically created for each entry e.g. `_acme-challenge.example.com` and `_acme-challenge.www.example.com`. In this example we could redirect those as CNAME entries to a dedicated zone such as `auth.example.org`.
122
+
- Configure the authorization to update the target (delegated) domain and set `CNAME Delegation Rule` to `*.example.com:*.auth.example.org`.
123
+
- In the original domain, add `_acme-challenge` CNAMEs pointing to the delegated zone, e.g., `_acme-challenge.example.com` → `_acme-challenge.auth.example.org` and `_acme-challenge.www.example.com` → `_acme-challenge.www.auth.example.org`.
124
+
- The app will create/update TXT records in the delegated zone using the DNS credentials/API you specified for that zone.
100
125
101
-
- Configure all of the settings in order to update the target domain (instead of the original domain) and set your `CNAME Delegation Rule` as `*.example.com:*.auth.example.org`.
102
-
- You will then also need an `_acme-challenge` CNAME in your original domain setup to point to delegated domain, for each domain/subdomain (e.g. `_acme-challenge.example.com` pointing to `_acme-challenge.auth.example.org` and `_acme-challenge.www.example.com` pointing to `_acme-challenge.www.auth.example.org`).
103
-
- The app will create/update the target TXT record and values, using the DNS credentials/API selection you have specified for the target domain/DNS zone.
126
+
You can also map multiple sources to a single destination subdomain by using a non‑wildcard target. For example, `*.example.com:auth.example.org` maps `_acme-challenge.www.example.com` to `_acme-challenge.auth.example.org` (ignoring the subdomain). Not all DNS providers support multiple TXT values on a single record—check your provider’s capabilities.
104
127
105
-
It's also possible to redirect multiple sources to one destination subdomain using a non-wildcard target e.g. a rule definition of `*.example.com:auth.example.org` would translate `_acme-challenge.www.example.com` to `_acme-challenge.auth.example.org`, ignoring the subdomain. This means all of your TXT updates can use the same TXT record but support for this will vary by DNS provider.
128
+
### Domain match rules
129
+
If a certificate needs multiple authorization configurations (for example, different DNS zones/providers or a mix of HTTP and DNS), use `Domain Match Rule` to specify which names each configuration applies to. These rules are optional and only used when more than one authorization configuration exists.
106
130
107
-
### Domain Match Rules
108
-
For certificates that require multiple authorizations across different domain (e.g. different DNS providers/zones or a mix of HTTP and DNS validation) you can use the `Domain Match Rule` to specify which domains/subdomains should be matched for the given authorization configuration. These are optional and *only* used if you have multiple authorization configurations for the same certificate. To match all (first level) subdomains of a domain use a wildcard `*.example.com` or to match only a single specific domain/subdomain identifier use `subdomain.example.com`, multiple rules can be supplied as semicolon separated.
131
+
Tips:
109
132
110
-
Note that `*.example.com` will *not* match a further subdomain level such as `something.subdomain.example.com`. To match multiple subdomains either explicitly or as a wildcard you can use a semicolon separated list e.g.`*.example.com;*.subdomain.example.com;www.something.example.com`. You can use the Preview tab to see which authorization configurations will match which identifiers, if an identifier is not matched the app will fall back to HTTP validation for that identifier.
133
+
-`*.example.com` matches first‑level subdomains only, not `something.subdomain.example.com`.
134
+
- Use a semicolon‑separated list to match multiple patterns, e.g., `*.example.com;*.subdomain.example.com;www.something.example.com`.
135
+
- Use the Preview tab to confirm which identifiers match which configurations. If an identifier is not matched, the app falls back to HTTP validation for that name.
111
136
112
-
## Other DNS Validation Methods
137
+
## Other DNS validation methods
113
138
114
139
You can alternatively use the following methods to manage your DNS TXT records:
115
140
116
-
### ACME DNS
141
+
### acme-dns
117
142
118
-
[acme-dns](https://github.com/joohoi/acme-dns)is a system to automatically manage TXT record values on behalf of your domain **just for challenge validation**. This is probably the easiest method if you have a trusted acme-dns server you can use, this also avoids storing powerful DNS admin credentials on your server. Find out more on[how to use acme-dns](providers/acme-dns.md).
143
+
[acme-dns](https://github.com/joohoi/acme-dns) automatically manages TXT record values **only for challenge validation**. If you have access to a trusted acme-dns server, this is often the simplest approach and avoids storing DNS admin credentials on your servers. Learn more:[how to use acme-dns](providers/acme-dns.md).
119
144
120
-
### DNS Scripting
145
+
### DNS scripting
121
146
122
-
[DNS Scripting](providers/scripting.md)involves providing your own custom script to update/delete TXT records in your DNS using a .bat file which can then optionally call python, node scripts etc.
147
+
[DNS scripting](providers/scripting.md)lets you run your own update/delete logic for TXT records. For example, call a `.bat` file that invokes PowerShell, Python, or Node.js.
123
148
124
149
### Manual DNS
125
150
126
-
If you are just experimenting with wildcard domains you may opt to use manual DNS updates (editing manually via your DNS control panel).
151
+
If you’re experimenting with wildcard domains, you can use manual DNS updates (edit records in your DNS control panel).
127
152
128
-
**This is the leastrecommended option as you will need to update this for every renewal.**
153
+
**This is the least‑recommended option** because you must repeat the process for every renewal.
129
154
130
-
This method can also be extremely confusing when requesting a single cert for `*.domain.com` and `domain.com`, as you need to provide 2 values for the same TXT `_acme-challenge.domain.com` record (to answer both the `*.domain.com` and `domain.com` challenge responses).
155
+
It can also be confusing when requesting a single cert for `*.domain.com` and `domain.com`: you must provide two TXT values for the same `_acme-challenge.domain.com` record (to answer both challenges).
131
156
132
157
To use Manual DNS:
133
158
134
-
- Select Manual DNS as your DNS update method
135
-
- Perform your initial certificate request. The request will pause and ask you to create a TXT record in your domain (one value for each domain or wildcard). Once you have completed that, wait for your DNS name servers to complete propagation. If you have trouble validating, wait an hour or more for this to complete.
136
-
- Use 'Request Certificate' to resume the request and check validation.
137
-
- If the certificate authority can see the TXT value they asked for in your DNS, they will then allow a certificate to be issued and the request will resume as normal.
159
+
1. Select Manual DNS as your DNS update method.
160
+
2. Start the certificate request. When prompted, create the TXT record(s) (one value per name). Wait for DNS propagation—if validation fails, wait longer (up to an hour) and try again.
161
+
3. Use Request Certificate to resume and validate.
162
+
4. If the CA can see the expected TXT values, the order proceeds and the certificate is issued.
0 commit comments