Microsoft AD CS
Issue from your Active Directory Certificate Services CA. A connection talks to the CA in one of two ways, chosen when the connection is created (it cannot be changed later — create a second connection to switch):
| Direct to the CA (RPC) | CES/CEP web services | |
|---|---|---|
| What the CA server needs | Only the Certification Authority role | The CA role plus the CES and CEP roles on IIS |
| Network from the worker | TCP 445 to the CA server; TCP 88 to a domain controller for Kerberos; TCP 636 (or 389 with StartTLS) to a domain controller to read templates | HTTPS (usually 443) to the CES/CEP site |
| Authentication | Kerberos (default) or NTLM, with a domain account | Username and password in the SOAP message |
| Templates | Read from Active Directory, or typed by name | Read from the CEP policy service |
Most installations have only the CA role — use Direct to the CA (RPC) there. Connections created before 1.7.2 use CES/CEP and keep working unchanged.
Direct to the CA (RPC)
CertAutoPilot sends the request to the CA the way Windows itself does (the MS-ICPR interface on the CA server's \\<ca-host>\pipe\cert, over SMB on TCP 445, always signed and encrypted). Nothing has to be installed on the CA server: the CA role opens TCP 445 in Windows Firewall itself (rule Certification Authority Enrollment and Management Protocol (CERTSVC-RPC-NP-IN)), even when the general File and Printer Sharing rule is off.
Network
| From the worker to | Port | When |
|---|---|---|
| The CA server | TCP 445 | Always |
| A domain controller (KDC) | TCP 88 | Kerberos authentication |
| A domain controller | TCP 636 (LDAPS), or TCP 389 with StartTLS | Templates read from Active Directory, and Find CAs |
| Your DNS server | UDP/TCP 53 | Always: the CA server, domain controller and KDC names are resolved through DNS (Kerberos needs the CA server's DNS name), and an unset domain controller or KDC is found through the domain's DNS records |
Required permissions
The account does not need to be an administrator anywhere, and nothing beyond these rights is needed — measured on a member-server CA with the default security of a new installation:
| Where | Right | Default | What it is used for |
|---|---|---|---|
The CA (certsrv.msc → CA → Properties → Security) | Request Certificates | Granted to Authenticated Users | Sending requests, the connection Test, and collecting a request a manager approved later. Grant it to the account (or a group it is in) only if your CA's security was tightened and Authenticated Users no longer holds it. |
Each template (certtmpl.msc → template → Security) | Read and Enroll | Template-specific | Requesting with the template. Without Enroll, CertAutoPilot shows the template as unusable and the CA would deny the request (0x80094012). |
| Active Directory | Read | Every domain account can read the CA and template objects | Listing the CAs and templates, and checking the account's Enroll right (only with templates read from Active Directory). |
Issue and Manage Certificates (Certificate Manager) and Manage CA are not needed — approving a waiting request stays a CA manager's job in certsrv.msc. The CES/CEP method needs the same template rights; it has its own requirements on the IIS side (AD CS server setup).
Create the connection
- Settings → Certificate Authorities → Microsoft AD CS tab → Add Connection → method Direct to the CA (RPC).
- Authentication — Kerberos (recommended) or NTLM. There is no fallback from one to the other: some hardened domains turn NTLM off, and Kerberos needs the CA server's DNS name (an IP address works only with NTLM).
- User name —
user@corp.example.comorCORP\user, and its password. - Active Directory domain — the DNS name of the domain (
corp.example.com). Kerberos uses it as the realm (without a domain, the part after@in the user name is the realm; theCORPofCORP\usernever is) and finds a domain controller through its DNS records. The user name before@must be the account's pre-Windows 2000 logon name. - Templates — Read from Active Directory (recommended) or Enter template names.
- Read from Active Directory: optionally pin a Domain controller (when the worker cannot resolve the domain's DNS records) and choose LDAPS (TCP 636) or StartTLS (TCP 389). Domain controllers that require LDAP signing and channel binding accept only these two. The domain controller's certificate is checked against the system roots, the CA certificate in TLS trust, or — for a self-signed or private-CA certificate — a pinned SHA-256 fingerprint. Find CAs signs in with the account, lists the forest's enterprise CAs and fills in the CA server and name when you pick one; when the domain controller's certificate is not trusted it shows the fingerprint it presented and offers Trust this certificate and search again — check the fingerprint on the domain controller first. A fingerprint is one domain controller's certificate, so trusting it also fills in that controller as the Domain controller (when none was set); a pinned fingerprint without one tries each controller DNS lists until one presents it.
- Enter template names: type the template names (not display names). Nothing about them is known before the CA answers, so a key size, algorithm or permission the template refuses comes back from the CA when a certificate is requested.
- CA server — the DNS name of the server the CA runs on; CA name — the CA's common name (
certutil -cainfo name). - Optional, under Advanced: a KDC (host or host:port). Empty means the domain controller set above (every domain controller is a KDC), else one found through DNS.
- Save. The connection is then tested and its templates are read once. Where a connection sends the password — CA server, CA name, domain, domain controller and how its certificate is trusted, KDC, template source, authentication and the user name — can be changed later only with the password entered again (or by the person who entered it, or an organization owner).
Test signs in and asks the CA for a request that cannot exist, which proves the account, the CA name and TCP 445 without leaving anything in the CA database; any other answer fails the test (for example an account the CA does not let request certificates). With templates read from Active Directory it also signs in to a domain controller and checks the CA is listed there. Sync Templates reads the templates again (with typed names it only keeps the list). What Sync stores belongs to the CA, the domain and the account it was read with: editing any of them clears the stored templates until the next Sync (the UI syncs after every save), and a Sync that was still reading while the connection was edited stores nothing and asks you to sync again. A connection created through the API with templates read from Active Directory has no templates until Sync Templates is called; the UI calls it right after saving.
On a cluster, an RPC connection can be created only after every node runs 1.7.2 or later (CLUSTER_UPGRADE_REQUIRED otherwise) — an older node would not know how to use it.
CES/CEP web services
CES/CEP vs WSTEP
AD CS exposes its web enrollment as two web-service endpoints, and CertAutoPilot uses both:
- CEP (MS-XCEP — Certificate Enrollment Policy) returns the list of templates the caller may enrol. CertAutoPilot calls this on Sync.
- CES (MS-WSTEP — Certificate Enrollment Service) accepts the CSR and returns the issued certificate. "WSTEP" is simply the protocol this CES endpoint speaks — it is not a separate URL.
So there is no separate "WSTEP" field: you supply a CEP Endpoint URL (for template discovery) and a CES Endpoint URL (for enrolment). Both are required — CertAutoPilot cannot run CES-only without a CEP endpoint for templates.
Typical URLs — both endpoints must be the _UsernamePassword virtual directories, the only auth mode CertAutoPilot implements:
CEP: https://<ca-host>/ADPolicyProvider_CEP_<Auth>/service.svc
CES: https://<ca-host>/<CA-name>_CES_<Auth>/service.svc
Find the exact virtual-directory names in IIS Manager on the CA host (the *_CEP_* and *_CES_* applications under the enrollment site).
Prerequisites
- An AD CS server with the CES/CEP (Certificate Enrollment Web Services) roles installed.
- A service account in AD with permission to Read and Enroll the templates you want to use.
- Network reachability from the worker to the enrollment endpoint (typically port 443 on the CA host or an IIS frontend).
Preflight check script
Run this from a Windows host on the same network path as the CertAutoPilot worker, before you add the provider. It prompts for your CEP URL, CES URL, and the AD service account, then for both endpoints checks: TCP reachability, that the TLS chain validates, and how the endpoint responds to an authenticated request. Green = ready; fix every FAIL first.
Two honest limits: (1) if the probe host is domain-joined it auto-trusts your enterprise root via group policy — the worker (often a Linux container) does not, so a TLS PASS here still requires pasting the issuing root into the profile's TLS-trust field unless the worker's CA bundle has it; (2) *_UsernamePassword vdirs run anonymous IIS authentication (credentials are verified inside the SOAP message, not by IIS), so this probe proves reachability but cannot verify the password. Neither can CertAutoPilot's own Test button: it treats a 401/403 as endpoint alive, auth enforced and still passes. Use Sync Templates to prove the credentials actually work.
# CertAutoPilot — Microsoft AD CS (CES/CEP) preflight. Run on the worker host.
$ErrorActionPreference = 'Continue'
$pass = 0; $fail = 0; $warn = 0
function Ok($m) { Write-Host "[ PASS ] $m" -ForegroundColor Green; $script:pass++ }
function Bad($m) { Write-Host "[ FAIL ] $m" -ForegroundColor Red; $script:fail++ }
function Warn($m) { Write-Host "[ WARN ] $m" -ForegroundColor Yellow; $script:warn++ }
function Info($m) { Write-Host " $m" -ForegroundColor Gray }
Write-Host "`n=== CertAutoPilot AD CS (CES/CEP) preflight ===`n" -ForegroundColor Cyan
$cepUrl = Read-Host "CEP Endpoint URL (.../ADPolicyProvider_CEP_<Auth>/service.svc)"
$cesUrl = Read-Host "CES Endpoint URL (.../<CA>_CES_<Auth>/service.svc)"
$cred = Get-Credential -Message "AD service account (DOMAIN\user) with Read + Enroll on your templates"
function Test-Endpoint($label, $url) {
Write-Host "`n--- $label : $url ---" -ForegroundColor Cyan
try { $u = [Uri]$url } catch { Bad "$label URL is not a valid URI"; return }
if ($u.Scheme -ne 'https') { Warn "$label is not HTTPS — CES/CEP should use TLS" }
if ($label -eq 'CEP' -and $url -notmatch '_CEP_') { Warn "CEP URL has no _CEP_ virtual dir — did you paste the CES URL?" }
if ($label -eq 'CES' -and $url -notmatch '_CES_') { Warn "CES URL has no _CES_ virtual dir — did you paste the CEP URL?" }
$port = if ($u.Port -gt 0) { $u.Port } else { 443 }
# 1. TCP reachability
$tcp = Test-NetConnection -ComputerName $u.Host -Port $port -WarningAction SilentlyContinue
if ($tcp.TcpTestSucceeded) { Ok "$label reachable at $($u.Host):$port" }
else { Bad "$label NOT reachable at $($u.Host):$port — DNS / routing / firewall"; return }
# 2. TLS: validate the chain + hostname the way a client would
$script:tlsOk = $true
try {
$client = [Net.Sockets.TcpClient]::new($u.Host, $port)
$cb = [Net.Security.RemoteCertificateValidationCallback]{
param($s, $cert, $chain, $errors)
if ($errors -ne [Net.Security.SslPolicyErrors]::None) { $script:tlsOk = $false }
return $true
}
$ssl = [Net.Security.SslStream]::new($client.GetStream(), $false, $cb)
$ssl.AuthenticateAsClient($u.Host)
$c = [Security.Cryptography.X509Certificates.X509Certificate2]$ssl.RemoteCertificate
Info "server cert: $($c.Subject) (expires $($c.NotAfter.ToString('yyyy-MM-dd')))"
if ($script:tlsOk) { Ok "$label TLS chain validates and hostname matches" }
else { Warn "$label TLS does NOT validate (self-signed / untrusted / name mismatch) — paste the issuing root as TLS trust, or make the worker trust it" }
if ($c.NotAfter -lt (Get-Date)) { Bad "$label server certificate is EXPIRED" }
$ssl.Dispose(); $client.Close()
} catch { Warn "$label TLS probe failed: $($_.Exception.Message)" }
# 3. Endpoint probe with the service account (NTLM / Negotiate on challenge).
# Kerberos/Windows-auth vdirs challenge with 401 — a non-401 there means the
# account was accepted. UsernamePassword vdirs are ANONYMOUS in IIS (the
# password is verified inside the SOAP message), so any 2xx/4xx only proves
# reachability — CertAutoPilot verifies the password itself on Save.
try {
$resp = Invoke-WebRequest -Uri $url -Credential $cred -UseBasicParsing -Method Get -TimeoutSec 20 -ErrorAction Stop
if ($url -match '_(CEP|CES)_UsernamePassword') {
Ok "$label reachable (HTTP $($resp.StatusCode)); UsernamePassword vdir is anonymous in IIS — password is verified by CertAutoPilot on Save"
} else {
Ok "$label authenticated OK (HTTP $($resp.StatusCode)) — the service account is accepted"
}
} catch {
$code = $_.Exception.Response.StatusCode.value__
if ($code -eq 401) { Bad "$label returned 401 — credentials rejected, or NTLM/Kerberos disabled on the endpoint's IIS auth settings" }
elseif ($code -eq 403) { Warn "$label returned 403 — authenticated but forbidden (account lacks rights on this vdir)" }
elseif ($code) { Ok "$label reachable (HTTP $code from a GET on a SOAP-only endpoint is expected)" }
elseif ($_.Exception.Message -match 'trust relationship|SSL|TLS') {
Warn "$label request blocked by TLS trust on THIS host: $($_.Exception.Message) (see the TLS check above — paste the issuing root into the profile's TLS trust field)"
}
else { Bad "$label request failed: $($_.Exception.Message)" }
}
}
Test-Endpoint 'CEP' $cepUrl
Test-Endpoint 'CES' $cesUrl
Write-Host "`n=== Result: $pass passed, $warn warning(s), $fail failed ===" -ForegroundColor Cyan
if ($fail) { Write-Host "Fix the FAIL items before adding the AD CS provider." -ForegroundColor Red }
elseif ($warn) { Write-Host "Reachable & authenticated — review the warnings (TLS trust / URL suffix) for your setup." -ForegroundColor Yellow }
else { Write-Host "All good — CEP and CES are reachable, TLS validates, and the account authenticates." -ForegroundColor Green }
Notes: the AD CS template Read/Enroll rights are checked at enrollment time, so also confirm those on the CA (see Prerequisites and Policy fetch returns 401). For Kerberos vdirs run the script as (or from) a domain-joined context — there the probe genuinely proves IIS accepted the account; the only credential check that actually exercises the account is Sync Templates; neither Save nor Test does.
Create the profile
- Settings → Certificate Authorities → Microsoft AD CS tab → Add Connection. (Settings → CA Providers lists the seeded public ACME CAs and has no create action.)
- CEP Endpoint URL — the policy service (e.g.
https://<ca-host>/ADPolicyProvider_CEP_UsernamePassword/service.svc). - CES Endpoint URL — the enrollment service (e.g.
https://<ca-host>/<CA-name>_CES_UsernamePassword/service.svc). Its_<Auth>_suffix must match the CEP URL's and your chosen auth mode. - Authentication — username and password. This is the only supported mode; the credentials travel inside the SOAP message as a WS-Security
UsernameToken, not as HTTP NTLM or Negotiate. - Optional: TLS trust — if your CA chain isn't system-trusted, paste the issuing root.
- Save — this performs no network call; it validates the fields and stores the encrypted credentials. Use Test for reachability and Sync Templates to fetch the template list.
Authentication
Username and password is the only implemented mode. Creating or updating a connection with any other auth type is rejected. Client-certificate (mutual-TLS) and Kerberos authentication to the CES/CEP endpoints are not supported.
The credentials are sent as a WS-Security UsernameToken inside the SOAP envelope; no HTTP Authorization header is ever set, so IIS never negotiates NTLM or Kerberos. Point both endpoints at the _UsernamePassword virtual directories, and pin a service account with the template permissions you need.
Templates
When issuing, the operator picks one of the templates returned by CEP. Common templates: WebServer, Computer, EnrollmentAgent. The template controls subject format, key usages, key size and validity period. CertAutoPilot checks two of them before it sends anything: the template name must be in the synced list, and the key must be at least as long as the template's minimum key size, which the policy reports and Sync stores with each template (ECDSA P-256 is 256 bits, P-384 384, RSA its size). A shorter key is refused with MSCA_TEMPLATE_KEY_TOO_SMALL (the issue wizard disables those key types; a key type you chose is kept while the template accepts it, otherwise the selection moves to the organization's default key type when the template accepts that, else to the smallest key type the template accepts) — the CA would deny it as Denied by Policy Module (0x80094811). A template synced before this check existed has no stored minimum: Sync again to enable it. Any other mismatch (subject format, key algorithm the template does not allow, enrol rights) still surfaces as an MSCA_DENIED_BY_POLICY error from the CA at enrollment.
The template's Subject Name setting must be Supply in the request. A template that builds the subject from Active Directory (the built-in User, Computer and Domain Controller templates, or a copy of them) ignores the names in the request: the CA issues a certificate that names the account CertAutoPilot signs in with, not your domain. CertAutoPilot checks every certificate the CA returns — at issuance, at renewal and after an approval — and refuses one that does not name every requested domain with MSCA_CERT_NAME_MISMATCH (see Issued certificate does not name the domain).
With an RPC connection whose templates are read from Active Directory, Sync stores more about each template, and the issue wizard and certificate create use it before anything is sent to the CA:
- a template that cannot work is marked unusable with its reason and refused with
MSCA_TEMPLATE_NOT_USABLE: its subject is built from Active Directory, it needs enrollment-agent signatures, or the account has no Enroll right on it (read from the template's permissions, including the account's groups; a deny wins); - the key algorithm the template accepts (a version 4 template names it; older templates use RSA) — a key type it does not accept is refused with
MSCA_TEMPLATE_KEY_ALGORITHM. This is checked by CertAutoPilot because a CA does not always check it itself: measured, one CA refused an ECDSA key on an RSA template and another issued it; - the minimum key size, and whether a CA manager must approve each request (shown in the wizard).
With typed template names none of this is known and the CA's answer decides.
A CES/CEP connection fetches the list via a live CEP GetPolicies call on every Sync, then stores it on the connection. Issuance validates the requested template against that stored copy, so a template added on the CA is only usable after a re-sync. If a newly added template doesn't appear after a re-sync, the cause is on the AD CS side — see New template doesn't appear after Sync.
Renewal
Renewal works the same as issuance — submit a new CSR against the same template. CertAutoPilot keeps the same logical certificate identity in the UI; the underlying X.509 changes, history is preserved.
Pending approval, denials and polling
A template with CA certificate manager approval parks every request (the CA answers Taken Under Submission): the certificate moves to msca_pending_approval and a poll job asks the CA again every few minutes for up to 7 days. Approving the request in certsrv.msc (or certutil -resubmit <id>) is picked up by the next poll, which stores the certificate; denying it (certutil -deny <id>) ends the request — a first issuance returns to pending with the reason under Last Error, a renewal ends at once (renewal_failed, see below), and a re-issue of a certificate still in use returns that certificate to its previous status with its own key. The operator is notified (Certificate Issuance Failed / Renewal Failed) in every case.
A request the CA refuses at once — Denied by Policy Module (a key size below a minimum CertAutoPilot did not know, a missing Enroll right, a subject the template does not allow) — is final: the job fails once and is not retried (an earlier version retried it three times, sending the CA three requests with three new keys). Fix the cause on the CA or the template and use Re-issue (a first issuance) or Renew.
A renewal the CA refuses — at once or after a manager's denial — is not sent again either: the certificate goes to renewal_failed, automatic renewal stops (the renewal ladder and the daily renewal_failed safety net skip it, since the same request would be refused again) and the certificate in use keeps serving until it expires. A CA-side error for the request ends the renewal the same way, but the daily safety net may try again. Renew after fixing the cause starts over.
A re-issue whose job died while the certificate showed issuing is recovered by the scheduler after two hours: the certificate returns to the status it had, with its own key, and the operator is notified. The request the dead job sent to the CA, if any, is abandoned.
The answer is read by its content, not only its wording: a returned certificate is an issuance and a request number without a certificate is a request the CA keeps, so a CA that answers in another language (Turkish, German…) is handled the same way.
While a renewal or re-issue waits for approval, the certificate in use keeps serving and keeps receiving its expiry warnings and the expired notice.
Troubleshooting
Policy fetch returns 401
Either credentials are wrong or NTLM/Kerberos is disabled on the IIS authentication settings of the policy site. Test with curl --ntlm -u DOMAIN\user:pass <url> from the worker host.
New template doesn't appear after Sync
CertAutoPilot returns exactly what CEP GetPolicies gives it, so a missing template means the CA's policy endpoint isn't returning it. Duplicating a template in the Certificate Templates Console (certtmpl.msc) only creates the AD object — it is not offered for enrollment until all three of the following are true. Work through them in order, then re-Sync:
-
Publish it to the CA.
certsrv.msc→ your CA → Certificate Templates → right-click → New → Certificate Template to Issue → select the template. (Duplicating ≠ publishing — this is the most common miss.) -
Grant Enroll to the service account. Template Properties → Security → add the account CertAutoPilot authenticates as → allow Enroll (or Autoenroll). CEP only returns templates the caller can enrol.
-
Refresh the CEP policy cache. The policy web service caches its template set in memory, so a fresh template can lag even after steps 1–2. Recycle just the CEP/CES application pool on the CA's IIS frontend (least disruptive):
Restart-WebAppPool -Name "<CEP/CES app pool>" # e.g. WSEnrollmentPolicyServeriisresetalso works but bounces the whole IIS instance. Neither touches the CA engine, issued certificates, or CRL publishing — only the enrollment web front-end blips for a few seconds. If the domain has multiple DCs, also allow AD replication of the new template object (repadmin /syncall).
After steps 1–3, click Sync again — the new template appears. To see exactly what CEP returned, enable backend debug logging and look for the CEP GetPolicies raw response entry.
Issued certificate does not name the domain
Last Error starts with MSCA_CERT_NAME_MISMATCH and shows the names the certificate carries, for example issued certificate (CN=svc-account, SANs=[]) does not cover app.example.com. The CA issued the certificate, but the template builds its subject from Active Directory, so it names the service account instead of the requested domain. CertAutoPilot does not store or distribute such a certificate and does not send the request again — the same request would get the same certificate:
- a first issuance returns to
pending; - a re-issue returns the certificate in use to its previous status, with its own key;
- a renewal ends at once (
renewal_failed) and automatic renewal stops, while the certificate in use keeps serving.
Fix: in certtmpl.msc open the template → Subject Name → choose Supply in the request (or pick a template that already does, such as a copy of Web Server), publish it to the CA, Sync the connection, then Re-issue or Renew. The certificate the CA issued for the refused request (its request number is in the message) stays in the CA database; revoke it there if your policy requires it.
RPC: the CA cannot be reached
MSCA_ENDPOINT_UNREACHABLE — nothing answered on TCP 445 of the CA server. Check the firewall between the worker and the CA server, and that the CA role's CERTSVC-RPC-NP-IN rule is enabled on it.
RPC: no Kerberos KDC
MSCA_KDC_UNREACHABLE — the worker could not find or reach a domain controller on TCP 88 for the realm (for example the domain's _kerberos._tcp DNS record does not resolve from the worker). Set a Domain controller on the connection (it is also used as the KDC) or a KDC under Advanced, and allow TCP 88 to it.
RPC: sign-in refused
MSCA_AUTH_FAILED — the user name or password is wrong, the account is locked or disabled, (NTLM) the domain does not allow NTLM, or the CA does not let the account request certificates (grant Request Certificates on the CA, see Required permissions). Use Kerberos where NTLM is turned off. A failed sign-in counts toward the domain's account lockout, and a job retries it — fix the password before the next attempts lock the account.
RPC: CA not running or wrong CA name
MSCA_CA_UNAVAILABLE — the server answered but the Certificate Services service is not running there, or the CA is suspended or out of database sessions (start Active Directory Certificate Services; requests are retried, never read as a denial). MSCA_CA_NAME_INVALID — the server does not host a CA with that name; use the name certutil -cainfo name prints on the CA server.
RPC: templates cannot be read
MSCA_DIRECTORY_ERROR — no domain controller was found, it refused the search, or the CA is not listed in the directory. MSCA_ENDPOINT_UNREACHABLE — the domain controller did not answer on TCP 636 (or 389). MSCA_AUTH_FAILED — it refused the user name or password. MSCA_TLS_VALIDATION — its certificate is not trusted; the message (and presented_fingerprint / presented_by in the API answer) names the fingerprint it presented and the controller that presented it: check it on the domain controller, then pin it (or paste the CA certificate that issued it into TLS trust). A domain controller addressed by IP address is checked against the names in its certificate, which rarely list the IP — pin its fingerprint or use its DNS name. A domain controller that requires LDAP signing refuses plain LDAP on 389 — use LDAPS or StartTLS.
Waiting for approval: request gone from the CA
When the request a certificate waits on is deleted from the CA database, the next poll ends the wait: the CA has no such request any more. The certificate returns as after a denial, with the request number in Last Error.
TLS handshake fails
CES/CEP: the IIS frontend uses an internal CA your worker doesn't trust. Paste the issuing root into the profile's TLS trust field.
See also
Video tutorials
Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →