Authorities

Authorities are the PKI backends that Certeasy submits certificate requests to. Each authority represents one ADCS instance (or a fake PKI for testing).

Configuration

authorities:
  - name: ca1
    type: adcs                 # native connector (default) — see "Connector" below
    configuration:
      ca-name: "PKI\\LAB-RootCA"
      certificate-template: "ACME-Template-Server"
      default-timeout: 4m

Fields

Field	Required	Description
name	Yes	Unique authority name. Referenced in policy bindings.
type	Yes	Authority type: adcs / adcs-native (native connector, default) · adcs-cli (certreq.exe connector) · fake (testing)
policies	No	Remote authority policy constraints (advanced). If omitted, all local policies are candidates.
disable-ca-revocation	No (default false)	When true, keep ACME revocations local to Certeasy instead of propagating them to the backing CA (CRL/OCSP). Leave unset (or false) to propagate. See Revocation.
configuration	Yes	Type-specific configuration block (see below)

ADCS Authority

Connector: native (default) or certreq.exe

Certeasy talks to ADCS through one of two interchangeable connectors. Both issue the same certificates from the same ca-name and certificate-template — only the integration method differs.

type	Connector	Notes
adcs (default), adcs-native	Native — Certeasy enrolls in-process through the built-in Windows certificate API. No external program is launched.	Recommended. Nothing extra to install, and the cleanest fit for hardened, EDR-monitored hosts (see Antivirus & EDR).
adcs-cli	certreq.exe — Certeasy drives the standard Windows certreq.exe tool.	Choose this if you prefer the classic certreq.exe integration, or want it as a fallback.

type: adcs resolves to the native connector, so an existing configuration moves to it automatically on upgrade — no change required. Both connectors are Windows-only: ADCS enrollment runs on a Windows host joined to, or able to reach, the CA.

Prefer the native connector at scale

On large or high-throughput deployments, use the native connector (adcs / adcs-native). It runs in-process and bounds concurrency to the worker pool, whereas adcs-cli spawns a child process per operation (certreq.exe to issue, certutil.exe to revoke) — process-creation overhead, temp-file churn and OS process limits add up under load. Keep adcs-cli for compatibility or as a fallback, not for heavy issuance/revocation volume.

Configuration Fields

Field	Default	Applies to	Description
ca-name	—	both	Full CA name as shown by certutil -CA (e.g. PKI\LAB-RootCA)
certificate-template	—	both	ADCS certificate template name for ACME issuance
default-timeout	4m	both	Maximum wait time for a single ADCS request. Keep it below workers.max-job-duration (default 5m) so the ADCS timeout — not the surrounding job deadline — bounds the call; Certeasy warns at startup if it is greater than or equal to max-job-duration.
certreq-path	system directory	adcs-cli only	Path to certreq.exe (enrollment). Ignored by the native connector.
certutil-path	system directory	adcs-cli only	Path to certutil.exe, used for revocation (certutil -revoke). certutil is a different binary from certreq. Ignored by the native connector. Only relevant when revocation propagation is enabled (i.e. disable-ca-revocation is not set).

Since 0.9.4, both binaries are taken from the Windows system directory (typically C:\Windows\System32) instead of being looked up through %PATH%. Leaving the key unset — or giving just a file name, with or without the .exe extension — resolves there.

Set a full path only to run a copy kept elsewhere, for instance on a dedicated path carved out of an Endpoint Detection and Response (EDR) policy:

      certutil-path: "C:\\Tools\\certutil.exe"

A path relative to the working directory (tools\certutil.exe) is refused at startup and by certeasy validate.

Finding your CA Name

certutil -CA

The output shows the CA name in the format Machine\CAName. Use this exact string in ca-name.

Certificate Template Requirements

The ADCS template must:

• Allow enrollment by the Certeasy service account
• Be configured for Web Server or equivalent (Server Authentication EKU)
• Not have conflicting subject policies that would override the CSR

tip

Create a dedicated template for Certeasy (e.g. ACME-Template-Server) rather than reusing an existing one. This isolates the configuration and simplifies auditing.

Revocation

When an ACME client revokes a certificate (RFC 8555 §7.6), Certeasy marks it revoked in its own database and, by default, propagates the revocation to the backing CA so the certificate also appears revoked in the CA's CRL/OCSP.

authorities:
  - name: ca1
    type: adcs
    disable-ca-revocation: false   # default — propagate to the CA's CRL/OCSP
    configuration:
      ca-name: "PKI\\LAB-RootCA"
      certificate-template: "ACME-Template-Server"

