Certificate workflows and deployment¶

For step-by-step modular examples, variables, conditions, and the DNS job timeline, see Agent workflow usage.

The Windows and Linux Agents contain an ACME client. A certificate policy owns the ACME account, names, domain validation (Delegated DNS-01), renewal state, storage destinations, and application installation steps. It also reports check-in and renewal outcomes to CertIntel. You do not need simple-acme, Certbot or Posh-ACME for an agent-managed workflow.

The Agent also has a modular workflow builder for customizing the steps after issuance. That page lists every bundled template field and every supported action input. New Windows workflows use the template library and Workflow studio. Existing storage/installation plans remain supported and are documented below. On Linux the terminal interface (sudo certintel tui) has its own guided wizard (a on the Workflows page; N before Agent 1.3.88) since Agent 1.3.77; the CLI's configuration transaction remains available for scripted setups.

A certificate is issued either through ACME (the default) or, since Agent 1.3.81, by the tenant's CertIntel Private CA for internal names that no public CA can validate. The issuance, storage, installation, renewal and reporting paths are the same for both; the Private CA specifics are on the Private CA page.

Private keys are generated and retained locally. They are never returned by the local management API or included in CertIntel reporting.

Create a workflow¶

Open Workflows → + New certificate workflow:

1. Choose and configure an application template, Start from scratch, or Import workflow… from a reusable JSON definition.
2. Use Workflow studio to edit shared settings, arrange steps, and review the definition. Choose Continue to certificate setup and supply protected secrets.
3. Complete Names & authority: display name, DNS names, the issuer (an ACME account and CA with profile and agreement to its terms, or - when the platform offers it to this Agent - CertIntel Private CA (internal names, no DNS validation) with the CA, validity and IP addresses), the key type and the Request the first name as the subject common name (CN) box (checked by default; see omit_common_name below).
4. Complete DNS validation with a delegation for each exact base domain. A Private CA certificate skips this step.
5. Check Review & create, then choose Create & issue.

The illustrated workflow guide shows the template library and three-stage certificate setup. A template's destination and service settings are entered before certificate setup, so the modular path does not ask for a second storage/installation plan.

Creating a certificate is an administrator change: Windows asks for administrator approval and lists the new names, account and delegation before saving. A long approval continues across up to five dialogs; only a request that still does not fit is refused with too many security-sensitive changes to review safely at once, in which case split the configuration change.

For a saved certificate, choose Edit workflow… to manage its account, DNS delegations, automatic renewal, application steps, and protected secrets. Edit workflow settings and steps… opens its studio. Certificates using older plans show Legacy storage / installation steps and Choose modular template…. History… shows the certificate's creation, issuance, installation and renewal-check events.

New ACME accounts have a name chosen by the administrator, a contact email and a directory URL. Existing accounts appear by that name for reuse. Let's Encrypt supports Default, TLS Server and Short-Lived profiles when the CA advertises them; custom ACME directories do not show Let's Encrypt-only profiles. Choose ZeroSSL, SSL.com ECC/RSA, Actalis, Google Trust Services production/staging, or (Agent 1.4.0 and later) DigiCert US/EU/Japan, Sectigo DV/OV or GlobalSign Atlas EMEA directly from the authority dropdown. Setup asks for the EAB KID and masked EAB HMAC Key for these providers; custom directories also support EAB. See ACME providers and EAB setup for credentials, endpoints, and Google's project requirements. Keys can also be rotated from Edit workflow….

The wizard creates a disabled draft first, saves EAB/DNS/output secrets through the protected service API, restores the selected automatic-renewal setting, then queues issuance. If a later step fails, the draft remains available rather than losing already entered configuration.

Click Auto-renew in the certificate table to enable or pause scheduled renewal. The Enabled checkboxes in TLS probe, file, and Windows store monitor tables also save immediately (after administrator approval). In the AD CS template dialog, checkbox changes remain in the draft until Apply; Cancel discards them.

Certificate and account parameters¶

The wizard and local configuration use these names. id is a stable renewal ID; the desktop wizard generates it. An asterisk marks a required value for the relevant object.

