How deployment works¶
PKIFactor does more than issue certificates: it delivers them onto the devices that serve them, renews them there before they expire, and checks that the device actually serves the expected certificate. No agent is installed: PKIFactor uses each device's management API (iControl REST, FortiWeb REST, PAN-OS XML API, Check Point Management API, Kemp REST, WinRM, SSH).
Vocabulary¶
| Term | Meaning |
|---|---|
| Endpoint (deployment target) | A device declared in Administration > Operations > Endpoints, with its management address and service account |
| Binding | One certificate attached to one place on the endpoint: an F5 SSL profile, a FortiWeb server policy, a PAN-OS decryption rule, a Check Point server certificate object, a Kemp virtual service, an IIS site, a site (file paths) on a Linux server |
| D-X | Number of days before expiry at which the renewal starts (30 by default) |
Who can do what¶
| Role | Endpoints and bindings |
|---|---|
| Administrator | Everything: declare, edit and delete endpoints and bindings, deploy, pause, adopt, set the deployment defaults, and name the operators of each endpoint (section Operators of this appliance on the endpoint page) |
| Operator | The endpoints of their organizations that an administrator assigned to them, under Operations > Endpoints, according to their permissions: See appliances and bindings and Deploy, rotate, pause and resume, verify are granted by default; Create and edit appliances and bindings and Delete appliances and bindings are not. Approving an SSH host key stays with administrators |
| Other roles | No access to the endpoint list |
Administrators and auditors also follow deployments from the Oversight dashboard and the Deployment incidents list (see Dashboards).
The binding form¶
Add a binding on the endpoint page (or Create binding from estate discovery) opens the form Link a certificate. Its fields:
| Field | Content |
|---|---|
| Certificate source | Existing certificate (an issued certificate), or Issue from a template: a certificate profile and the CN to issue; PKIFactor issues the certificate from that profile's authority |
| The place on the device | Depends on the device, see the table below |
| Key custody | Key generated by PKIFactor and pushed to the appliance, or Key born on the appliance / netHSM — it never leaves it where the device supports it |
| Automation | Full auto, Install, Provide only, ACME (see below) |
| On-device key algorithm | Inherit from certificate, or an algorithm allowed by the profile |
| Reuse the device key on renewal | Re-certifies the key already on the device instead of creating a new one |
| Renew (days before expiry) | The D-X of this binding |
| Intervention date (UTC, optional) | A one-shot date for the next action; when empty, it is derived from D-X |
Since version 1.8.49 the place on the device is named in the device's own vocabulary. Devices where the certificate is attached to a single object have one field; the same name is used for the object and for the profile in the API:
| Device | Field(s) |
|---|---|
| F5 BIG-IP | Certificate role (server certificate, client certificate for outbound mTLS, forward-proxy CA), then Virtual server and Profile (server certificate) |
| Linux server over SSH | Probed TLS endpoint (host:port) and Site (placement on the server) |
| Palo Alto Networks | Decryption rule |
| Check Point | Server certificate object (always typed in; created if it does not exist) |
| Kemp LoadMaster | Virtual service |
| Windows IIS | IIS site |
| Fortinet FortiWeb | Server policy |
When the device answers, the field is a list read from it; otherwise you type the name. The same vocabulary is used on the binding page, in Edit binding and in the group binding form of crypto-agility.
Two independent choices per binding¶
Where the private key is born (key custody)¶
| Custody | What happens |
|---|---|
Key pushed (push_both) |
PKIFactor generates the key, has the certificate issued, then pushes key and certificate together, encrypted in transit. Simple; the key travels. |
Key on the device (csr_on_device) |
The device (or its netHSM) generates the key, which never leaves it. The device produces a CSR, PKIFactor has it signed and returns only the certificate. Recommended for sensitive and FIPS keys. Available on F5 BIG-IP and on Linux servers over SSH (the key is generated on the host with openssl). The form also offers it on PAN-OS, for certificates the firewall terminates itself; this path is not tested, and inbound inspection always needs a pushed key. On IIS, Kemp, Check Point and FortiWeb the form offers only the pushed key. |
What PKIFactor does on its own (automation level)¶
| Level | At D-X |
|---|---|
| Full auto | Renews, installs and activates the certificate, without intervention |
| Install | Prepares the renewed certificate on the device (staged); a person clicks Activate (switch over). With the key on the device, provisioning is manual (Provision on appliance) |
| ACME | The device renews itself through its own ACME client against PKIFactor's ACME server; PKIFactor supervises. Choosing it asks for a confirmation, since PKIFactor then stops pushing certificates to the device |
| Provide only | Makes the certificate available (download, API, Make available on the binding page); writes nothing on the device. Only with a pushed key |
Defaults are set once in Administration > Operations > Endpoints, panel Deployment defaults (Default D-X for new targets and Maintenance window (UTC hour, empty = as soon as due)), then per endpoint (default lead time and default delivery mode), then per binding.
The safety rules¶
Never break production¶
Before any change, PKIFactor reads the real topology of the device and decides:
| Situation found | Decision |
|---|---|
| The profile is used by one virtual server only, nothing unusual | Full auto proceeds |
| The profile is shared by several virtual servers, shared through SNI, or inherited by other profiles | Downgraded to staged, approval required: a person validates the switch over, seeing the list of affected services |
| The certificate object is also referenced by profiles PKIFactor does not manage | Downgraded to approval, and the other profiles are named |
| The configuration is owned by another tool (F5 AS3, iApp) | Refused, with the reason |
| The served certificate is not the one PKIFactor last delivered (someone changed it on the device) | Drift: no automatic overwrite; a badge and an alert until a person decides |
A renewal always creates a new object on the device and repoints the profile to it in one transaction; the previous object is kept until the switch over succeeds, which makes rollback possible. On a cluster, the change is synchronized to the peers and the synchronization is checked (F5 clusters).
Human control¶
| Control | Effect |
|---|---|
| Veto (pause) | Stops any automatic action on the binding until it is lifted, with a reason (Pause…, then Resume); set by an administrator, or by an operator who has the endpoint and the deploy permission, at any time |
| Intervention date | Postpones the next automatic action to a chosen date |
| Maintenance window | Restricts automatic actions to an hour of the day (UTC) |
Protecting private keys¶
A binding that pushes a private key to a device is, in effect, an export of that key. PKIFactor therefore applies the same rules as for a PKCS#12 download:
| Situation | Rule |
|---|---|
| Binding someone else's certificate to a device, provisioning it on the device, renewing it there | Reserved to the owner of the certificate and their team, whatever the key mode (key pushed by PKIFactor or generated on the device): signing a device's CSR with someone else's identity would hand that identity over |
| A device is redirected: its address, port, transport, TLS verification, account or commands change (each connector declares which settings count) | The bindings that push a key are paused with the reason device redirected. Only the owner of the certificate (or their team) resumes them, from the certificate page (Resume); another pause cannot replace that reason |
| TLS verification is turned off, or the trusted CA is removed | The device credentials must be entered again, as for a new host: they are never sent over a channel that is no longer verified |
| An SSH server | No authenticated connection before an administrator has approved the host key fingerprint; the fingerprint is erased when the host or port changes |
Verification¶
After each push, and then every hour (or at once with Verify now on the endpoint page), PKIFactor reads the device's configuration and compares the certificate actually attached to the binding (serial number, and public key fingerprint where the device exposes it) with the expected one. Only then does the binding become Verified.
This is a proof of configuration read through the management API, not a TLS connection to the service: it confirms what the device is configured to serve. Some devices serve a certificate chosen by rules outside the binding (an F5 iRule, an SNI selection to another profile); those cases are reported by the drift detection when they replace the certificate, not otherwise.
Lifecycle of a binding¶
| State | Meaning |
|---|---|
| Planned | Waiting for D-X |
| Deployed, not verified | Pushed; waiting for the next verification |
| Verified | The device serves the expected certificate |
| Staged | Prepared on the device, waiting for a person to activate it |
| Drift | The device serves something else than what PKIFactor delivered |
| Failed | The last attempt failed; PKIFactor retries with increasing delays |
| Paused | Veto, or a failure that cannot be retried (missing object, credentials refused) |
When a binding fails, its page shows the last failure, its cause in plain words (credentials, network, object missing on the device, permission), and the steps to repair it. A failure that cannot be fixed by retrying pauses the binding instead of renewing certificates in a loop. The History section of the binding page lists the actions recorded on it, newest first, with their author or Automatic.
Alerts¶
Deployment events are sent to the certificate's owner, to the SIEM, and, when ServiceNow is configured, as tickets: a failed deployment opens an incident; a renewal that needs an installation step on the device (for example a Check Point policy installation) opens a change request with its due date.
Discovery is not deployment¶
The network scanner observes what is served on the network. Deployment acts on the device's management plane, usually on another address. You deploy onto a declared endpoint, never onto a discovered IP address. Estate onboarding links the two: it imports what an endpoint already serves and lets you attach those certificates to PKIFactor in bulk.
License¶
Devices are not counted by the license and are never limited.
Supported devices¶
| Device | Connector type in the form | Delivery | Key on device | Tested in the laboratory | Guide |
|---|---|---|---|---|---|
| F5 BIG-IP, including clusters | F5 BIG-IP | iControl REST | yes, including netHSM / FIPS | two-unit cluster | F5 BIG-IP, F5 clusters |
| Fortinet FortiWeb | Fortinet FortiWeb | REST API | no | FortiWeb 7.6 | FortiWeb |
| Palo Alto Networks PAN-OS | Palo Alto Networks (PAN-OS) | XML API | not for inspection (offered for the firewall's own certificates, not tested) | PAN-OS 12.1 (virtual firewall) | PAN-OS |
| Check Point | Check Point | Management API (R80+) | no | Gaia R81.20 | Check Point |
| Progress Kemp LoadMaster | Kemp LoadMaster | REST API, or its ACME client | with ACME only | LMOS 7.2.63 | Kemp |
| Windows IIS | Windows server (IIS) | WinRM, or an ACME client on the server | with ACME only | Windows Server | Windows IIS |
| Linux servers (nginx, Apache, HAProxy, Tomcat, WildFly, OpenLDAP...) | Linux server (SSH) | SSH and SFTP, with a reload command | yes, generated on the host (not for Java keystores) | Debian, RHEL family | Linux servers over SSH |