Revocation requires higher privileges than enrollment. Issuing certificates needs only Read + Enroll on the template and Request Certificates on the CA. Revoking requires the Certificate Manager role — the Issue and Manage Certificates permission on the CA. If the Certeasy service account lacks it, enrollment keeps working but revocation fails with an Access Denied error (surfaced in the audit log as certificate.revoke.publish_failed).

Revocation is asynchronous: the ACME client receives its 200 immediately, and Certeasy publishes to the CA in the background, retrying with an escalating backoff (minutes to hours) if the CA is temporarily unreachable. RFC 8555 §7.6 does not require publication to be confirmed before responding.

Set disable-ca-revocation: true to keep revocation local to Certeasy (no CA propagation). This is appropriate when:

• the service account cannot be granted the Certificate Manager role, or
• you intentionally rely on short-lived certificates and local revocation only.

Note that this is a privilege decision, not a connectivity one: revocation targets the same CA host and channel as enrollment, so a CA reachable enough to issue is reachable enough to revoke.

With propagation disabled, the audit log records certificate.revoke.skipped instead of certificate.revoke.published.

Two authorization modes are accepted, per RFC 8555 §7.6:

• Account key — the account that owns the certificate signs the request.
• Certificate key — the request is signed with the certificate's own private key (the canonical "the key has leaked, revoke it" path). This works even without the issuing account, since possession of the private key is the proof.

The following CRL reason codes are accepted: 0 unspecified, 1 keyCompromise, 2 cACompromise, 3 affiliationChanged, 4 superseded, 5 cessationOfOperation, 9 privilegeWithdrawn, 10 aACompromise. The stateful codes 6 (certificateHold) and 8 (removeFromCRL) are rejected, because Certeasy revocation is terminal (no hold/un-revoke lifecycle).

Fake PKI Authority (Testing)

The fakepki authority type is a built-in self-signed CA for local testing. It does not connect to any external system.

authorities:
  - name: test-ca
    type: fake
    configuration:
      common-name: "Certeasy Test CA"
      password: "testpassword"
      key-size: 4096
      validity: 3650            # CA certificate lifetime, in days
      certificate-validity: 2160h   # issued-certificate lifetime (default 90 days)

Fake PKI Configuration Fields

Field	Description
common-name	CN of the fake CA certificate. Required.
password	Password encrypting the CA key on disk. Required — whoever reads that file otherwise becomes the authority.
key-size	RSA key size for the CA, applied only when the CA is generated. Defaults to 4096 when omitted.
validity	Lifetime of the CA certificate, in days. Defaults to 3650 when omitted.
certificate-validity	Lifetime of issued certificates (Go duration, e.g. 2160h). Also bounds the CRL: a revoked serial is purged at RevocationTime + certificate-validity (it would be expired anyway), so the CRL cannot grow without bound. Default 90 days.

The CA key cannot be weaker than what it signs

key-size must be at least the highest min-rsa-bits of the issuance policies bound to this authority — 3072 by default — with a hard floor of 2048. A CA signing 3072-bit certificates with a 2048-bit key is refused at startup, and by certeasy validate.

key-size only applies when the CA is generated

An existing ca.key is loaded as it stands and is never regenerated — replacing it would invalidate every certificate the authority has issued. So on an authority that already has a CA, changing key-size changes nothing: the key keeps the size it was created with, and the value in the configuration describes an intention rather than what runs.

Certeasy logs a warning at startup when the two disagree, giving the size in use and the configured one. Moving to a stronger CA is a deliberate rollover: create a new authority and re-issue, rather than editing this field.

Note the two checks fire at different moments. key-size against the policy floor is a static check, so certeasy validate and the startup gate both refuse it before anything else happens. The common-name check compares the configuration with the certificate on disk, so it can only run once the authority is opened, later in startup.

warning

The fake authority is for development and testing only. Do not use it in production.

Multiple Authorities

You can define multiple ADCS authorities for redundancy or to serve different policies:

authorities:
  - name: adcs-primary
    type: adcs
    configuration:
      ca-name: "PKI\\Primary-CA"
      certificate-template: "ACME-Server"

  - name: adcs-backup
    type: adcs
    configuration:
      ca-name: "PKI\\Backup-CA"
      certificate-template: "ACME-Server"

Then reference both in a policy binding with strategy: first_available.