The wizard selects Let's Encrypt production and RSA 2048 by default; select staging when testing a new setup. ACME accounts may also use a custom directory. For Let's Encrypt, profile is empty (or classic) for Default, or tlsserver or shortlived when advertised; the TLS Server and Short-Lived profiles accept at most 25 names, and a certificate can carry 1 to 100 names. A requested preferred_chain must be offered by the CA. The CA must validate each requested DNS name through its configured delegation.

Identity fields do not change in place¶

The renewal ID, names, ACME account, key type and CA policy are treated as the workflow's issuance identity and cannot be edited after creation. The directory of an existing ACME account is also locked. Changing these values underneath an existing order can invalidate persisted state or violate replacement policy.

Create a new workflow when you need a different CA, account, domain set, key type or profile. Display names, account labels/contact details, automatic renewal and storage/installation plans can be updated without changing issuance identity.

Workflow actions¶

On Windows, each of these except History… asks for administrator approval and shows the approval dialog naming the certificate before it runs.

The Workflows table shows issuance status, expiration, Renewal due, installation status and Auto-renew. Queued and recent operations appear in the activity popup and on Jobs. The popup shows only the requested job/workflow and starts at the top of its log. New entries preserve your scroll position and text selection. Enable Follow latest activity to scroll with arriving entries; it is off by default.

Install again runs the saved installation from the beginning with the current certificate. It can repeat custom programs, backups, and service actions; it is not limited to the last failed step. Saving a studio edit alone does not install anything. An older plan's edit dialog may separately offer Save and install again. Installation failure does not mean ACME issuance failed, and a retry does not create another DNS challenge or order.

The service wakes for each certificate's renewal date, retry delay, revocation follow-up and (Agent 1.4.0 and later) next check of the CA's renewal window on its own (see when a certificate renews), and otherwise evaluates every certificate on the Renewal check interval (twice a day by default, Settings → Schedules); with renewal windows configured, that scheduled check runs at a random time inside each window instead. After a managed certificate is installed, the agent re-probes any local TLS monitors it covers; see post-install re-check.

Replaced certificates in Windows stores¶

The standard Windows store and IIS workflows end with a Remove previous certificate from Windows store step. After confirming that the replacement is installed, valid and has a usable private key, the step removes the renewal's recorded predecessor only when you have turned on Remove previous certificate after confirmation (off by default) and the Agent can show that nothing it can inspect still uses it: no IIS HTTPS binding, HTTP.sys SSL binding or Remote Desktop listener. The machine-store template additionally needs No other application uses the previous certificate, because it can only confirm the store contents; the IIS template's own post-binding endpoint check is enough. Otherwise the certificate is kept and the job says why (retained: true). Private keys are never deleted.

A separate Superseded Windows store certificates schedule can purge predecessors later under a retention policy instead. Both are described in Windows store verification. Agents 1.3.55 through 1.3.69 never removed previous certificates; removal returned in 1.3.70.

When a certificate renews¶

Since Agent 1.4.0 an ACME certificate follows the renewal window its certificate authority suggests through ACME Renewal Information (ARI, RFC 9773), when the CA offers it:

• Planned time. Inside its renewal pass the Agent asks the CA for the certificate's renewal window and picks a random time inside it. It keeps that time and picks again only when the CA changes the window.
• Checking again. The next check follows the CA's Retry-After, kept between 1 and 24 hours (6 hours when the CA gives none). A failed check is retried after 6 hours and shown as an error; until a check succeeds the lifetime schedule applies. A CA that does not offer ARI is asked again every 24 hours and is not shown as an error.
• Lifetime schedule. Without an ARI window, a certificate renews at a point between one half and two thirds of its lifetime, as before.
• Early renewal. When the CA reports a window that has already ended, or moves the window earlier so that the new time is already due - for example ahead of a mass revocation - the certificate renews on the next pass, even outside the Agent's renewal windows. A deployment window still applies to installing it, with its expiry override. A planned time that merely passes while the Agent waits for its own renewal window is not treated as urgent.
• Floor. A certificate is never renewed sooner than one hour after its validity starts, so a CA that keeps answering with a past window cannot cause a renewal loop.
• Replacement. New orders tell an ARI-capable CA which certificate they replace (replaces).

