Skip to main content
Video tutorial · 3:20

FortiGate module

Puts the certificate on a Fortinet FortiGate firewall over the FortiOS REST API v2. The first deploy creates a local certificate; every later deploy updates that same object in place. FortiGate keeps its name, its comments and every VIP, SSL inspection profile and SSL VPN reference, and serves the new certificate a few seconds later — so a binding made once follows every renewal.

Every behaviour on this page was measured on FortiOS 7.6.8. Under continuous traffic, six updates in two minutes gave 8 failed fresh handshakes out of 647, against 6 out of 573 in an equal run with no update, and no keep-alive connection was broken in either run — no drop above the normal level.

Overview​

  • Type: fortigate, credential type: fortigate_api_token (JSON {"api_token"}), slot default.
  • Per target: read the system status and the local certificate under its resolved name → import any intermediate the firewall lacks into the CA store → create the local certificate, or update it in place → add it to the configured VIPs, SSL inspection profiles and SSL VPN where it is missing.
  • Rollback: supported — a rollback updates the same object in place with a previous retained certificate version (Rollback). Auto-rollback is available.

What the module deliberately does NOT do​

  • It never removes a placement. On every deploy the certificate is added to each configured placement where it is missing — also after someone took it out on the FortiGate, so remove a placement from the target (or the override) to stop it. A certificate is never taken out of a VIP, an SSL inspection profile or the SSL VPN.
  • It never deletes a CA certificate. Imported intermediates stay: other chains may rely on them, and FortiGate does not count chain use as a reference.
  • It never changes an SSL inspection profile's mode. A profile in re-sign mode is refused, not switched.
  • It does not set the admin GUI certificate and refuses to write the certificate the management interface serves (admin-server-cert) — see Ownership. It does not touch firewall policies and does not talk to FortiManager.
  • It never renames a CA certificate. FortiGate's own name (CA_Cert_N) is kept: a rename closes the open TLS sessions FortiGate terminates, just like an import (measured).
  • It never writes a factory certificate — naming one is refused.

Requirements​

  • A REST API administrator and its token (System → Administrators → Create New → REST API Admin). FortiOS 7.6 accepts the token only in the Authorization: Bearer header; the module never puts it in a URL.
  • HTTPS reachability from CertAutoPilot to the management interface (default port 443). If the administrator has Trusted Hosts, include CertAutoPilot's egress address — a request from outside them is refused like a wrong token.

Least-privilege admin profile​

Minimum access: a dedicated REST API administrator whose admin profile has vpngrp read-write and every other group none, with the target's VDOM in its VDOM list. Add fwgrp → custom → address read-write only for VIP placements, and others read-write only for SSL inspection profile placements. The SSL VPN placement needs nothing more. It does not need super_admin or sysgrp.

config system accprofile
edit "certautopilot"
set vpngrp read-write
set fwgrp custom
config fwgrp-permission
set address read-write
set others read-write
end
next
end
config system api-user
edit "certautopilot"
set accprofile "certautopilot"
set vdom "root"
config trusthost
edit 1
set ipv4-trusthost <CertAutoPilot address> 255.255.255.255
next
end
next
end
execute api-user generate-key certautopilot

Leave out the fwgrp lines when the target has no VIP or SSL inspection profile placements.

Everything not listed (including sysgrp) can stay at none:

SettingAccessNeeded for
vpngrpread-writeAlways: local certificates, the CA store, the SSL VPN server certificate and the system status. With read only, every certificate write answers 403 (FORTIGATE_PERMISSION).
fwgrp → custom → addressread-writeOnly for VIP placements: adding the certificate to a VIP. Reading a VIP worked with vpngrp alone.
fwgrp → custom → othersread-writeOnly for SSL inspection profile placements (and their picker).

Refused tokens and the admin lockout​

FortiGate counts refused tokens toward its admin lockout per source address, not per account. Measured: after four refused tokens, even a valid token was refused for about 50 seconds — for CertAutoPilot and for every administrator behind the same address. So a refused token (HTTP 401) is never retried, and the run sends nothing more to that firewall: its other targets fail with "not attempted". Dry run, validate and health check behave the same. The refusal is also remembered for about 70 seconds for that firewall and that token, across runs: a retried job, the next distribution, a health check or a picker using the same token sends nothing in that window and fails with "not attempted". The refusal is recorded in the database, so every node of a multi-node installation (and the API process beside a separate worker) holds the token too — keyed by the firewall, the credential and the moment its token was last entered, never by anything derived from the token. Entering the token again, or another token for the same firewall, is not held, so a corrected credential works at once. A node the device accepted the same credential from in the last 10 minutes does not wait for another node's refusal (a device can refuse only some addresses — trusted hosts); a credential read from a secret store without versions is held only by the node that was refused. The token's format is checked when the credential is saved, so a token that cannot be right is never sent.

Target configuration​

FieldMeaning
hostManagement IP address (IPv6 bare or in brackets) or ASCII host name — no scheme, port, path or trailing dot.
portManagement HTTPS port. Default 443.
vdomOptional VDOM every request names (empty = root; 1–31 letters, digits, _ or -). See VDOMs.
cert_nameOptional local certificate name: letters, digits, ., _, -, at most 35 characters (the FortiGate limit). Names starting with Fortinet_ are refused: every factory certificate measured on FortiOS 7.6 is named that way. Empty (recommended) means the per-certificate auto name cap-<token>-<slug>. See Ownership.
placements.vipsOptional firewall VIPs to add the certificate to (up to 50).
placements.ssl_profilesOptional SSL inspection profiles to add it to (up to 50). Each must be in replace mode.
placements.ssl_vpnOptional: make it the SSL VPN server certificate.
delete_old_certDefault off. Only matters when the certificate name changed — see Previous object.
ssl_verifyDefault off: FortiGate management certificates are self-signed out of the box.
ca_certOptional PEM CA certificate(s) added to the trust roots while ssl_verify is on. Refused (400) while ssl_verify is off.
tls_fingerprint_sha256Optional SHA-256 of the certificate the management interface serves; checked on every connection, with ssl_verify on or off. The health check and the dry run show the value. A mismatch refuses the connection before anything is sent (TLS_TRUST_REFUSED).
http_timeoutPer-request timeout in seconds, 5–300. Default 30.

With ssl_verify off and no tls_fingerprint_sha256 pinned (the default), the token goes to whoever answers at that address: deploy, dry run and health check warn TLS_UNVERIFIED_PASSWORD and show the served certificate's SHA-256 — pin it, or turn ssl_verify on (with ca_cert for a private CA). Nothing is blocked. The TLS options still follow the credential-binding rule: for a bound credential, only the person who entered the secret or an organization owner may weaken them; anyone else may only add a check (422 CREDENTIAL_TLS_CHANGE_NOT_ALLOWED).

The module config carries one tuning field, concurrency (API only): how many targets one run deploys in parallel, default 5, clamped to 1–50.

