Windows DNS (WinRM)
Write the _acme-challenge TXT record on a Windows DNS Server by running Add-DnsServerResourceRecord / Remove-DnsServerResourceRecord over WinRM/PowerShell, using a Windows account.
This is the simplest path for a Windows AD-integrated "Secure only" zone: no TSIG, no GSS-TSIG, and no krb5.conf / Kerberos plumbing on the CertAutoPilot host — the DNS server enforces its own ACL against the account you connect as. (If you'd rather use dynamic updates instead, see RFC 2136 (Dynamic DNS).)
How it works
The worker writes the challenge records with Add-DnsServerResourceRecord -Txt over WinRM and, after the CA validates, removes them with Remove-DnsServerResourceRecord. Fully automatic on every renewal.
Records are written and removed many at a time. Loading the DNS cmdlets on the server takes several seconds, so on the default (phased) flow and in the record cleanup the worker sends up to 100 records in one PowerShell run instead of one run per record — a 100-name certificate was measured at about 1.5 minutes to write its records instead of about 13. Each record still gets its own result:
- a record that already holds the same value (a retried run) counts as written — it is read back, not guessed from the error message;
- a record that could not be written fails the attempt, and every record of the attempt is removed again (removing one that was never written is harmless);
- an answer CertAutoPilot cannot read fails every record of that run — nothing is taken as written on doubt.
Removing a record that is already gone counts as removed; a zone that does not exist on the server fails the cleanup (it is reported, never taken for a removed record). Windows Server's own error code decides this, so it works whatever language the server runs in.
With the phased flow turned off (or a certificate whose zones also use RFC 2136 or Cloudflare / DigitalOcean / OVH / Plesk), records are written one at a time as before. The environment variable CERTAUTOPILOT_WINDNS_BATCH=false on the workers turns batching off without a release (one run per record, as before 1.7.0).
A CA connector uses the same session to write the vendor's validation record — Add-DnsServerResourceRecord -CName or -Txt at the per-order name the vendor returns (an existing record of that name and type is removed first, so a retry replaces rather than duplicates), and Remove-DnsServerResourceRecord once the order closes. The account therefore needs the right to create and delete CNAME as well as TXT records in the zone.
Prerequisites
- WinRM enabled on the target Windows host (the DNS server / domain controller, or a management box with the
DnsServerPowerShell module that can reach the DNS server via-ComputerName).winrm quickconfigon the target; HTTPS listener (5986) recommended. - A Windows account that can open a WinRM shell on the DNS server and write the zone. A member of the server's Administrators group works as is; a non-administrator account needs the rights listed under Account permissions.
- Network: the CertAutoPilot worker can reach the WinRM host on 5986 (TLS) or 5985 (plain).
Add the credential
-
Settings → DNS Credentials → New → Windows DNS (WinRM).
-
WinRM Host — the host to run PowerShell on (the DNS server, or a management box).
-
Username / Password — the Windows account; Domain if the username isn't already
DOMAIN\user. -
Auth Type — NTLM (default), Basic, or Kerberos. Kerberos is zero-config on the CertAutoPilot host: set Domain to the uppercase realm and use the server's AD FQDN as the WinRM host; the KDC is discovered via AD DNS (or pinned with the optional KDC Address field).
-
DNS Zone — the zone root that holds the records, e.g.
corp.local. -
Optional DNS Server (
-ComputerName) if the WinRM host is a management box, and Use TLS / Skip TLS Verify.Prefer pointing WinRM Host at the DNS server itself. With a management box, the cmdlets open a second connection from that box to the DNS server, and Windows does not pass the account's credential on to it unless Kerberos delegation is set up for the management box (the "double hop"); without it that connection is refused.
-
Test — no domain needed: Windows DNS has its own connectivity check (like Infoblox, and RFC 2136 with GSS-TSIG, which checks its Kerberos setup), so this connects over WinRM and verifies the zone exists. Then Save.
Config fields
| Field | Required | Purpose |
|---|---|---|
host | yes | WinRM target host. |
port | no | Defaults to 5985 (plain) or 5986 when Use TLS is on. |
username | yes | Windows account with zone-update rights. |
password | yes | Its password. |
domain | no | NTLM domain / Kerberos realm (if not in the username). |
auth_type | no | ntlm (default) / basic / kerberos. |
kdc_host | no | Kerberos only: optional KDC pin (host or host:port). Empty = discovered via the AD DNS SRV record. |
use_tls / tls_skip_verify | no | WinRM TLS. Skip-verify only for a self-signed listener cert. Over plain HTTP (5985) the DNS server's WinRM service needs AllowUnencrypted=true (every auth type). |
zone | yes | DNS zone root, e.g. corp.local. An internationalized zone may be typed in Unicode (örnek.com); CertAutoPilot addresses the server with its punycode name (xn--rnek-4qa.com) — see Internationalized zones. |
computer_name | no | -ComputerName target DNS server if the WinRM host isn't the DNS server. |
password is encrypted at rest and never returned by the API.
How long issuance waits
The CA reads the challenge record from public DNS. An Active Directory-integrated zone reaches the other domain controllers by AD replication — minutes inside a site, up to hours across sites — and a resolver that asked a controller before the record arrived keeps the "no such record" answer for the zone's negative TTL (one hour by default on Windows DNS). So whenever a zone of the certificate uses a Windows DNS credential, the propagation check waits at least 2 hours before giving up, even when Max Propagation Wait under Settings → General is shorter (a longer setting is kept). It stops as soon as every record is visible, so a fast zone is not slowed down.
- The zone must be published to the internet by its authoritative servers: a zone that only internal resolvers see cannot be validated by a public CA, however long the wait.
- With the phased flow turned off, each name waits at most the DNS Propagation Timeout (up to 600 s) instead.
- To check against your own domain controllers, list them under DNS Resolvers (Settings → General).
- Point WinRM Host (or DNS Server) at one domain controller by its own name, never at a name that resolves to several (the AD domain name does). Each batch of records opens its own connection; when the records are written on one controller and removed on another before replication, the removal finds nothing to delete and the record arrives afterwards and stays.
Security
- Prefer HTTPS WinRM (5986) + a valid listener certificate over plain 5985.
- Use a dedicated account with the rights under Account permissions instead of a domain administrator, and do not add it to DnsAdmins (that group can make the DNS service load a DLL of its choice, which runs as SYSTEM on the domain controller).
- Restrict WinRM access (firewall) to the CertAutoPilot worker IP(s).
Account permissions
CertAutoPilot opens a WinRM command shell (WinRS) on the DNS server and runs the DnsServer PowerShell cmdlets there as the account in the credential. The account needs rights at three levels: WinRM, WMI and DNS.
Administrators. A member of the DNS server's Administrators group has all of them. On a domain controller that is the domain's built-in Administrators group, which is a highly privileged group; the rest of this section sets up an ordinary domain account instead.
A non-administrator account. Each right below was measured on Windows Server 2022 (an Active Directory-integrated zone with secure updates, Kerberos over HTTPS): without it, the step named in the last column fails.
| Where | Right | What fails without it |
|---|---|---|
| Group Remote Management Users on the DNS server (on a domain controller: the domain's built-in group) | Membership | WinRM refuses the sign-in (HTTP 401). |
| WinRM root security descriptor | Read and Execute for Remote Management Users | The sign-in succeeds but WinRM refuses to open a shell ("Access is denied", HTTP 500). Remote Management Users is only allowed into PowerShell remoting endpoints by default, and CertAutoPilot uses the command shell. |
WMI namespace root\Microsoft\Windows\DNS | Enable Account and Remote Enable | Every DNS cmdlet: "Access denied". A WinRM session is a network sign-in, so WMI asks for Remote Enable even though the cmdlets run on the server itself. |
WMI namespace root\cimv2 | Enable Account and Remote Enable | Some record updates: "Cannot connect to CIM server. Access denied". |
| DNS server (DNS Manager → the server → Properties → Security) | Read | Every cmdlet: "Failed to get the zone information". |
| The zone (DNS Manager → the zone → Properties → Security → Advanced) | Read, Write, Create all child objects, Delete all child objects and Delete, applied to This object and all descendant objects | Only needed when a name already exists and was created by another account. |
About the zone row: an Active Directory-integrated zone with secure updates already lets every authenticated account create a name, and the account that created a name may change and delete it. So the records CertAutoPilot creates itself work without a zone permission. A _acme-challenge name another account created (an earlier run under an administrator account, a record added by hand) cannot be written or deleted by the new account until the zone permission is given. Give it unless you are sure no such names exist.
To set the WinRM right, run this in an elevated PowerShell on the DNS server:
# WinRM: let Remote Management Users open a shell. Keeps a copy of the
# current value, then adds one entry (Read + Execute for Remote Management Users).
$cur = (Get-Item WSMan:\localhost\Service\RootSDDL).Value
$cur | Out-File "$env:USERPROFILE\rootsddl-backup.txt"
$ace = '(A;;GXGR;;;RM)'
$new = if ($cur -like '*S:*') { $cur.Replace('S:', "${ace}S:") } else { $cur + $ace }
Set-Item WSMan:\localhost\Service\RootSDDL -Value $new -Force
For the two WMI namespaces use Computer Management → Services and Applications → WMI Control → Properties → Security, select the namespace, Security, add the account (or a group holding it) and tick Enable Account and Remote Enable (Advanced: This namespace only).
The credential's Test reads the zone and writes and removes a test record with the same cmdlets, so a missing right shows up there with the error from the table above.
Internationalized zones
Windows DNS keeps a zone under the exact spelling it was created with, and only a zone created under its punycode (A-label) name — xn--rnek-4qa.com for örnek.com — answers the names a certificate authority asks for. A zone created in DNS Manager under its Unicode spelling exists on the server, but queries for _acme-challenge.xn--rnek-4qa.com get no answer from it.
So create the zone on the server under its punycode name. In the credential you may type the zone either way: CertAutoPilot compares challenge names and addresses the server in punycode. If the server holds the zone under its Unicode spelling only, the credential Test says so and names the punycode zone to create instead.
Troubleshooting
- WinRM connect fails — WinRM not enabled/listening, wrong port, or firewall. Test with
Test-WsMan <host>andwinrm quickconfigon the target. - Access denied on the cmdlet — the account lacks Write on the zone (DNS Manager → zone → Security), or the
DnsServermodule isn't present on the WinRM host (use-ComputerNameto target the DNS server from a box that has it). - "not under the configured zone" — the certificate's domain isn't a subdomain of the DNS Zone you set; the zone must be the authoritative zone root. Unicode and punycode spellings of the same zone count as the same zone.
- "holds zone … under its Unicode spelling only" — the zone was created on the server under its Unicode name; recreate it under the punycode name the message gives (see Internationalized zones).
See also
- RFC 2136 (Dynamic DNS) — TSIG / GSS-TSIG dynamic updates
- WinRM distribution module — the same WinRM transport, for cert distribution
- DNS providers overview