The CA connector

The CA connector is a separate 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 a signing endpoint 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 toThe connector, directly, on your internal network.
The connector talks toThe local CA, through certreq / certutil.
The connector reports to aethercertIts liveness, and the certificate templates it discovered.
The connector never sends aethercertCertificate material, CSRs, or keys.

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

Manage › CA Connectors - liveness and discovered templates.

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.

Install on the CA server

On the AD CS server, from an elevated PowerShell:

.\aethercert-installer-windows-amd64.exe install `
  --api https://your-app.example.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:

FlagDefaultWhat it sets
--public-url <url>Derived from the host's FQDNWhere fleet agents reach this connector on your internal network.
--listen <addr>:8443The local listen address.
--ca-config <name>Auto-detected, if there is exactly oneThe certreq/certutil -config target, as <CAHostName>\<CAName>. Name it explicitly when the domain has more than one CA.
--template <name>WebServerThe certificate template to issue against.
--tls-cert / --tls-keyThe CA issues oneYour own certificate for the connector's listener.
--service-account <user>LocalSystemRun the service as this account. See below.
--service-password <pw>-Password for that account. Not needed for a gMSA.
--no-firewall-ruleRule is addedSkip 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 the better one:

  1. Grant those rights to the machine account. Works, but ties a CA permission to a computer object.
  2. 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. This is the recommended setup - the permission then belongs to an identity you can name, audit and revoke.

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

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:

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

Transport pinning is not the authentication

Fleet agents authenticate every request to the connector with the shared API key regardless of which of those three applies. 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, and they appear as a dropdown on the certificate job form. Leaving it at Connector default uses the template the connector was installed with.

The form warns inline about two categories that are 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.

Updating, repairing and removing

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

.\aethercert-installer-windows-amd64.exe repair --component ca_connector
.\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://your-app.example.com `
  --token <token> `
  --public-url https://adcs01.corp.internal:8443 `
  --ca-config "ADCS01\Corp Issuing CA"

You then register and start the Windows service yourself - with a dedicated service account - and separately install the Update Service if you want automatic updates. Full flag list: Agent CLI reference.