How a deploy works​

  1. Local checks. The private key is read and compared with the certificate before anything is sent; a key that does not belong to the certificate is refused (FORTIGATE_VALIDATION) with nothing written.
  2. The chain. FortiGate drops intermediates placed in the certificate field and serves the chain from its CA store. A chain certificate the firewall already holds (compared by SHA-256 with the user CA certificates, whatever its name) is reused — nothing is written. One it lacks is imported and keeps the name FortiGate gives it (CA_Cert_N): for an update in place before the leaf, so the new leaf serves its full chain from the first moment; for a new object right after creating it — nothing serves a new object yet, and a create FortiGate refuses (the certificate already on it under another name) then imports nothing. Inside a known HA cluster (a-p / a-a), a CA the cluster already held is not offered again after a failover; an HA mode the token cannot read is treated as a single unit. About 4 seconds after an import FortiGate closes the TLS connections it terminates that are open at that moment — the run warns FORTIGATE_CONNECTIONS_RESET (see What interrupts traffic). CA certificates are never renamed or deleted.
  3. The leaf. The first deploy creates the local certificate with the private key (CertAutoPilot converts the stored key to unencrypted PKCS#8) and the ownership tag certautopilot:<certificate id> in its comments. Every later deploy updates it in place. When the same leaf is already there, nothing is written.
  4. Placements that are missing are added (see below).
  5. Not bound? With no placement configured and nothing on the firewall referencing the object, the run succeeds with the warning FORTIGATE_NOT_BOUND — bind it once on the FortiGate; renewals keep the binding.

Post-deploy validation endpoints wait for the new leaf to settle before they connect (measured: about 6 seconds).

What interrupts traffic​

Measured on FortiOS 7.6.8 with idle keep-alive connections open while one operation ran at a time:

OperationEstablished connections
In-place update of the local certificate (every renewal)Kept
Writing the ownership commentKept
Creating a local certificate nothing uses yetKept
Adding the certificate to a VIP or an SSL inspection profile, setting the SSL VPN certificateKept
Reusing a CA certificate the firewall already holdsKept
Importing a CA certificate the firewall did not holdTLS connections the FortiGate terminates (SSL offload on a VIP) are closed once, about 3–5 seconds later — on every such VIP, not only this certificate's. Their clients reconnect.
Renaming a CA certificate (CertAutoPilot never does)Closed the same way

What a CA import does not interrupt (measured in the same windows):

  • new connections — TLS handshakes made during that moment succeeded;
  • ordinary firewall traffic — TCP sessions through flow-mode and proxy-mode policies stayed open;
  • administrator sessions to the FortiGate.

A REST API request that is in flight on the management interface at that moment can be cut too (seen in the live tests). CertAutoPilot sends a read, or a write that only sets values, once more on a new connection when that happens; a create is never repeated — if one is cut, the run fails and the next attempt picks it up.

FortiGate's proxy process keeps running; it only drops the TLS sessions it had open. SSL VPN sessions and outbound SSL deep inspection may be affected in the same way; plan a CA import for a maintenance window when the firewall carries them. The dry run names, for each FortiGate, the VIPs that offload SSL — the connections that would be closed — and says when SSL VPN is in use.

A CA import happens only when the chain brings an intermediate the firewall does not hold: usually the first deploy of a certificate from a new CA, or a renewal after the CA moved to a new intermediate. To choose the moment, import the intermediate on the FortiGate in a maintenance window first — CertAutoPilot then reuses it and imports nothing.

Placements​

Placements are optional and only ever add:

  • VIPs — the certificate is added to the VIP's certificate list.
  • SSL inspection profiles — the profile must be in replace mode (Protecting SSL Server). In re-sign mode FortiGate answers success but keeps nothing, so CertAutoPilot refuses the target with FORTIGATE_PLACEMENT and writes nothing — it never changes the mode.
  • SSL VPN — sets the SSL VPN server certificate; the previous one is named in the job log. FortiOS cannot clear this field over the REST API (an empty value is ignored — measured), so switching back is done on the FortiGate.

A VIP or profile that does not exist stops the target with FORTIGATE_PLACEMENT before anything is written.

Ownership​

The local certificate name in the target's VDOM is the identity. When the name already exists on the firewall:

  • tagged for this certificate → updated in place;
  • not tagged (made on the FortiGate) → taken over: updated in place and tagged, warning FORTIGATE_ADOPTED. Its earlier comment is kept after the tag (certautopilot:<id> (was: …));
  • tagged for another CertAutoPilot certificate → FORTIGATE_CONFLICT before any write;
  • a factory certificate → FORTIGATE_VALIDATION;
  • the certificate the management interface serves (admin-server-cert in system global) → FORTIGATE_VALIDATION before any write. Measured: an in-place update of it changes what the management HTTPS interface serves at once, and one refused update left that interface unreachable for minutes.

FortiGate refuses the same certificate under two names. If another object already carries it, the create — or an in-place update — fails with FORTIGATE_VALIDATION naming that object: set the certificate name to it to take it over, or delete it on the FortiGate. A certificate and key that do not match are refused and the object stays unchanged.

Previous object​

Renewals update the same object, so a previous object only exists after the certificate name changed. CertAutoPilot keeps following it until it is deleted or gone:

  • While something still uses it (a VIP, an SSL inspection profile or the SSL VPN), it keeps serving the earlier certificate and is no longer renewed — every run warns FORTIGATE_OLD_CERT_KEPT and names how many settings use it. Move them to the new name.
  • When nothing uses it and delete_old_cert is on, it is deleted (never during a rollback). Only an object carrying this certificate's tag is ever deleted.
  • A rename while the same certificate is current. FortiGate refuses the same certificate under a second name. With delete_old_cert on and nothing using the previous object, it is deleted first and the certificate is created under the new name. Otherwise the run succeeds with FORTIGATE_OLD_CERT_KEPT, the previous object keeps serving, and the new name is used from the next renewal on (the target's placements apply to the new name then).
  • Going back to a version the previous object still carries (typically a rollback after a rename). The current object cannot be updated to it while the previous object exists. Outside a rollback, with delete_old_cert on and nothing using the previous object, it is deleted first. Otherwise the target fails with FORTIGATE_VALIDATION before anything is written, and the message says what keeps the previous object (still used, a rollback, delete_old_cert off) — a rollback never deletes, so delete the previous object on the FortiGate and run the rollback again.
  • The certificate the management interface serves is never deleted.

State​

Per certificate the target records the host, VDOM, firewall serial, object name, leaf fingerprint, the CA objects this certificate added and the placements it wrote. A state recorded on another firewall (serial) or in another VDOM is not applied: the run warns FORTIGATE_TARGET_MOVED and changes nothing there.

VDOMs​

With VDOMs enabled, a certificate written with a VDOM belongs to that VDOM. A VDOM that does not exist answers HTTP 424 (FORTIGATE_VALIDATION); naming a VDOM other than root while VDOMs are disabled is refused before any write (FORTIGATE_VALIDATION).

HA clusters​

Point the target at the cluster management address. A serial change while the unit is in an HA cluster is treated as a failover, not as another firewall.

Pickers​

Three fields can be read from the firewall, on the target form and on a certificate's per-target override row:

  • Certificate name — the local certificates, with the CertAutoPilot certificate that owns each (from its tag). Factory certificates are hidden; each row says whether it is this certificate's, another certificate's (refused) or would be taken over.
  • VIPs — with their type and the certificates they serve today.
  • SSL inspection profiles — with their mode; a re-sign profile is listed with the reason a deploy would refuse it.

Listings are read-only and capped at 500 rows. Every field still accepts a typed value.

Per-distribution overrides​

From a certificate's Distributions → Overrides drawer:

  • cert_name — pins or takes over one object. Accepted on a specific target row only; on the Default row or a group row it is refused, because it names one object on one firewall.
  • placements — VIPs, SSL inspection profiles and SSL VPN; when set, they replace the target's placements as a whole for this distribution. ssl_vpn is refused on the Default row and on group rows: it would switch the SSL VPN certificate of every FortiGate the row reaches (targets added later included), and FortiOS cannot clear that setting over its API.

Precedence, group rows and the list: Per-distribution overrides.

Dry run, validate, health check​

  • Dry run — the same reads and refusals as a deploy (including a certificate already on the firewall under another name, and a missing or malformed credential with its code); lists import CA, create, update in place, add to VIP / profile / SSL VPN, delete previous certificate, and warns FORTIGATE_CONNECTIONS_RESET before a CA import, naming the CA and the VIPs whose open TLS connections it would close. Writes nothing. Shows the FortiOS version and the served management certificate fingerprint.
  • Validate — the object exists in the target's VDOM and carries the expected leaf.
  • Health check — the status and the certificate list are readable; reports version:, serial:, vdom: and tls_fingerprint_sha256:.

Rollback​

A rollback runs the normal deploy with a previous retained version: the same object is updated in place, so every binding serves the older certificate. The previous object is never deleted during a rollback. After a certificate-name change, a rollback to the version the previous object still carries is refused before any write — see Previous object.

Concurrency​

One device identity — fortigate:<host>:<port>, host lower-cased, port 443 when unset — drives the distributed device lock, the serialization of targets on the same firewall inside one run, and fan-out batching (one firewall's targets land in one batch). Different firewalls are deployed in parallel.

Error codes​

CodeClassMeaning
FORTIGATE_CONNECTnetworkConnection, DNS or TLS failure, or an empty / non-JSON answer. Retried.
FORTIGATE_AUTHauthThe token was refused (wrong, expired, revoked, or the address is outside the administrator's trusted hosts), the credential is malformed, or an earlier target of the run had its token refused ("not attempted"). Never retried.
FORTIGATE_PERMISSIONauthHTTP 403 — the admin profile lacks a right (permissions). Not retried.
FORTIGATE_APIio_transientAny other device error. Retried — every write is safe to repeat.
FORTIGATE_VALIDATIONvalidationName too long, factory certificate, the management interface's certificate, certificate and key that do not match, the same certificate already carried by another object (named), a previous object that still carries the version being deployed, unknown VDOM (HTTP 424), a VDOM named while VDOMs are disabled, and the device answers that cannot change on a retry: a named object missing (HTTP 404, -3), a table full (-4, trial licences), an object in use (-23), a value refused (-37), a CA certificate refused as invalid (-146, -324). Usually before any write; when it comes after one (for example after a CA import) the run reports what was changed. Not retried.
FORTIGATE_PLACEMENTvalidationA named VIP or SSL inspection profile does not exist, or the profile is not in replace mode. Nothing written. Not retried.
FORTIGATE_CONFLICTio_permanentThe name holds another CertAutoPilot certificate's object. Nothing written. Not retried.
TLS_TRUST_REFUSEDvalidationThe firewall presented another certificate than the pin, or the trust options could not be applied. Nothing sent.

FORTIGATE_CONFLICT, FORTIGATE_PLACEMENT, FORTIGATE_AUTH, FORTIGATE_PERMISSION and FORTIGATE_VALIDATION before a write do not auto-roll back the healthy targets of the run. Warnings: FORTIGATE_ADOPTED, FORTIGATE_NOT_BOUND, FORTIGATE_TARGET_MOVED, FORTIGATE_OLD_CERT_KEPT, FORTIGATE_CONNECTIONS_RESET — see Warning codes.

Known limitations​

  • The module does not manage HA: point the target at the cluster management address.
  • Evaluation (low-encryption) licence: FortiGate refuses to import any RSA CA certificate above 512 bits (Certificate is invalid. invalid cert format, error -324 — measured, including Let's Encrypt R12); ECDSA intermediates import. The deploy then fails with FORTIGATE_VALIDATION (not retried) and names this cause; nothing else is written. A licensed FortiGate is expected to accept RSA intermediates (not measured here), so RSA chains were tested against a simulated FortiGate only.
  • A CA import can also affect SSL VPN sessions and outbound SSL deep inspection; plan it for a maintenance window (see What interrupts traffic).
  • Error messages from FortiGate can echo the certificate PEM; CertAutoPilot strips it (and the token) before logging.

See also​

Video tutorial

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Deploy Certificates to a Fortinet FortiGate FirewallYouTube ↗