The CA connector

Connect aethercert to Active Directory Certificate Services: what the connector does, installing and pairing it, the CA rights it needs, and its readiness check.

The CA connector is a Windows service that lets aethercert issue from a certificate authority which speaks neither ACME nor a REST API. In practice that means Active Directory Certificate Services, which is reached through Windows RPC from a domain-joined host.

It is only needed for that case. An internal CA that speaks ACME, or exposes an HTTP endpoint that signs a CSR, connects directly - see Certificate authorities.

What it does, and what it does not

The connector runs on the CA host - or a domain-joined host beside it - and answers sign and revoke requests from your fleet agents over your internal network.


Agents talk to	The connector, directly, on your internal network.
The connector talks to	The local CA, through `certreq` and `certutil`.
The connector reports to aethercert	Its liveness, the templates it discovered, and a health snapshot of the CA.
The connector never sends aethercert	Certificate material, CSRs, or keys.

Certificate data never leaves your network. The control plane knows a connector is alive and which templates exist; the certificates themselves travel from the CA to the agent that asked for them.

The connector checks in every 30 minutes by default. It never polls for jobs through that channel - agents reach it directly - so the cadence is only about liveness, templates, CA health and its own updates.

How a request is authorized

An agent does not hold a long-lived shared secret for the connector. Each sign or revoke request carries a short-lived, job-bound token the control plane minted when it dispatched the job. The connector:

verifies the token's signature locally against the control plane's published JWKS, and
calls back to POST /api/ca-connector/authorize to confirm the job it names is still open, is still for that agent, and that the token has not been used before,

and only then touches certreq.exe. A signature alone proves the control plane issued the token at dispatch time; it cannot prove the job has not since been cancelled. The callback is what proves that. A denial, and especially a replay, is recorded as an alert-worthy event.

Setting one up

The connector pairs with an Internal CA (REST) authority, so that entry comes first.

Create the authority and a pairing token. Under Manage > Certificate Authorities, add an authority of type Internal CA (REST) and tick provision via a CA connector - the base URL and signing path are filled in at pairing rather than typed now. Then open its Connector panel and generate a one-time pairing token. It expires an hour after it is created.
Install on the CA server. From an elevated PowerShell on the AD CS host:
```
.\aethercert-installer-windows-amd64.exe install `
  --api https://api.aethercert.com `
  --token <token>
```
The token itself decides that this is a connector install rather than a fleet agent, so the command is the same one you would use for an agent.

The installer auto-detects the public URL from the host's own FQDN and the CA to pair with through Active Directory. It defaults to the WebServer template, listens on :8443, adds a Windows Firewall rule for that port, and runs as LocalSystem.
Grant the service account rights on the CA. This is the step that is easy to miss. See below.

Every default above is also a flag, and every flag is a field on the setup window's Options page if you start the installer with no arguments instead:

Flag	Default	What it sets
`--public-url <url>`	Derived from the host's FQDN	Where fleet agents reach this connector on your internal network.
`--listen <addr>`	`:8443`	The local listen address.
`--ca-config <name>`	Auto-detected, if there is exactly one	The `certreq`/`certutil` `-config` target, as `<CAHostName>\<CAName>`. Name it explicitly when the domain has more than one CA.
`--template <name>`	`WebServer`	The certificate template to issue against.
`--tls-cert` / `--tls-key`	The CA issues one	Your own certificate for the connector's listener.
`--service-account <user>`	LocalSystem	Run the service as this account.
`--service-password <pw>`		Password for that account. Not needed for a gMSA.
`--no-firewall-rule`	Rule is added	Skip opening the listen port inbound.

Service account rights

By default the connector runs as LocalSystem, which authenticates to AD CS as the machine account. That account usually has neither of the two rights the connector needs:

Enroll on the certificate template it issues against.
Issue and Manage Certificates on the CA itself, for revocation.

You have two options, and the second is better:

Grant those rights to the machine account. Works, but ties a CA permission to a computer object.
Install under a dedicated service account with --service-account, and grant the rights to that. A group managed service account - a name ending in $ - works and needs no password. The permission then belongs to an identity you can name, audit and revoke.

The installer grants that account Log on as a service for you and checks the credentials before it registers the service, so a wrong password or a deny-logon policy is reported immediately. It does not touch any CA or template permission; those two rights are still yours to grant.

Without these rights the connector installs and pairs successfully and then fails every signing request, which makes this the first thing to check when nothing issues.

Readiness check

The installer runs a read-only readiness check at the end of a connector install and reports each item as OK, needs a manual look, or the exact step still missing. You can re-run it at any time:

.\aethercert-ca-connector.exe preflight

It checks nine things: that the service account exists and holds Log on as a service; that the Windows service is registered, running, and running as the intended account; that the CA is reachable; that the CA grants the account Issue and Manage Certificates; that templates were found; that the template grants Enroll; and finally that the connector is ready overall.

It changes nothing - not the CA, not a template, not an ACL. A permission held through a group it cannot expand offline is reported as review this, with the console path to confirm it, rather than as a false pass. It exits non-zero only when the connector genuinely cannot issue as configured.

The connector's own TLS certificate

The connector serves HTTPS to your agents, so it needs a certificate of its own. The installer works down this order:

Use --tls-cert and --tls-key, if you supplied your own.
Request one from the CA it just paired with, using the WebServer template.
If that fails, generate a self-signed certificate and persist it. Pairing then sets insecure_skip_verify automatically so agents do not reject it.

Transport pinning is not the authentication

Fleet agents authenticate every request to the connector with a signed, job-bound token regardless of which of those three applies, and the connector confirms it with the control plane before acting. The listener certificate affects transport-level pinning only - a self-signed fallback does not leave the connector open to anyone who can reach the port.

Certificate templates

Once paired, the connector reports the templates it can see - up to 200 - and they appear as a dropdown on the certificate job form. Leaving it at Connector default uses the template the connector was installed with.

An operator can curate that list under Manage > Connectors > Edit > Templates, so only the templates you want offered appear. A template already selected on an existing certificate stays selectable in that certificate's own form even if it has since been hidden, so saving it without changing anything cannot silently clear it.

The form warns inline about two common misconfigurations:

Client-authentication templates used for a server certificate. The resulting certificate will not be accepted for TLS server authentication.
Subject-from-Active-Directory templates, where the CA overrides the subject you requested with one built from the directory - so the certificate does not carry the common name you asked for.

The scan behind these signals is best-effort, so they are advisory rather than a hard gate. A template's minimum RSA key size, where the scan found one, does filter the key-type options on the form.

Updating, repairing and removing

The connector is updated by the same Update Service as the agent, and repaired by the same command:

.\aethercert-installer-windows-amd64.exe repair --component ca_connector
.\aethercert-installer-windows-amd64.exe repair --component ca_connector --redownload
.\aethercert-installer-windows-amd64.exe uninstall --connector

Repair also re-adds the firewall rule, which is worth knowing if a hardening pass removed it.

Manual pairing

For a setup where you want to register the service yourself, the connector binary pairs without installing anything:

.\aethercert-ca-connector.exe enroll `
  --api https://api.aethercert.com `
  --token <token> `
  --public-url https://adcs01.corp.internal:8443 `
  --ca-config "ADCS01\Corp Issuing CA"

enroll registers no Windows service and has no --service-account option of its own

that flag lives on aethercert-installer install. Afterwards, either run aethercert-installer repair --component ca_connector (which registers the service and does take --service-account / --service-password), or register it by hand:

sc.exe create AetherCertCAConnector `
  binPath= "<path>\aethercert-ca-connector.exe run" `
  obj= <DOMAIN\account> password= <pw> start= auto
sc.exe start AetherCertCAConnector

sc.exe grants the account Log on as a service as part of obj=. Separately run aethercert-update-service install if you want automatic updates.

Re-pairing an existing connector is the same flow: generate a fresh pairing token from the authority's Connector panel and install again. It overwrites that CA's connector identity rather than creating a second one.

The connector also reports a continuous health snapshot of the CA it fronts, and carries a hardening checklist. See CA health and hardening.