Dashboard-assigned workflows¶

A platform administrator can propose a certificate workflow for one enrolled Agent from the CertIntel dashboard: pick the device on the Agents page, choose one of the Agent's bundled templates, fill in its fields, name the certificate and its issuer, and send it. The Agent fetches the proposal, checks it exactly as it checks a workflow created on the device, and 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. Agent 1.3.95 and later, on a platform build that offers the feature.

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 that an administrator set on that device. 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.

Assigning a workflow from the Agents page¶

1. Open Agents and find the device. The row offers Assign workflow once the Agent is approved, not revoked or unregistered, and has reported what it can do. Until then the row explains why: waiting for the first heartbeat (the device has not reported at all yet), Agent too old: update to 1.3.95 or later (an earlier release, or a client that is not the CertIntel Agent) or Waiting for the agent's capabilities report; it is sent within minutes of approval (the Agent is new enough but has not sent its template list yet).
2. Choose a template. The list is built from what that 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.
3. Fill in the certificate: id, 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. An ACME account that uses one of the Agent's CA presets is listed as ACME: (). An ACME certificate needs a delegated DNS-01 record on that Agent for every name; the Agent reports the delegated names, so the form refuses names it could not validate (and the Agent itself rejects with no delegation for certificate … if its 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 (Agent 1.5.0+) 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. Tick Issue now to issue and install right after approval, or leave it clear to create the certificate and workflow and let issuance follow the renewal schedule. Add a note for the person who will approve it on the device (ticket number, purpose); the note is shown there. An assignment expires after 30 days by default (1–90) if nobody acts on it.
5. Send. The form tells you when the Agent will see it: the Agent checks for assignments every 5 minutes, and within a minute for 15 minutes after approval; run certintel assignments refresh or restart the service to check now.

Credential and choice fields¶

Since Agent 1.5.0, 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 (Variable '…' must be one of: …).
• 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 (Variable '…' is a credential: set it to 'local' (an administrator sets it on the device) or to 'platform:' (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.

Linux service templates¶

The Linux service templates haproxy-standard, caddy-standard, traefik-standard, litespeed-standard, postfix-standard, dovecot-standard, postgresql-standard and mysql-standard (Agent 1.5.0+) run a root starter hook on the device. The Agent refuses 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 folder must also be a folder the Agent may write, which a root administrator prepares once with sudo certintel tui; the Agent does not check this before the first run. See Linux service targets.

Private CA certificates¶

For a Private CA issuer, an Agent 1.5.0 or later 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. For an older Agent the form reads Server: this agent does not report private-ca-profile support (Agent 1.5.0+).
• 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. For an older Agent add a DNS name (This agent does not report ip-only-certificates support; update the agent, or add a DNS name to the certificate.).

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.

Deployment windows¶

Agent 1.4.0 and later report which optional features they support, and the form offers the matching fields only for such an Agent:

• 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 older Agent the form says Deployment windows: not reported by this agent.

The assignment 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.

The assignment appears under the Agent with its state and a timeline; the organization-wide overview groups every assignment by state. While it is pending or awaiting approval you can Re-send it with changes (the Agent treats the new revision as a fresh proposal) or Cancel it. An assignment whose lifetime ran out is marked Expired before either takes effect, so re-sending or cancelling it is refused; you can delete it. Once the Agent has applied it, the assignment is history: retiring the workflow or the certificate is a local action on the device. Revoking, deleting or unregistering the Agent's key cancels its live assignments; rotating the key keeps them. Creating an assignment needs the workflow_assignments.create permission in the device's organization plus agents.read (the built-in Administrator and Operator roles; Operators can also re-send and cancel, only Administrators delete finished assignments; Auditors can read; custom roles can grant each action); see permissions. The Agent's assignments page, and the Assign workflow and Assignments buttons on its row, need agents.read and workflow_assignments.read in the device's own organization; a grant in another organization does not open it. The timeline records who created, re-sent or cancelled an assignment; that identity is never sent to the device.

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, and the issuer must be a Private CA the Agent's cache lists as active or an ACME account it has configured. 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 on an older platform (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¶

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 --json; 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.

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. 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

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), and its assignments page says 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. Agents before 1.3.95 do not report it and show no label.

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, so an earlier Agent release can still read the configuration after a downgrade. 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 (Agent 1.4.0 and later; 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. 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. The Assign a workflow form is replaced by an explanation. The API still accepts a proposal for a locked Agent; it waits like any other until the lock is turned off. Renewals and deployments of existing certificates are not affected.

States¶

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.

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¶

• 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.
• Assignments target the Agent's API key. A re-enrolled Agent (new key) receives nothing until a new assignment is made for it.
• No remote removal: cancelling only works before the device applied the assignment. 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 assignment 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
• Platform credentials - appliance credentials stored in CertIntel
• 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