Skip to main content

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​

For each DNS-01 challenge the worker opens a WinRM session and runs a PowerShell cmdlet: Present → Add-DnsServerResourceRecord -Txt, then after the CA validates, CleanUp → Remove-DnsServerResourceRecord. Fully automatic on every renewal.

Prerequisites​

  • WinRM enabled on the target Windows host (the DNS server / domain controller, or a management box with the DnsServer PowerShell module that can reach the DNS server via -ComputerName). winrm quickconfig on the target; HTTPS listener (5986) recommended.
  • A Windows account with permission to update the target zone (a domain account like cap-admin, or a delegated service account with Write on the zone).
  • Network: the CertAutoPilot worker can reach the WinRM host on 5986 (TLS) or 5985 (plain).

Add the credential​

  1. Settings → DNS Credentials → New → Windows DNS (WinRM).
  2. WinRM Host — the host to run PowerShell on (the DNS server, or a management box).
  3. Username / Password — the Windows account; Domain if the username isn't already DOMAIN\user.
  4. 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).
  5. DNS Zone — the zone root that holds the records, e.g. corp.local.
  6. Optional DNS Server (-ComputerName) if the WinRM host is a management box, and Use TLS / Skip TLS Verify.
  7. Test — no domain needed: Windows DNS is the one provider with a real connectivity check, so this connects over WinRM and verifies the zone exists. Then Save.

Config fields​

FieldRequiredPurpose
hostyesWinRM target host.
portnoDefaults to 5985 (plain) or 5986 when Use TLS is on.
usernameyesWindows account with zone-update rights.
passwordyesIts password.
domainnoNTLM domain / Kerberos realm (if not in the username).
auth_typenontlm (default) / basic / kerberos.
kdc_hostnoKerberos only: optional KDC pin (host or host:port). Empty = discovered via the AD DNS SRV record.
use_tls / tls_skip_verifynoWinRM 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).
zoneyesDNS zone root, e.g. corp.local.
computer_nameno-ComputerName target DNS server if the WinRM host isn't the DNS server.

password is encrypted at rest and never returned by the API.

Security​

  • Prefer HTTPS WinRM (5986) + a valid listener certificate over plain 5985.
  • Use a dedicated, least-privilege account delegated Write on only the challenge zone/sub-zone — not a domain admin where avoidable.
  • Restrict WinRM access (firewall) to the CertAutoPilot worker IP(s).

Troubleshooting​

  • WinRM connect fails — WinRM not enabled/listening, wrong port, or firewall. Test with Test-WsMan <host> and winrm quickconfig on the target.
  • Access denied on the cmdlet — the account lacks Write on the zone (DNS Manager → zone → Security), or the DnsServer module isn't present on the WinRM host (use -ComputerName to 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.

See also​