simple-acme integration¶

These scripts connect simple-acme to CertIntel. Use all three scripts on each simple-acme host:

Checkin-Wrapper.ps1 replaces wacs.exe as the scheduled-task action and reports every run, including runs where no certificate is due.
Notification-Script.ps1 reports the outcome of each certificate creation or renewal.
Installation-Script.ps1 reports certificate details such as the new and previous thumbprints, validity period, SANs, and storage location.

Together they send the same four requests used by the other ACME client examples:

When	Endpoint	Script
Scheduled run starts	`POST /api/v1/checkins/start`	`Checkin-Wrapper.ps1`
Scheduled run finishes	`POST /api/v1/checkins`	`Checkin-Wrapper.ps1`
Certificate is stored/installed	`POST /api/v1/renewals/enrich`	`Installation-Script.ps1`
Renewal attempt finishes	`POST /api/v1/renewals`	`Notification-Script.ps1`

The installation step runs before the notification step. CertIntel correlates the two requests using the simple-acme renewal id and the reporting device's API key, with the certificate thumbprint as an additional identity.

Prerequisites¶

A working simple-acme installation and at least one configured renewal.
Windows PowerShell 5.1 or a compatible PowerShell executable configured in simple-acme's Script.PowershellExecutablePath setting.
Administrator access to configure the simple-acme renewal and Windows scheduled task.
HTTPS access from the simple-acme host to the CertIntel public API domain.
One unique CertIntel write-scoped API key for this device, tied to the organization these certificates belong to. Enable both the renewals and checkins resources. Authentication is a single header: X-Api-Key: cik_<prefix>.<secret> (the full token is shown once at creation).

Do not reuse a device key on multiple hosts. CertIntel uses the key as the stable device identity; ComputerName is descriptive and may change without splitting history.

1. Copy the scripts¶

Copy all three .ps1 files to a persistent directory on the simple-acme host. Do not put them in a temporary extraction directory that will be removed during an upgrade. For example:

C:\Admin\CertIntel\simple-acme\
├── Checkin-Wrapper.ps1
├── Installation-Script.ps1
└── Notification-Script.ps1

The examples below use that path. Replace it everywhere if you choose another location. Grant read/execute access to the account used by the simple-acme scheduled task. The notification script also needs write access to C:\Admin for its local result/history files, unless you change its $OutputDirectory setting.

2. Configure the wrapper and API credentials¶

Open Checkin-Wrapper.ps1 and set these values:

$WacsExe  = 'C:\Admin\simple-acme\wacs.exe'
$WacsArgs = @('--renew', '--baseuri', 'https://acme-v02.api.letsencrypt.org/')

$ApiBase = 'https://acme-corp.certintel.example/api/v1'
$ApiKey  = 'cik_XXXXXXXX.YYYYYYYYYYYYYYYYYYYYYYYY'   # full write-scoped token

$ApiBase is your tenant's API origin plus /api/v1. The subdomain is the tenant slug you chose when the tenant was provisioned.

$WacsExe and $WacsArgs must match the executable and arguments used by the existing simple-acme scheduled task. Do not add --force to a routine scheduled run.

The values shown in the script are fallbacks. Environment variables take precedence, so credentials may instead be provided by machine configuration or a protected launcher:

$env:CERTINTEL_API_BASE = 'https://acme-corp.certintel.example/api/v1'
$env:CERTINTEL_API_KEY = 'cik_XXXXXXXX.YYYYYYYYYYYYYYYYYYYYYYYY'

The wrapper exports the resolved API base and token before starting wacs.exe. The notification and installation scripts are child processes of simple-acme and inherit those values automatically. This makes Checkin-Wrapper.ps1 the only file that normally needs the real credentials.

Keep the fallback values in the other two scripts synchronized only if users will run wacs.exe directly and bypass the wrapper. Never commit real API secrets to this repository or place them in Task Scheduler command-line arguments.

3. Configure renewal notifications¶

In simple-acme's settings.json, configure Notification.Script with the notification script path and enable success notifications:

{
  "Notification": {
    "Script": {
      "Path": "C:\\Admin\\CertIntel\\simple-acme\\Notification-Script.ps1",
      "Parameters": "-EventType {EventType} -Errors '{Errors}' -RenewalId '{RenewalId}' -FriendlyName '{FriendlyName}' -Log '{Log}' -Thumbprint '{CertThumbprint}'",
      "NotifyOnSuccess": true
    }
  }
}

Merge this fragment into the existing file; do not replace unrelated settings. If a Notification or Script object already exists, update its fields instead of creating a duplicate JSON key.

The parameter string is intentionally formatted this way:

Use named parameters because simple-acme may omit an empty placeholder.
Keep the string placeholders in single quotes. Empty values and paths ending in a backslash can be parsed incorrectly when they are bare or double-quoted.
Keep NotifyOnSuccess set to true; otherwise failures are reported but successful issuances are missing from CertIntel.
{Log} is base64-encoded by simple-acme. The script decodes it before saving and posting it.

The script writes these local troubleshooting files to C:\Admin by default:

LastRenewalResult.json — latest notification result.
<RenewalId>.json — latest result for that renewal id (local reference only).

4. Add the certificate-detail installation step¶

Add Installation-Script.ps1 as an additional installation step for every renewal that should appear with full certificate details in CertIntel. Keep any existing IIS, certificate-store, PFX, or application installation steps.