Private CA certificates do not use ARI; they renew on their renew_before_days setting.

The basis (ARI or certificate lifetime), the CA's window, the planned time, the next check and the last error appear in the desktop app's Renewal due tooltip and renewal tables, in the terminal interface's certificate detail (for example ARI window 12-20 → 12-24 · next check ...), in status --json, and in the certificate's Renewal schedule in CertIntel.

Renewal windows¶

Settings → Renewal windows can limit unattended renewal and automatic installation retries to one or more weekly windows. Times use the agent machine's local time zone. An end earlier than the start creates an overnight window; for example, Tuesday 22:00 to 02:00 closes Wednesday at 2 AM.

No configured window means unrestricted operation. Windows apply to automatic renewal and automatic/retry delivery. First issuance and actions explicitly started by an administrator, including Renew now and Install again, run immediately as deliberate overrides. The Renewal due column and History… show when a renewal is waiting for a window. An urgent ARI renewal (see above) does not wait for a renewal window.

When a certificate has a deployment window, its renewal windows gate only issuance: installation follows the deployment window instead, even while the renewal windows are closed.

Deployment windows¶

Since Agent 1.4.0 a deployment window limits when a renewed certificate is installed - for example only on weekend nights - while the certificate is still issued as soon as it is due. Set an Agent default and, where a workflow needs a different window, a window on the workflow, which replaces the default. Plan-based (legacy) certificates use the Agent default.

A window is a set of weekdays, a start and an end time (HH:MM, 24-hour), an IANA time zone such as Europe/London or America/New_York, and an expiry margin:

"deployment_window": {
  "days": ["saturday", "sunday"],
  "start": "22:00",
  "end": "04:00",
  "timezone": "Europe/London",
  "expiry_margin_hours": 72
}

• Days are lowercase English weekday names. An end earlier than the start runs overnight and belongs to its start day: the example opens on Saturday and Sunday at 22:00 and closes at 04:00 the next morning.
• The time zone is required and must be an IANA name; Local and an empty value are refused. The Agent carries its own time zone data, so a window follows daylight saving time the same way on every machine.
• expiry_margin_hours is 1–720 and defaults to 72.

What waits and what does not:

Expiry override. When the certificate currently installed would expire before the next opening plus the margin, the renewed certificate is installed at once instead. The Agent writes the reason to its activity log and adds deployment_window_override (the window opening, the installed certificate's expiry and the margin) to the renewal it reports; CertIntel raises the Deployment window overridden alert (deployment.window_override, see Alerts). When the installed certificate's expiry is unknown, the Agent waits for the window.

Where to set it:

• Windows - the Agent default under Settings → Deployment window (Set window…, Remove); a workflow's own window under Edit workflow… (Set deployment window…, Use the agent default deployment window).
• Linux - the Agent default on the terminal interface's Settings screen (Agent default deployment window, d removes it); a workflow's own window with W on the Workflows screen. Clearing every weekday removes a window.
• Configuration - top-level deployment_window and workflows[].deployment_window.
• CertIntel - a dashboard assignment can carry a window for the workflow it creates.

A waiting installation shows as Waiting for deployment window in the desktop app, as renewed certificate waits for the workflow's deployment window · installs ... in the terminal interface, as phase deferred with deferred_until and window_source under deliveries in status --json, and under Deferred deployments on the Agent's host detail in CertIntel.

A configuration that uses deployment windows does not load on Agents before 1.4.0.

Storage destinations¶

The formats below are available through certificate export/store actions or compatible deployment plans. For modular setup use the template and action reference; the deployments[] fields later in this section describe the plan format.

A certificate can have multiple storage/installation plans, except a JKS CSR workflow, which uses one dedicated JKS plan because its private key remains inside that keystore.

File outputs use stable names and atomic replacement. Keep previous files can place changed files in a separate backup directory with timestamped names.

For CLI configuration, a plan is a deployments[] entry with id, outputs[] and ordered installations[]. A generation-style plan uses an absolute directory instead of outputs and cannot have installation steps. A plan supports up to 16 outputs and 32 installation steps. Each outputs[] item has:

Private output passwords are never placed in that JSON. The CLI command certintel secret set output PLAN-ID:OUTPUT-ID stores or replaces one through a hidden prompt (or --stdin for automation). A new protected output can receive a generated password, as described below.

Private-key files are always encrypted. The wizard accepts a password when another application must know it. If no password is supplied for a new protected output, the service generates a strong random password directly into encrypted storage and never exposes it. Use a supplied password for software that must open the PFX, encrypted PEM/KEY or JKS itself. Public .cer, .crt and .p7b outputs do not contain a private key.

Existing application/backup directories and unrelated files retain their permissions. Export does not replace a directory ACL or change an existing directory's Linux mode. Atomic replacement preserves the selected file's Windows DACL or Linux mode/ownership; configured Windows reader grants apply to selected output files. New directories use restrictive defaults. Ensure the Agent can write the destination and the application can read the resulting certificate; an application-owned folder is supported when the path passes the Agent's checks.

Java keystores¶

The modular Java KeyStore and Tomcat + JKS templates import the Agent's issued certificate and Agent-owned private key using keystore.jks.write. They do not create the private key inside the destination JKS. For Tomcat using PKCS#12 instead, see the P12 example.

When the key and CSR must originate inside the JKS, use a compatible JKS CSR deployment plan. Existing plans remain editable in Edit workflow… → Legacy storage / installation steps, where Add plan… also creates a new plan for a certificate that still uses plans; plans can also be provisioned through the local CLI. For that plan, select:

• the exact absolute .jks path;
• the Java runtime's absolute keytool.exe path;
• a simple alias;
• the keystore/key password; and
• optional read access accounts for the JKS file.

The containing directory must already exist and retains its current directory permissions. If the JKS already exists, enter its current password. If the alias does not exist, keytool creates a keypair and CSR in that alias. The CA reply is then imported back into the same alias. Temporary CSR/reply/import files are deleted after use.

Optionally select Restart a Windows service after installing the certificate. The picker shows installed service display names and stores the exact service name, so the correct instance can be selected when several Tomcat services exist. The restart runs only after a successful import. If import succeeds but restart fails, Install again recognizes the certificate already in the JKS and proceeds to the restart rather than treating the duplicate import as a new failure.

Installation options¶

These are the compatible plan-based installations[] options. Modular workflows use explicit actions instead. For example, add a process.execute configuration test before service.reload if your custom NGINX/Apache workflow requires one; the modular service template does not implicitly perform every legacy installation check.

• IIS imports into WebHosting by default and creates or updates one selected HTTPS site binding. For a plan-based installation SNI is off by default (the IIS HTTPS binding template turns it on from Agent 1.3.93); Central Certificate Store requires SNI and enables it automatically. Unrelated sites and bindings are preserved, and Agent 1.3.93 and later refuse a non-SNI binding on an address and port that another site or HTTP.sys application already serves unless replace_shared_binding is set - see SNI.
• NGINX writes PEM files, tests the selected configuration and requests a graceful reload only after the check succeeds.
• Apache writes PEM files, tests the selected configuration and reloads or restarts the configured server/service.
• Tomcat writes a protected PFX and restarts the selected Windows service.
• JKS can restart the selected Windows service as described above.
• Certificate File can run an administrator-selected absolute .exe or .ps1 with a bounded timeout after files are written. Its output is not kept in the job result or the Agent's state. Since Agent 1.4.0, when the program fails, the redacted end of its combined output is sent with the failure report; see Reporting failed step output.

Installation failure retains the issued certificate and records a retryable delivery failure. It also reports a failed renewal event to CertIntel for attention and alerting, including (Agent 1.4.0 and later) the failed step, its exit code and the redacted end of its output. It does not trigger another CA order.

Reporting failed step output¶

When an installation step fails, Agent 1.4.0 and later report which step failed, its action and exit code, and the last 8 KiB of its output, so the failure is visible in CertIntel and in the renewal.failure alert without signing in to the machine:

Before the output leaves the machine, the Agent replaces with [redacted] every secret it knows of: the workflow's ${secrets.*} values, the resolved values of protected step inputs (including passwords and environment values typed into the workflow), the platform API key, EAB HMAC keys, DNS delegation secrets and legacy PFX/JKS/PEM passwords, each also in its base64 forms; then text that looks like a credential. Redaction runs before the output is cut to 8 KiB, so a secret on the cut cannot leak in part.

Redaction is best effort. A program that transforms a secret before printing it - encoding, splitting or reformatting it - is not caught, and a value shorter than four bytes is not replaced. Keep scripts from printing secrets, and turn reporting off where output may still contain them:

• for the whole Agent: Settings → Deployment window → Report the redacted end of a failed step's output to CertIntel on Windows, Report failed step output on the terminal interface's Settings screen, or "report_step_output": false at the top level of the configuration;
• for one workflow: "report_step_output": false on the workflow in the configuration. The desktop app and terminal interface have no control for the per-workflow setting yet.

With reporting off, the failure still names the step, its action and exit code, without output. The raw output is never stored in the Agent's state or shown by status. CertIntel shows the output in the renewal's Failed step output section; see Alerts for what each alert destination shows.

Each installations[] item accepts kind and the fields below. The compatible plan editor fills them for the selected application; direct CLI proposals must use these exact names. All timeouts are 1–600 seconds.

The script argument placeholders are {CertThumbprint}, {CertCommonName}, {RenewalId}, {StorePath}, and {Generation}. Passwords and private keys are never expanded into arguments. The modular process action uses a different, structured environment field for protected secrets.

Edit or delete a workflow¶

Use Edit workflow… to edit the display name/renewal preference, account label and contact data, DNS delegation credentials, protected secrets, and application steps. Modular steps open in Workflow studio. Compatible plans can be added, edited or removed without losing the issued certificate. Updating an issued plan queues installation of the current certificate.

Delete renewal… opens the Delete certificate lifecycle confirmation. It removes the renewal and its now-unused ACME account, DNS credentials, plans, archive passwords and protected agent certificate state. Installed certificates and exported files are retained, and the certificate is not revoked. A delegation with a challenge still pending cleanup blocks deletion until the cleanup finishes.

CLI equivalents¶

The desktop app (Windows) and terminal interface (Linux) are the normal setup experience. Useful elevated CLI operations include:

certintel acme accounts --json
certintel acme orders --json
certintel certificates issue CERTIFICATE-ID        # issuer-agnostic Issue / replace (1.3.81+)
certintel certificates renew CERTIFICATE-ID        # renews when due
certintel certificates force-renew CERTIFICATE-ID  # renew early
certintel certificates revoke CERTIFICATE-ID       # ACME only
certintel acme issue CERTIFICATE-ID                # ACME-specific forms, still supported
certintel acme renew CERTIFICATE-ID
certintel acme force-renew CERTIFICATE-ID
certintel acme revoke CERTIFICATE-ID
certintel private-ca list                          # Private CA availability and usable CAs
certintel private-ca refresh
certintel private-ca trust CA-ID                   # install the CA root into the machine trust store
certintel deployments retry CERTIFICATE-ID
certintel jobs get JOB-ID --json
certintel workflows create --template ID --certificate-id ID --domains NAMES [...]   # 1.3.93+: certificate + workflow from a template
                                                   # 1.5.0+ Private CA: --private-ca-profile server|client|both, --ip-addresses (alias --ip; --domains optional)
certintel secret set remote WORKFLOW-ID:NAME       # 1.5.0+: appliance credential (username:password or the API token)
certintel secret rotate-sealing-key                # 1.5.0+: replace the platform-credential sealing key (administrator)
certintel hooks starter KIND [--write]             # 1.5.0+, Linux: print or (root) write a service starter hook
certintel private-ca accept-rotation CERTIFICATE-ID   # 1.5.0+: follow a rotated CA under a new root
certintel lock [--reason TEXT]                     # 1.4.0+: configuration lock on (administrator or root)
certintel lock status
certintel unlock

workflows create has no option for a deployment window yet; add it to the created entries with config apply --file. The configuration lock is described on the Windows and Linux Agent pages.

The certificates … and acme … forms queue the same service jobs; the ID is the certificate's id from the configuration (shown in the Windows app and the TUI).

Queueing succeeds before the operation necessarily finishes; use the returned job ID, Jobs, Activity, or status --json for the final result.