Workflow Assignments¶

A workflow issues a certificate and installs it where it is used. On Workflow Assignments in the CertIntel dashboard you create one with New workflow: pick the Agent that runs it, choose one of that Agent's bundled templates, fill in its fields, and name the certificate and its issuer. The Agent fetches the proposal and checks it exactly as it checks a workflow created on the device. A server that applies its organization's proposals by itself (the default of a new installation) then carries it out; any other waits for a local administrator to approve it in the desktop app, the Linux terminal interface or with certintel assignments approve. Only then does it create the certificate and workflow, issue and install the certificate, and report each step back; the dashboard shows the timeline. Other pages call these dashboard-assigned workflows.

The rule is the platform proposes; the Agent decides. Nothing is applied on a device without a local approval or a local auto-apply policy on that device (on by default for a new installation; only the device can change it). The dashboard cannot set that policy, cannot add steps, scripts, paths or secrets, cannot change the Agent's platform connection, and cannot remove a workflow once it exists. This is the same shape as a Private CA offered to an Agent: the platform makes something available, the Agent accepts it locally.

For a first certificate on one server, Get a certificate for a server on the dashboard's Overview builds the proposal for you: it creates the organization's ACME account (Let's Encrypt) and the DNS-01 records, checks the CNAME before proposing, and then shows what happens on the server, step by step: for a server that applies proposals by itself there is nothing to approve, for any other the first step is the command that approves the proposal there. When the Agent reported a detected server that listens on port 443, the page starts from it. Approve on that page keeps following the server you approved; while another server is still being set up, the page asks which server to use instead of picking one. What it creates is a workflow like any other: it is listed, edited and renewed on Workflow Assignments. See IIS quick start and Get a certificate from the dashboard.

The list¶

Workflow Assignments (/workflow-assignments) is one list of every workflow the dashboard knows. A workflow is one row, whatever the number of Agents that may run it and of proposals made for it.

Above the list, the filters narrow it; they add up, and the count beside Workflows reads 2 of 14 while one is set:

Agent, Template and Issuer offer what the listed workflows name, and each appears once there is more than one to choose from. Clear shows every workflow again.

Rows that wait for someone come first: awaiting approval, then waiting for the Agent, applying, failed, not taken by any Agent, rejected, applied, cancelled and expired. A row offers Renew now once its workflow is applied.

A workflow created through the API is a row like any other. The proposals a deleted workflow left behind stay on the list as rows of their own; selecting one opens its details and timeline in a pop-out instead of a page.

Creating a workflow¶

A workflow is created in one place: New workflow on Workflow Assignments (/workflows/new; /workflows/new?agents=<id>&agents=<id> opens the form with those Agents ticked). It needs workflow_assignments.create and agents.read in the Agent's organization. The API creates the same workflows.

1. Where it runs. The page lists every Agent you can propose workflows to, with its version, when it was last seen and whether it can run workflows: ready, or the reason it cannot be ticked. Tick the Agent that runs the workflow, usually the server the certificate is for, and choose Continue. For a target several Agents can reach, tick each of them (see One Agent or several).

   Reason	Meaning
   Waiting for the agent's first heartbeat.	The device has not reported yet.
   Agent too old: update it to 1.3.95 or later for dashboard-assigned workflows.	An earlier release, or a client that is not the CertIntel Agent.
   Waiting for the agent's capabilities report; it is sent within minutes of approval.	The Agent has not sent its template list yet.
   A local administrator turned on the configuration lock on this device: it applies no workflow from the dashboard until the lock is removed there.	The Agent's configuration lock is on.

   An Agent whose key is pending approval, disabled or unregistered cannot be ticked either. An Auto flag marks an Agent with auto-apply on: the page warns that the device applies what you propose without a local approval.

2. Give the workflow a Name (how the list shows it; the certificate's name or id when left empty) and choose a template. The list is built from what the Agent really has: its bundled templates, their versions and fields, the ACME accounts configured on it and, on a Windows host with IIS, the IIS sites. Secret-typed fields (such as a keystore password) are not offered; the Agent generates them, as it does for a workflow created on the device. See bundled template setup fields for what each template asks. A file name, keystore name, alias or folder field shows the rule its value must follow and is checked as you type; a value the Agent would refuse is refused when you create the workflow (see Setting rules). With one Agent ticked that reported the servers it detected, a Detected on this server chooser sits above the form: pick a server and choose Fill the form to put its template, names and settings into the form, replacing what is there (see Detected servers).

3. Fill in the certificate: its id (see Certificate ids), display name, DNS names (the first becomes the subject common name), key type and automatic renewal, and the issuer - either a CertIntel Private CA the Agent may already use (see enabling a Private CA for an Agent) or an ACME account the Agent reported. The organization's Let's Encrypt (production) account is selected by default. When there is no issuer at all, the form offers Add the organization's ACME account (Let's Encrypt), which opens Settings → ACME Accounts and comes back to the form after Add account and go back. An ACME account that uses one of the Agent's CA presets is listed as ACME: <account name> (<preset name>). The organization's own ACME accounts are listed as ACME (organization): <name> (<CA>) (see Organization ACME accounts). An ACME certificate needs a DNS-01 delegation for each base domain of its names. The form's DNS-01 validation section lists each base domain with its choice: the Agent's own delegation, one of the organization's Delegated DNS-01 records, or a new record, created at once with Create record now (which shows the CNAME to publish) or by the proposal itself. The Agent gets its own credential for an organization record when it approves the workflow, so publish every CNAME before that. Picking or creating the organization's records needs a role that may see (and, for a new record, create) Delegated DNS-01 records. A name covered by neither is refused (The agent has no DNS-01 delegation for '…'; pick or create one under DNS-01 validation.), and the Agent itself rejects with no delegation for certificate … if its own delegations changed in between. DNS-01 is the only validation method (see HTTP-01 was removed). A Private CA certificate can also set the validity, IP addresses and the Certificate profile; see Private CA certificates. Names are stored the way the Agent will request them - trimmed, lower-case and without a trailing dot - so WWW.Example.com. appears as www.example.com; a whole-number field takes a value between −2147483648 and 2147483647.
4. Issue now (ticked by default) issues and installs the certificate while the workflow is approved and reports the result. Unticked, the Agent still issues it at its next renewal check, about a minute after approval, and the workflow shows Applied before that; it does not wait for the renewal schedule. So publish the DNS-01 CNAME before the approval either way. Add a note for the person who will approve it on the device (ticket number, purpose); the note is shown there. A proposal expires after 30 days by default (1–90) if nobody approves it.
5. Create workflow. You land on the workflow's page, and the confirmation tells you when the Agent will see the proposal: the Agent checks for assignments every 5 minutes, and within a minute for 15 minutes after approval; run certintel assignments refresh on the device or restart its service to check now.

A workflow the Agent could not run is refused when you create it: the form says why, nothing is proposed and your entries are kept.

The form has no renewal date to set, and says when the certificate renews. For an ACME issuer the certificate authority decides: when it offers ACME Renewal Information (ARI), the Agent renews at a random time inside the window the CA suggests and checks that window again when the CA asks. Without ARI the Agent renews between one half and two thirds of the lifetime. A Private CA certificate renews between one half and two thirds of its validity. In every case the Agent's own renewal windows still apply, except to a renewal the CA asks for early. See when a certificate renews.

CAA records¶

A certificate authority refuses to issue for a name whose CAA records (RFC 8659) do not name it. With an ACME account picked and names typed, the form's DNS-01 section offers Check CAA (it also runs when the names or the issuer change): for each name it says whether the CAA records allow that CA, which records decide (the name's own, a parent's, or the target of its CNAME), and when they do not, the exact record to add, for example example.com. CAA 0 issue "letsencrypt.org", with a Copy button. A wildcard name follows issuewild when the domain has one. A record that allows the CA only for other validation methods (validationmethods without dns-01) is refused, with the changed record; one limited to an ACME account (accounturi) or with a parameter CertIntel does not know says CAA: check, because CertIntel cannot compare it. An account on an ACME directory CertIntel does not know cannot be checked. IP addresses and internal names are not applicable. CertIntel asks public DNS resolvers; the CA checks again when it issues.

The check never stops a proposal (the CA decides): when CAA would refuse, the confirmation after Create workflow is a warning with the record to add. The details pop-out of a proposal shows the same check under CAA records for <CA>. The same check is on the Delegated DNS-01 pages, Public Endpoints and the API (GET /api/v1/caa-check). The issuer name each CA preset needs is listed under ACME providers.

One Agent or several¶

Most workflows run on one Agent: the server the certificate is for. Its proposal waits for that Agent until someone approves or rejects it there, or until it expires. It also waits while the Agent is offline, so a server that comes back finds its workflow.

Some targets belong to no one Agent: a firewall, a VPN concentrator, a load balancer or another network appliance that several Agents can reach. For such a target, tick every Agent that is allowed to run the workflow, up to 20, all of one organization. Network reachability decides which Agents those are, so leave out the ones that must not touch the target.

• The Agents are offered the workflow in the order the form lists them. After Use these agents, a number next to each tick shows the order.
• The form offers only what every ticked Agent reports: the templates they all carry in the same version, the issuers they share and the optional fields all of them support. IIS sites are offered only when one Agent is ticked. Agents with no template in common cannot share a workflow (The agents you picked carry no template in common (same template and version); update them to the same agent release, or pick fewer.).
• Every ticked Agent must be able to run the workflow when you create it. Otherwise it is refused with Every agent you pick must be able to run the workflow. and each Agent's reason.
• The platform offers the workflow to one Agent at a time, so two Agents never apply the same workflow. It moves on to the next Agent when the current one rejects it, fails it before applying it, lets it expire or does not fetch it within an hour. It also moves on when that Agent's key is disabled, deleted or unregistered, and when you choose Offer to the next agent. An Agent that cannot take the workflow at that moment is skipped, with the reason in the workflow's timeline.
• The Agent that applies the workflow runs and renews it from then on.
• When every Agent was tried, the workflow reads No eligible agent took it until you start a new round or edit it.

A workflow's page¶

Selecting a workflow on the list opens its page (/workflows/<id>; /workflows itself opens the list). It opens with one sentence on where the workflow stands (Runs on web01, which renews it.), then the certificate, its names and issuer, the Agent and the settings, one per line. A workflow that several Agents may run lists them under Eligible agents. Below are every proposal made for it (Offers) and the workflow's timeline.

DNS-01 records to publish is a section of the summary: the CNAME of each record the workflow uses, with Copy buttons. It is open while a proposal waits, when the records are needed, and folded once an Agent runs the workflow; select its heading to open it.

The heading shows where the workflow stands:

The actions depend on that and on the number of Agents:

While the Agent is applying a proposal, the workflow cannot be edited, cancelled or moved; wait until it has finished. The same actions are in the API.

Under Offers, each proposal made to an Agent is a card, newest first: the Agent, the proposal's state, revision, template and issuer on its first line, then the Agent's last report and reason, the command that approves it on the device and its own timeline. The proposal that is out and the one the Agent runs are open; earlier ones are folded to their first line, which you select to open them. A proposal made with the names and settings the workflow has now does not repeat them; one made with others, before an edit, lists its own. A card of a certificate whose issuance, renewal or installation is not settled has a Next attempt line: when the Agent tries again by itself, or that it stopped (see When the Agent tries again). While a proposal waits you can Re-send it (the Agent checks it afresh and asks the local administrator again) or Cancel it; cancelling a proposal offers the workflow to the next Agent, or leaves it as No eligible agent took it when there is none. A finished proposal can be deleted; its workflow stays. A proposal the Agent rejected is sent again from the workflow's page (Send again, or a new round with several Agents), not from its card.

A proposal that is sent again gets its full time to live from now, and it must pass what a new proposal passes: room on the Agent, no other live proposal for that certificate id, the certificate id not created on the device since, and the template version still reported. The timeline keeps the earlier refusal.

Once an Agent has applied a workflow, retiring the workflow or its certificate is a local action on the device. Disabling, deleting or unregistering an Agent's key cancels its waiting proposals; rotating the key keeps them.

Opening the list and a workflow's page needs workflow_assignments.read. Creating a workflow needs workflow_assignments.create in the Agent's organization plus agents.read. Editing, sending again, moving and cancelling need workflow_assignments.update, deleting needs workflow_assignments.delete, and Renew now needs agents.update. The built-in Administrator and Operator roles can create, edit and cancel; only Administrators delete; Auditors can read; custom roles can grant each action. See permissions. The timeline records who created, edited, re-sent or cancelled a workflow; that identity is never sent to the device.

Editing a workflow¶

Edit on a workflow's page (/workflows/<id>/edit) changes its name, the Agents that may run it and their order, and the workflow itself: template settings, names, key type, issuer, deployment window, DNS-01 records, note and expiry. The certificate id cannot change, because it names the certificate on the Agents; create a new workflow for another certificate. Every Agent on the list must be able to run the edited workflow, as when it was created. An Agent that cannot run workflows at the moment is left unticked, and saving takes it off the list.

What saving does depends on where the workflow is:

• Offered to an Agent, not yet approved: the proposal is sent again with the edit. If you took that Agent off the list, the next Agent gets it.
• No eligible agent took it: the edited workflow is offered again, from the first Agent.
• Running on an Agent: the edit goes to that Agent as a proposal to replace the certificate it already has. This needs Agent 1.8.2 or later on that Agent. Its local administrator approves the edit, or the Agent's auto-apply policy does, like any proposal. The Agent then changes the certificate's issuer, names and workflow in place, under the same certificate id. Until then, or if the edit is rejected, the Agent keeps running the current workflow, and the list shows an edit … pill next to the state. Leave Issue now ticked when you change the issuer, for example when a certificate authority is no longer trusted, so the Agent replaces the certificate at once instead of at its next renewal. If you change only the note, Issue now or the expiry, nothing is sent.

Without Agent 1.8.2 on the Agent that runs the workflow, the edit page says Requires Agent 1.8.2, and only the name, the Agents, the note, Issue now and the expiry can change.

An Agent replaces only a certificate that a dashboard assignment of the same organization created on it. It refuses to replace a certificate created on the device. The Agent that runs the workflow must stay ticked; to take it off the list, move the workflow to another Agent first.

Removing a workflow from the Agent¶

(Agent 1.19.0+) When you cancel or delete a workflow that an Agent runs, Also remove it from the agent is ticked. The Agent that runs the workflow then gets a proposal to remove it. Its local administrator approves it, or the Agent's auto-apply policy does, like any proposal.

Approved, the Agent does what Delete renewal does on its Workflows page (see Workflows): renewal stops, and the certificate's workflow and the Agent's state for it are deleted. The installed certificate stays. Its bindings (IIS, Remote Desktop, LDAPS, NPS and the rest) and exported files are left as they are, and nothing is revoked, so the server keeps using the certificate until it expires or another workflow replaces it.

The workflow's page then says Removed from on ; the installed certificate stays until it expires. If the removal is rejected, fails or expires, it says keeps the workflow: and the reason, with Remove from the agent to ask again. A removal that is still waiting does not stop you from deleting the workflow: the removal stays on the list as a row of its own.

The Agent refuses a removal, and the reason is shown, when:

• the certificate is not configured on it (there is nothing to remove);
• no dashboard workflow of the same organization created the certificate. A certificate created on the device can only be removed on the device;
• the certificate's workflow also serves another certificate.

On the device the proposal reads Removes certificate X and its workflow W from this agent. Renewal stops. The installed certificate, its bindings and exported files stay; the certificate is not revoked.

An Agent older than 1.19.0 cannot remove a workflow this way. The box is then unticked and cannot be ticked, and the Agent keeps the workflow until a local administrator removes it there with Delete renewal.

An Agent's workflows¶

The Agents page creates no workflows. The row menu (⋯) of a ready Agent has Workflows, which opens Workflow assignments for <device>: every proposal made to that Agent, newest first, each with its state, timeline and actions, and a line that says whether the device applies proposals without a local approval. New workflow for this agent on that page opens the workflow form with the Agent ticked.

While the Agent's configuration lock is on, the button is replaced by New workflows are disabled while the agent reports its configuration lock as on. Until an approved Agent is ready, its row menu says why instead of Workflows: Workflows can be assigned after the agent's first heartbeat, Agent too old for dashboard-assigned workflows: update it to 1.3.95 or later. or Waiting for the agent's capabilities report before workflows can be assigned.

Workflows and the page behind it need agents.read and workflow_assignments.read in the Agent's own organization; a grant in another organization does not open them.

Detected servers¶

An Agent reports the servers on its computer that use a certificate (see Server detection). The dashboard lists them under Detected on this server, in the Agent's detail pop-out on the Agents page and on its workflows page, with the time detection ran:

• Create workflow opens the workflow form with the Agent ticked and the template, names and settings filled in from the detected server. Check every value: nothing is proposed until you create the workflow. The link needs workflow_assignments.create and an Agent that can take a new workflow now, and a server marked covered, on the agent or left behind has none.
• on the agent means a workflow that was created on the Agent itself, in the CertIntel Agent app on Windows or with sudo certintel tui on Linux, already renews the certificate the server uses. The row names that workflow's certificate ID. CertIntel holds no workflow for it, so it cannot be changed from the dashboard, and a second workflow created here would manage the same server twice. To change it, edit it on the Agent. To manage it from CertIntel instead, remove it on the Agent and then use Create workflow, which is offered again once the Agent has reported the removal. CertIntel recognises such a server by its certificate: the certificate the server uses is one the Agent reports managing, under an ID that no dashboard workflow of this Agent holds. A server whose certificate detection could not read is not recognised this way.
• left behind (Agent 1.19.0+) means the workflow that renews the server's certificate was created in CertIntel, but that workflow was cancelled or deleted here, for example before removal from the Agent existed, or with Also remove it from the agent unticked. The row reads Left behind by the workflow , cancelled in CertIntel (or deleted). Remove from the agent asks the Agent to remove it, as described in Removing a workflow from the Agent; it needs workflow_assignments.delete. While the removal waits the row reads Removal sent; waiting for the agent. Create workflow is offered again once the Agent has reported the removal.
• For an NGINX or Apache httpd server on Linux (Agent 1.14.0+), the settings include the certificate file the server reads now. The form says so above the settings: the Agent will replace that file and its key file, and the server's configuration needs no change. Clear the setting to leave the server's files alone. See Replacing the files the server already reads.
• On the workflow form, with one Agent ticked, the Detected on this server chooser fills the form the same way. A server that suggests no template the form offers, such as a Docker container, is listed with no matching template; choose the template yourself. A server that already has a workflow is listed with has a workflow, workflow made on the agent or left behind by the workflow … (Agent 1.19.0+), and the form warns when you fill it from one.
• Get a certificate for a server lists every detected server of the chosen Agent in a Detected on this server menu in step 4. Use this fills in what the server runs, the names and the settings from the one you choose. The page starts from the first server it can set up that has no workflow yet. It can set up a server itself when the server's settings match what the page fills in: port 443, and on Windows the template's default certificate store. A server marked opens the full workflow form (another port or store, no names, or no template the page offers) opens that form filled in from it. A server marked has a workflow, workflow made on the agent or left behind is listed and cannot be chosen. With a single detected server the page starts from it and shows no menu.
• Check again (Agent 1.14.0+) asks the Agent to detect now, for example after you added a site on the server. The Agent answers within about a minute; reload the page to see the new list. It refuses while reporting is turned off on the device, and within 5 minutes of the last requested check. It needs agents.update. Between requests a Linux Agent detects every 24 hours (Agent 1.14.0+) and a Windows Agent every 12 hours; see When detection runs.

The dashboard only proposes. A reported name or setting is used only if it would be accepted when typed into the form; the Agent checks the proposal again, and its local administrator or auto-apply policy decides. The server can keep the list to itself: certintel config set report-detected-servers=off.

One certificate for several detected servers¶

Agent 1.18.0+, Windows. When an Agent detected several services that can share a certificate, one workflow can issue a single certificate and bind it to all of them, for example LDAPS, Remote Desktop and NPS on a domain controller.

1. Choose Create workflow for one of the servers (or pick it in the form's Detected on this server chooser).
2. Under Also use this certificate for, tick the other detected servers and choose Use one certificate for these servers.

3. The form is filled for the template One certificate for several Windows services with the names and settings of every chosen server: Filled in from the detected servers … one certificate will be issued and bound to all of them. Check every value, then create the workflow as usual.

4. Which services: Active Directory LDAPS, the Remote Desktop listener, Network Policy Server, Remote Desktop Gateway, the WinRM HTTPS listener and Routing and Remote Access SSTP. IIS sites are not among them. See One certificate for several services.

5. One of each service. Two Remote Desktop listeners or two NPS network policies cannot share one workflow: the second is listed with the reason and needs a workflow of its own.
6. The names. The certificate gets the names of every chosen server, so the issuer must be able to issue for all of them.
7. Servers that already have a workflow (covered or on the agent) are listed and cannot be ticked.
8. An older Agent shows Using one certificate for several of these detected servers requires Agent 1.18.0 or later on this computer.
9. Afterwards every chosen server shows as covered by that one workflow.

The template can also be chosen in the form without detection. The dashboard and the Agent refuse a proposal that selects no service or leaves out a setting a selected service needs, for example Network Policy Server is selected, so its network policy is required. Get a certificate for a server does not offer this template.

Certificate ids¶

The Certificate id names the certificate on the Agent, and the Agent names the certificate's files after it. The id therefore holds only what a file name can hold on every system, and it is lower case, because a file system that ignores case would mix two ids up:

• lower case letters, digits, hyphens (-), underscores (_) and dots (.);
• at most 64 characters, starting with a letter or digit;
• no dot at the end and no two dots in a row;
• no Windows device name (con, prn, aux, nul, com1 to com9, lpt1 to lpt9) before the first dot, because Windows opens a file named nul.example.com as the device.

So a host name can be the id, for example intranet.example.internal. The form lowers capitals as you type.

A dot needs Agent 1.8.2 or later, on every Agent you ticked. For an Agent without it the form takes letters, digits, - and _ only and says so, and a dotted id is refused with 422 (Requires Agent 1.8.2: this agent does not report certificate-id-dots support …).

The id must not exist on the Agent yet, and it cannot change later. On the device, the workflow the Agent creates for the certificate gets an id of its own: the certificate id with hyphens in place of the dots, followed by -workflow (intranet-example-internal-workflow).

Setting rules¶

Template settings that name a file or folder on the device follow the rules the Agent enforces, and the form shows each rule under its field:

A value that breaks its rule is refused with HTTP 422 before anything reaches the device, for example Setting 'Filename prefix (no extension)': file name 'site.pem' is not allowed: …. A setting that refers to a variable (${...}) is checked on the device. The Agent checks the same rules again when the proposal arrives and rejects a bad value at once, naming the setting, instead of failing after approval.

The dashboard and the API also refuse, with 422 before anything reaches the device, the other values the Agent would reject:

• an IP address among the DNS names (it belongs in IP addresses, Private CA only); more than 100 DNS names and IP addresses together; an IPv6 address with a zone (%eth0);
• a control character in the certificate's display name, or in the note other than line breaks and tabs, or in any setting;
• an empty or blank value for a required setting.

A new assignment (or a re-send) for a certificate id the Agent already manages is refused with 409; a replacement of that certificate is not.

Credential and choice fields¶

Templates can have two more kinds of setting:

• Choice - a list of fixed values, such as Use the certificate for on the FortiGate template. Only the values the Agent reported are accepted (Setting '…' must be one of: …; a refusal names the setting by the label the form shows).
• Credential - where an appliance credential comes from, used by the appliance templates. The list offers Local secret on the device and, for each of the organization's platform credentials of the matching kind, Platform credential: name. The assignment carries only this reference, never the credential itself. With Local, an administrator sets the value on the device after approval with certintel secret set remote WORKFLOW-ID:FIELD; until then the deployment step fails. A platform credential is fetched, sealed to the Agent, at each run, and only when the device allows it (see Platform credential). For an Agent that does not take platform credentials the hint says so and only Local works (This agent does not report platform-credentials support; set '…' to 'local' and set the value on the device, or update the agent.). Choosing a platform credential needs platform_credentials.read in the organization (Your role cannot use the organization's platform credentials.); a value that is neither local nor platform:<id> is refused (Setting '…' is a credential: set it to 'local' (an administrator sets it on the device) or to 'platform:<id>' (a platform credential); never a value.).

Settings that only a local administrator may set, such as Accept any management certificate (not recommended), are never offered in the form and are refused in an assignment. The form does not yet group templates by their category (appliances, Microsoft services, Linux services); the template list shows each template by name.

Kubernetes TLS Secret¶

The template kubernetes-tls-secret writes the certificate into a Kubernetes cluster as a TLS Secret with a kubeconfig on the Agent machine. The dashboard checks Namespace, Secret name, Labels and Annotations with the Agent's rules, and a proposed Kubeconfig file must be in the Agent's folder (/etc/certintel/kubernetes on Linux, %ProgramData%\CertIntelAgent\kubernetes on Windows); anything else is refused with HTTP 422 naming the setting. See Kubernetes TLS Secret.

Linux service templates¶

The Linux service templates haproxy-standard, caddy-standard, traefik-standard, litespeed-standard, postfix-standard, dovecot-standard, postgresql-standard, mysql-standard and tomcat-standard run a root starter hook on the device.

Agent 1.14.0+ installs the hook itself. When a workflow that needs a starter hook is approved on the device, or applied by the Agent's auto-apply policy, the Agent first writes its own certintel-KIND.sh to /etc/certintel/hooks.d (root, mode 0700), the script sudo certintel hooks starter KIND --write writes. It never replaces a script that is already there. The form says so under the chosen template: The agent installs certintel-KIND.sh, which runs as root after each renewal, when this workflow is approved on the device or by its auto-apply policy. Nothing has to be run on the server first. A local administrator can turn this off there with certintel config set install-starter-hooks=off; the rest of this section then applies again. If the script cannot be installed, the workflow is not applied, the reason is shown under Offers, and Send again works once the cause is fixed.

Earlier Agents, and Agents with install-starter-hooks off, refuse such an assignment at once until the hook is installed: starter hook certintel-KIND.sh is not installed; run certintel hooks starter KIND --write as root. The Agent also reports, for each template, the hook scripts it runs and whether each is installed, so the dashboard knows before you send: the form keeps offering the template with a line Needs setup on the device: … naming the command, and sending it is refused with HTTP 422 (… On the device, run 'sudo certintel hooks starter KIND --write' (or use sudo certintel tui), then propose it again.). A hook that exists but that the Agent's hook runner refuses (its owner, permissions or folder) is refused the same way, with sudo certintel hooks list to see why. Install the hook, then send: sudo certintel hooks starter KIND --write reports it to CertIntel at once and says whether CertIntel knows it (CertIntel now knows the hook is installed: the dashboard accepts proposals that use it). A hook installed another way is reported with the Agent's next check of dashboard assignments, about every 5 minutes - not with the hourly inventory report - or at once with sudo certintel assignments refresh. The Agent folder must also be a folder the Agent may write, which a root administrator prepares once with sudo certintel tui; the Agent checks this, and that no file the save step would replace there belongs to root or is a link, when the assignment arrives and before any certificate is ordered. See Linux service targets.

On a Linux Agent, nginx-standard and apache-standard save PEM files with an unencrypted key to /etc/certintel/certs/<site>, reload the web server through the root starter hook (installed by the Agent on approval from Agent 1.14.0; before that with sudo certintel hooks starter nginx --write, or apache), and check that the endpoint serves the new certificate. The site's configuration must name the saved files; the Agent does not edit it. With the optional setting Certificate file NGINX reads (or Apache httpd reads) (Agent 1.14.0+) the Agent instead replaces the certificate and key files the server already reads, so the server's configuration needs no change; see Replacing the files the server already reads.

Tomcat on Linux uses tomcat-standard, shown as Tomcat (starter hook) (Agent 1.9.0+): it saves PEM files, and its root starter hook installs them below Tomcat's base folder and restarts Tomcat. Its HTTPS port setting (default 8443) is the port the Agent checks afterwards; use the same port in Tomcat's connector. The keystore templates tomcat-jks and tomcat-p12 are for Windows only. See Tomcat.

Private CA certificates¶

For a Private CA issuer, the form also offers:

• Certificate profile - Server (TLS server authentication) (the default), Client (TLS client authentication, e.g. mTLS) or Server + client. Client and server + client certificates carry the clientAuth usage.
• Certificates with IP addresses only - the DNS names may be empty when the certificate has at least one IP address. Private addresses (RFC 1918, ULA, loopback, link-local) are allowed; the CA's name constraints still apply.

An ACME certificate takes no IP addresses: an IP address among its names is refused (IP addresses need the private CA: '…' cannot be in an ACME certificate's names.). After a Private CA rotation, new assignments name the successor CA.

Organization ACME accounts¶

An administrator can define an ACME account once for an organization on Settings → ACME Accounts in the dashboard, and every Agent of that organization can then use it - see organization ACME accounts for how to add one. For a workflow this means you can pick a CA account that is not yet configured on the device: the issuer menu lists the organization's accounts as ACME (organization): <name> (<CA>).

What happens on the device depends on its auto-apply policy:

• With auto-apply on for the organization (and the configuration lock off), the Agent adds the organization's accounts to its configuration at its next heartbeat (about hourly) after you create them. An assignment that names an account the Agent has not read yet makes it read the list first.
• Otherwise the Agent adds the account when a local administrator approves an assignment that uses it; the approval dialog names the issuer as usual.

The assignment itself still carries no secrets: the account's EAB key travels separately, from the platform to the Agent's protected secret store.

Deployment windows¶

An Agent reports which optional features it supports, and the form offers the matching fields only when it does (with several Agents, when all of them do):

• Deployment window (optional) - the weekdays, Window opens, Window closes, Window time zone and Deploy at once within (hours of expiry). Leaving every day unticked means no window. The window is written to the workflow the assignment creates; see Deployment windows for what waits and what does not. For an Agent that does not report the feature the form says Deployment windows: not reported by this agent.

The proposal's card shows the window in its own time zone. A request that asks for a feature the Agent does not report is refused with HTTP 422, from the form and from the API.

What the Agent does with a proposal¶

When the Agent fetches an assignment it validates it with the same code that runs certintel workflows create: the template must be bundled with that Agent for its operating system in exactly that version, every variable must be a declared non-secret field of the right type, the certificate id must be unused, the names must be valid for the chosen issuer, file names and folders must follow the setting rules, and the issuer must be a Private CA the Agent's cache lists as active, an ACME account it has configured, or one of the organization's ACME accounts. An assignment that carries anything the contract does not allow - steps, secrets, a path outside the template's declared fields - is refused outright. A refusal is reported back as rejected with the reason, and the Agent's activity log records Dashboard assignment … was refused by this agent: ….

A proposal for a CertIntel Private CA the Agent does not know yet (a CA created after its last hourly check) makes the Agent ask the platform again first, at most every 5 minutes. While the Agent cannot tell whether it may use the Private CA at all (it has not checked yet, the last check failed, or its approval is pending), it leaves such a proposal alone: the dashboard keeps showing Pending, and the Agent judges it at a later check.

A proposal that passes is recorded as awaiting approval, reported as such, and shown on the device:

• Windows: the Dashboard assignments section on the desktop app's Overview page lists it with Approve…, Reject…, Details and Check now.
• Linux: screen 7 Assignments in sudo certintel tui, and certintel assignments list.
• Either: certintel assignments show ID prints every detail, including the template settings, the issuer, the note from the dashboard and the revision, and ends with the exact command that approves that revision.

Nothing happens to the configuration until someone approves. The Agent's certintel status --json reports the feature under dashboard_assignments: status is available when the platform offers assignments to this Agent, unsupported when it does not (checked again every six hours), pending while the Agent itself still awaits approval (HTTP 428), or error with the reason in detail; awaiting_approval counts proposals that wait for you.

Approving or rejecting on the device¶

Each live assignment card in the dashboard says how to approve it on the device, with the exact command, for example Approve it on the device: sudo certintel assignments approve ID --revision N (Windows: the same command without sudo in an elevated prompt, or the CertIntel Agent app, Overview → Dashboard assignments), and links to What to do on the server.

Approval creates the certificate and the workflow exactly as the workflow wizard or certintel workflows create would, through the Agent's normal configuration save (the configuration revision increments and the activity log records the change), then queues issuance when the assignment asked for it. Rejection sends your reason to the dashboard and changes nothing.

Desktop app (Windows). Select the row and choose Approve…. The app runs without elevation, so the elevated CertIntel Agent - administrator approval dialog appears and lists the whole proposal: assignment id and revision, certificate id and name, every DNS name and IP address, the issuer, key type, automatic renewal and validity, every template setting, whether issuance starts at once, and the note (Requested by a dashboard user in the CertIntel dashboard; the person's identity stays in the dashboard timeline). Approve only if that is what you expect; the approval applies exactly the revision the dialog showed, and if the dashboard re-sent the assignment after the app listed it, the dialog does not open: refresh the list and review the new revision. A template setting too long for one line of the dialog is shown in full, split into numbered parts (Template setting … (part 1 of 3)). An assignment too long to review in the dialog at all is not approved there: the app tells you to open a prompt with Run as administrator, review it with certintel assignments show ID and approve it with the certintel assignments approve ID --revision N it names. Reject… asks for a one-line reason that the dashboard shows to the person who made the assignment, and the same elevated dialog confirms it, because the reason leaves the device under the Agent's name. See administrator approval in the desktop app.

Terminal interface (Linux). Open screen 7, select the assignment, press enter for the details, y to approve (a confirmation shows the same details) or n to reject with a reason. R asks the platform now, H shows the history. The actions need sudo certintel tui; a read-only session can look but not decide. See the terminal interface.

Command line (both). From an elevated prompt (Windows) or with sudo (Linux):

certintel assignments list                  # awaiting, applying, applied and failed
certintel assignments list --all            # also rejected, cancelled, expired, superseded
certintel assignments show ID              # ends with the approve command for this revision
certintel assignments approve ID --revision N
certintel assignments reject ID --reason "wrong site"
certintel assignments refresh               # ask the platform now (at most every 5 s)

approve ID --revision N approves revision N only - the one show printed - so a proposal the dashboard re-sent after your review is refused until you review it again. Without --revision in an interactive prompt, approve prints the proposal and asks Approve revision N of this assignment and apply it now? [y/N]; anything but y changes nothing. Scripts, RMM tools and --json have no one to ask and must pass --revision. After approving it prints the new configuration revision and, with Issue now, the issuance job id to follow with certintel jobs get ID; without it, issuance follows the renewal schedule and certintel certificates issue ID starts it at once. Add --json to any command for machine-readable output. show says when the assignment was proposed in the CertIntel dashboard; the person who proposed it is shown only in the dashboard's timeline.

Every surface approves the exact revision it showed you. If the dashboard re-sent the assignment with changes between your review and your approval, the Agent refuses with conflict: revision N was reviewed but revision M … now awaits approval; review it again - look at the new proposal and decide again. An assignment whose lifetime ran out while it waited is closed as expired on the device when you try to approve it; nothing is created.

If the Agent cannot apply an approved assignment - the Private CA was disabled meanwhile, the resulting configuration is invalid - it reports failed with the reason and leaves the configuration as it was. If the service was busy or could not save at that moment, nothing is wrong with the proposal: it stays awaiting approval and you approve it again. The same holds when the Agent cannot confirm right now whether it may use the Private CA the proposal names (unavailable: the CertIntel Private CA availability could not be confirmed): retry in a few minutes.

A proposal that uses the organization's Delegated DNS-01 records gets each record's credential from CertIntel while it is approved. If an administrator disabled (revoked) the record meanwhile, CertIntel refuses with 409 delegation-disabled, and the Agent keeps the assignment awaiting approval: refused: the platform did not issue a DNS-01 credential for … (record …): the Delegated DNS-01 record is disabled in CertIntel: The Delegated DNS-01 record … is disabled (revoked). Reactivate it under Delegated DNS-01 in the CertIntel dashboard, then approve the assignment again. Nothing was changed on this device, and dashboard assignment … still awaits approval. Reactivate the record, then approve again. The same holds when DNS-01 for agents is switched off for the workspace (403 dns01-disabled).

If the certificate and workflow were created but the Issue now attempt failed for a reason the Agent retries on its own (DNS propagation, a CA rate limit or outage), the assignment stays applying with issuance is being retried after a failed attempt; the scheduled renewal pass issues later and the Agent then reports applied with the thumbprint, or failed once the order is held (a policy rejection or exhausted attempts). A failure the Agent will not retry is failed at once; the certificate stays configured and can be issued again from the device like any other. Issuance that was queued for an assignment still runs when another assignment or a setting changes the configuration meanwhile; if that certificate's own settings changed before issuance started, the Agent queues issuance again for the certificate as it now is (the assignment stays applying), and if the certificate was removed, the assignment is failed.

Auto-apply policy¶

A local administrator can tell one Agent to apply assignments from its organization without a local approval: the checkbox Apply assignments from this agent's organization without local approval (auto-apply) in the desktop app's Dashboard assignments section, the A key on the terminal interface's Assignments screen, or

certintel assignments policy --auto-apply on
certintel assignments policy                 # show the current policy
certintel assignments policy --auto-apply off

A new installation has auto-apply on by default: the installer records the consent, and the Agent binds it to the organization the platform reports when it connects. An existing installation that upgrades keeps its current choice. To install with it off, choose Off for Apply dashboard assignments from this organization without local approval under Advanced on the install page.

The dashboard shows the policy. On the Agents page a device with auto-apply on carries the label auto-applies assignments (or auto-apply for another organization when its consent names a different organization, so proposals from this one still wait). The Agent's own page and the New workflow form say before you propose anything whether the device will apply it without a local approval. The device reports its policy with its capabilities, so a change shows up at its next check, within about 5 minutes. The dashboard only displays the policy; it cannot change it.

The policy is a setting in the Agent's own configuration, bound to both the organization the platform reported for the Agent's key when it was turned on and the platform address the Agent was connected to; certintel assignments policy shows both (assignments from organization … at https://… are applied without local approval). A later connection to a different platform does not inherit the consent even if it claims the same organization. Turning it on is a security-sensitive change: the confirmation, and on Windows the elevated approval dialog, state that the SYSTEM service will create, issue and install the proposals as they arrive, including any folder paths and keytool executable a proposal names (the file and JKS templates take a destination folder and the keytool path as fields). Turning it off is routine; it removes the setting from config.json altogether. Only proposals that arrive after the switch is turned on are applied automatically; anything already awaiting approval still needs your decision. The Agent applies them during its own checks (every 5 minutes, sooner when the platform signals a new assignment); certintel assignments refresh and Check now only fetch, so a proposal they bring in is applied at the Agent's next own check. The dashboard cannot read, set or imply the policy; it only learns of it from the report of an applied assignment, which says decided by policy. If the platform later reports a different organization for the same key, the Agent discards its cached assignments and the policy no longer matches until an administrator turns it on again (assignments already being applied finish and are still reported). Replacing the credential (unregister, a key rotation, a new enrollment) forgets the cached assignments too; live ones are fetched again and wait for approval - the first list after such a change is never applied automatically. Registering or enrolling the Agent with a different platform address turns auto-apply off, and so does a service start with a configuration whose consent names another platform than the one configured; the activity log then records Automatic application of dashboard-assigned workflows was turned off: …; an administrator must confirm the policy again.

Configuration lock¶

A local administrator can turn on the Agent's configuration lock (on Linux see the Linux page). While it is on, the Agent applies no dashboard assignment at all:

• auto-apply is skipped, and Approve on the device is refused (the desktop app and terminal interface disable it, and certintel assignments approve is refused with code locked);
• every live assignment is reported once per revision as awaiting approval with the reason Configuration lock is on; platform changes are blocked on this agent.;
• proposals that arrive while the lock is on wait for a local administrator after it is turned off; they are never applied automatically, even with auto-apply on.

The Agent reports the lock with its heartbeat, within about two minutes of a change. On the device, certintel status reads the lock each time you run it, so a lock, an unlock or a change of the folder's permissions shows there at once. The dashboard then shows a Locked pill on the Agents list, on the Agent's host detail (with a Configuration lock row) and on its assignments page, and marks the Agent's live assignments Blocked by configuration lock. A locked Agent cannot be ticked for a new workflow, and New workflow for this agent on its page is replaced by an explanation. A workflow it already runs can still be edited; the edit waits like any other proposal. The API still accepts a proposal for a locked Agent; it waits until the lock is turned off. Renewals and deployments of existing certificates are not affected.

Renew now¶

Renew now asks the Agent to renew one of its certificates at once, outside the renewal schedule:

• on Workflow Assignments, on the row of a workflow that is Applied;
• on a workflow's page while an Agent runs it, and on the card of an Applied proposal on the Agent's own page;
• on ACME Renewals, in the pop-out of a renewal an Agent reported for a certificate it manages from its own configuration.

The request names only the certificate id. The Agent runs its own local Renew now with the configuration it already has. Like the local action it bypasses the renewal window, not the CA's rate limits, retry backoff or uncertain-order protection, and a deployment window still decides when the renewed certificate is installed. The Agent decides; the confirmation says so, and its answer is shown on the page.

The Agent picks the request up with its next assignment check (every 5 minutes; within about a minute with Agent 1.13.0+) and reports back: Renewal request sent to the agent, Renewing, then Renewed or Renewal failed (with the error). It refuses a certificate it does not manage, one whose auto-renew a local administrator switched off, and a second dashboard renewal of the same certificate within an hour of a successful one (Renewal refused, with the reason). It also refuses it for these reasons:

The configuration lock blocks only dashboard renewal requests: the Agent's own scheduled renewals carry on while it is on. A forced renewal validates every name with DNS-01 again (see CLI equivalents). A request nobody finished expires after 24 hours. One request per certificate and Agent can be open at a time.

Renew now is not offered for a certificate the Agent stopped retrying: its card says Renew now: the agent stopped retrying this certificate and does not take a request from the dashboard for it; start it on the device (see Next attempt). The Next attempt line names the command (see When the Agent tries again).

Asking needs agents.update in the Agent's organization (Operator and Administrator).

How soon the Agent hears of it¶

(Agent 1.13.0+) The Agent asks CertIntel about once a minute whether anything changed for it, and then fetches only what changed. A new or changed workflow, Renew now, Update now, a new internal TLS endpoint or its Check now, the Private CA permission, an organization ACME account, branding, the ignored CA list, a CRL monitor and an AD CS template therefore reach the device within about a minute. The question carries no instructions: the platform still only proposes or requests, and the device decides.

• certintel status shows the state on the Sync: line, and the Linux terminal interface shows Platform sync under Schedules.
• While it works, the Agent checks for workflows every 30 minutes instead of every 5.
• If CertIntel cannot be reached, the Agent asks again after 1 minute, then 2, 4, 8 and so on up to an hour. Its other checks continue on their own schedule.
• Earlier Agents hear of a change at their next check: workflows and Renew now within 5 minutes, the rest within about an hour.

States¶

The list shows the state of each workflow, and each proposal's card shows the state of that proposal. The API names them as in the second column.

A Failed assignment whose certificate was issued, where only the installation failed, can still become Applied: the Agent reports Applied for the same revision once a later installation of that certificate succeeds (certintel deployments retry ID or the Agent's own retry).

If you re-send an assignment while a local administrator is approving the previous revision, the device keeps what was approved. The dashboard then shows the state the device reports for that earlier revision, the timeline says This was revision N, acted on before the dashboard re-sent revision N+1, and the re-sent revision is not applied; create a new assignment if you still need it. When that approval of the replaced revision failed without changing anything on the device, it is not the assignment's outcome: the assignment keeps revision N+1 and its state, the page says Revision N was replaced before the device acted on it …, and revision N+1 can still be approved on the device or re-sent. The Agent checks with the platform before every local approval: approving the replaced revision is refused (revision N was reviewed but revision N+1 … now awaits approval; review it again) and nothing is reported for it. When the platform cannot be reached, the approval is refused as unavailable and the proposal keeps waiting.

When the configuration lock is turned off, the Agent reports its waiting proposals again without the lock reason, and the dashboard drops the lock reason from the assignment. certintel assignments show ID, the terminal interface and the desktop app show the proposal's deployment window (Deployment window: renewed certificates install only Sat, Sun 22:00–04:00 Europe/London …). The days read every day, a run of three or more as Mon–Fri, or a list such as Sat, Sun.

On the device, certintel assignments list --all also shows superseded (a re-sent revision replaced a proposal that was still awaiting approval; the new revision is validated afresh). Finished records are kept on the device for 30 days.

Limits¶

• A workflow names at most 20 Agents, all of one organization.
• One live assignment per certificate id per Agent; at most 64 live assignments per Agent, together at most 900 KiB (the dashboard refuses an assignment or an edit that would exceed it); the note is 500 characters; the display name is 120 characters.
• A locked Agent applies nothing until its configuration lock is turned off on the device.
• Only bundled templates in the version the Agent carries; templates are part of the Agent itself and change only with an Agent update. Custom step sequences, imported workflows, secret values and post-renewal scripts cannot be assigned; add them on the device afterwards if needed. A credential field carries only a reference (Local or a platform credential), never the credential.
• Workflows target the Agent's API key. A re-enrolled Agent (new key) receives nothing until a workflow names it.
• No remote removal: cancelling only withdraws a proposal the device has not applied. Retiring a workflow is a local action.
• The Agent reports ids, states, a bounded reason, the job id, the thumbprint and its configuration revision. Who approved on the device stays in the device's activity log and is never sent to the platform; who created the workflow stays in the dashboard timeline and is never sent to the device.

Related pages¶

• Workflow studio & usage - creating workflows on the device
• Modular workflow builder & action inputs - template fields
• Appliance deployment - appliance templates and their credentials
• Kubernetes TLS Secret - the Kubernetes template and its kubeconfig
• Platform credentials - appliance credentials stored in CertIntel
• ACME providers - organization ACME accounts
• Install tokens & enrollment - the Agents page
• Private CA - allowing a CA for an Agent
• Organizations, users & roles - workflow_assignments permissions
• Troubleshooting - rejected, failed and missing assignments