In simple-acme's interactive renewal editor, choose Add installation step, select Script, and use:

Script:
C:\Admin\CertIntel\simple-acme\Installation-Script.ps1

Parameters:
-CommonName '{CertCommonName}' -Thumbprint '{CertThumbprint}' -OldThumbprint '{OldCertThumbprint}' -StorePath '{StorePath}' -StoreType '{StoreType}' -CacheFile '{CacheFile}' -CachePassword '{CachePassword}' -RenewalId '{RenewalId}'

For a new unattended renewal, the equivalent installation-plugin arguments are:

--installation script --script "C:\Admin\CertIntel\simple-acme\Installation-Script.ps1" --scriptparameters "-CommonName '{CertCommonName}' -Thumbprint '{CertThumbprint}' -OldThumbprint '{OldCertThumbprint}' -StorePath '{StorePath}' -StoreType '{StoreType}' -CacheFile '{CacheFile}' -CachePassword '{CachePassword}' -RenewalId '{RenewalId}'"

Important details:

Preserve the single quotes around every placeholder, especially {OldCertThumbprint}, which is empty on first issuance.
Keep {RenewalId} on both the installation and notification scripts so the pending enrichment row and final outcome become one renewal-history row.
The cache password is used only in memory to open the cached PFX. It is never included in an API payload or written to a log by this script.
CacheFile lets the script read expiry, NotBefore, and SAN data that is not available through the other placeholders.
The script intentionally exits zero if CertIntel is unavailable. Monitoring downtime must not make simple-acme retry an otherwise successful certificate install.

Repeat this step for existing renewals; adding it to one renewal does not automatically update the others.

5. Replace the scheduled-task action¶

Open the simple-acme task in Windows Task Scheduler and note its existing executable and arguments. Put those values in $WacsExe and $WacsArgs in Checkin-Wrapper.ps1, then replace the task action with:

Program/script:
powershell.exe

Add arguments:
-NoProfile -ExecutionPolicy Bypass -File "C:\Admin\CertIntel\simple-acme\Checkin-Wrapper.ps1"

On the task's General tab, enable Run with highest privileges. Keep the task's existing service account, trigger, random delay, and execution limits unless your own deployment requires different values.

The wrapper starts wacs.exe, captures its UTF-8 console output and exit code, posts the completion check-in, and exits with the same code. Task Scheduler's Last Run Result therefore continues to reflect simple-acme's result. A CertIntel API outage is reported as a warning but does not change the simple-acme exit code.

Do not leave a second scheduled action or task running bare wacs.exe; that run would not produce CertIntel check-ins and could renew a certificate before the monitored wrapper sees it.

6. Test the integration¶

Run PowerShell as Administrator and invoke the wrapper manually:

& 'C:\Admin\CertIntel\simple-acme\Checkin-Wrapper.ps1'

If no certificate is due, this is still a successful test. Confirm that the host appears or updates on CertIntel's Reporting Devices page and that the wrapper prints successful start/completion POST messages.

Next, use simple-acme's More options → Test notification menu item. Confirm that the notification script writes C:\Admin\LastRenewalResult.json and that no authentication or connectivity warning appears.

To test the full installation and notification sequence, use a disposable/staging renewal where possible. simple-acme documents --renew --force --verbose for a controlled manual renewal test, but forcing production renewals repeatedly can consume CA rate limits. After an actual issuance, verify:

The run appears on Reporting Devices with the simple-acme exit code and output.
The event appears on ACME Renewals with success/failure status and log.
The certificate has common name, current and previous thumbprints, expiry, NotBefore, SANs, and store information.

Troubleshooting¶

The host does not appear¶

Confirm the task actually runs Checkin-Wrapper.ps1, not wacs.exe.
Verify $ApiBase ends with /api/v1 and uses your tenant's API subdomain.
Verify the key is active and allows the checkins resource.
Run the wrapper interactively as Administrator and inspect its warnings.
Confirm the host can resolve and reach the CertIntel API over HTTPS.

The host appears but no renewal event appears¶

This is normal when no certificate is due. For an actual issuance, verify Notification.Script.NotifyOnSuccess is true, the notification path is correct, and the task account can execute the script and write to its output directory.

A renewal event is missing certificate details¶

Confirm the Script installation plugin is an additional step on that specific renewal.
Compare its parameter string character-for-character with the example above.
Confirm all three scripts resolve to the same API key and renewal URL.
Check simple-acme's log for installation-script invocation messages.
Confirm the cached PFX exists and can be opened by the task account.

The API returns 401 or 403¶

Re-check the X-Api-Key value: it must be the full cik_<prefix>.<secret> token.
Create a new device write key if the token was lost; CertIntel does not show it again.
Make sure the key allows both renewals and checkins.
Do not use a dashboard/browser key for reporting scripts.

The scheduled task reports access or elevation errors¶

Enable Run with highest privileges, verify the task account is an administrator, and confirm it can read wacs.exe, the three scripts, simple-acme's configuration, and the certificate cache.

Updating simple-acme or these scripts¶

After changing the simple-acme installation directory or upgrading to a new versioned folder, update $WacsExe. The integration-script paths remain stable if you keep them in the separate C:\Admin\CertIntel\simple-acme directory suggested above.

When replacing these examples with newer versions, compare the configurable values first and retain your deployment-specific paths, output directory, API URLs, and credential delivery method.

Official simple-acme documentation: