Minimal Configuration

Certeasy is configured with a single YAML file. This page shows the smallest valid configuration to get started.

Config File Location

Pass the config file explicitly:

certeasy.exe -f C:\certeasy\config.yml

Without -f, Certeasy searches for config.yml / config.yaml in:

1. Current directory
2. Executable directory
3. Windows: %PROGRAMDATA%\certeasy, then user config directory
4. Linux: $XDG_CONFIG_HOME/certeasy, then /etc/certeasy

Minimal Example

This configuration relies on safe defaults wherever possible:

server:
  url:
    - "https://acme.corp.internal"
  listen: ":8443"

tls-certificate-manager:
  bundles:
    - name: public
      mode: pki
      authority: ca1

dns-validation-profiles:
  - name: internal
    mode: local
    zones:
      - suffixes:
          - "corp.internal"
        system: true

authorities:
  - name: ca1
    type: adcs
    configuration:
      ca-name: "PKI\\LAB-RootCA"
      certificate-template: "ACME-Template-Server"

issuance-policies:
  - name: corp-server
    dns:
      allow:
        - ".corp.internal/3"

What this configuration actually does

In plain English:

Certeasy listens on port 8443 and exposes itself at https://acme.corp.internal. It contacts LAB-RootCA (your ADCS) to obtain a certificate for that hostname using the ACME-Template-Server template, and renews it automatically before expiry. It accepts ACME certificate requests for any name under corp.internal (up to 3 labels), validates challenges using the system DNS resolver, and forwards CSR signing to the same LAB-RootCA.

The authority ca1 plays two roles here: it secures Certeasy's own HTTPS endpoint and signs the certificates your ACME clients request. Both use the same ADCS CA and the same template.

ca-name (PKI\\LAB-RootCA) is the name of your ADCS certification authority — the backslash-separated form is <server>\<CA common name>. You can retrieve the exact value with certutil -CA on the ADCS host. certificate-template (ACME-Template-Server) is the name of the certificate template configured in ADCS for ACME enrollment. See ADCS Configuration for how to set up the template and permissions.

Workers

Certeasy processes certificate orders (validation, CSR submission, renewals) through an internal job queue. By default, 4 workers consume that queue in the background. You don't need to configure this for a standard deployment — the default handles the load of most environments. Workers are only worth tuning if you have a very high volume of concurrent requests.

Implicit policy binding

This configuration has exactly one policy (corp-server) and one authority (ca1). Certeasy connects them automatically — no policy-bindings section is needed.

Think of it like a default route

With a single destination, you don't need a routing table. As soon as you add a second authority (e.g. a pre-production CA), Certeasy can no longer guess which policy routes where — you'll need to declare policy-bindings explicitly at that point.

How PKI-mode TLS works

On first startup, Certeasy submits a CSR to your ADCS for a certificate covering acme.corp.internal (taken from server.url). The certificate is cached locally and renewed automatically before expiry. No manual certificate provisioning required.

The issuance policy must cover the server hostname — .corp.internal/3 handles acme.corp.internal.

What Each Section Does

Section	Purpose
server	ACME endpoint URL and listen address
tls-certificate-manager	TLS certificate for the ACME HTTPS endpoint itself
dns-validation-profiles	How Certeasy resolves and validates DNS challenges
authorities	Your ADCS backend
issuance-policies	Which DNS names are allowed, key requirements

Startup Checklist

Before starting:

• server.url is set to the hostname ACME clients will use
• ca-name matches your ADCS CA exactly (check with certutil -CA)
• certificate-template exists in ADCS and is configured for ACME enrollment
• The service account has enroll permission on the template
• Work directory is writable

Next Step

Once Certeasy starts successfully, follow the First Certificate guide to issue your first certificate.