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.
  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. Save.

Config fields​

FieldRequiredPurpose
hostyesWinRM target host.
portno5986 (TLS) / 5985 (plain); default 5986.
usernameyesWindows account with zone-update rights.
passwordyesIts password.
domainnoNTLM domain / Kerberos realm (if not in the username).
auth_typenontlm (default) / basic / kerberos.
use_tls / tls_skip_verifynoWinRM TLS. Skip-verify only for a self-signed listener cert.
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​