Fortinet

Knocknoc orchestrates Fortinet FortiGate firewalls - directly or via FortiManager - to dynamically control network access by adding or removing IP addresses from lists, which are then used in whatever Firewall rule you like. The orchestration is performed by a Knocknoc orchestration Agent which is subscribed to the central Knocknoc Server. 

The Fortinet ecosystem allows for multiple integration modes, depending on your network architecture, topology, Fortinet products in use and how quickly access changes need to propagate. A high-volume Internet facing environment may suit Passive+ mode best, with an air-gap network benefitting from the one-way nature of Passive mode, with another more suited to Active orchestration directly connected to a Fortigate firewall rather than instructions propagating via a FortiManager. 

Which Mode Should I Use?

If you have a FortiManager - use Passive+.

If you do not have a FortiManager, use Passive+ or Active.

Alternative if you want a data-diode style approach, using Passive is best, however the refresh/polling period for users access could be up to 60 seconds from login, unlike the Passive+ or Active modes where this is near real time.

Comparison of operating modes

	FortiGate firewall(s) Without FortiManager		FortiManager Managing firewalls		Passive mode
Mode	Passive+	Active	Passive+	Trusted-Hosts	Polling mode
Main difference	Firewall talks outbound to the Knocknoc Server	Orchestration agent talks to the firewall (internal)	Firewall talks outbound to  the Knocknoc Server	Does not remove pre-auth exposure	Simple, but polling period affects user experience
What it controls	Firewall IP list	Firewall IP list	Firewall IP list	Trusted Host IP restrictions	Firewall IP list
Propagation time	1–2 seconds	Near real-time	1–2 seconds	Near real-time	Poll interval (minimum 60 seconds)
Requires agent	Yes	Yes	Yes	Yes	No

Option 1 - Passive+ mode

This is the recommended mode for multi‑FortiGate environments when FortiManager is present - the agent only needs connectivity to FortiManager, not to every individual FortiGate, but offers near real time updates of IP address information tied to user login/logout activity.

Passive+ mode combines an EDL (allowlist) with real‑time dynamic entry push. FortiGates poll the Knocknoc allowlist on a schedule for consistency reconciliation, while the agent pushes individual IP entries for near‑instant propagation.

Deploy an Orchestration Agent

Passive+ and Active require an Orchestration Agent to be deployed. This interacts with the Fortinet/Fortimanager device after obtaining instructions from the Knocknoc Server via an outbound subscription to the server. This should be deployed before following the below process. This Agent can be re-used for multiple configurations and devices. Read more here.

Step 1 - Knoc configuration

Select the "Firewalls / Appliances" Knoc configuration, selecting "Passive+"

• Select the Firewalls / Appliances Knoc type

• Choose Passive+ as the Application Type

• Choose Fortinet as the Vendor

• Set "I am using a FortiManager" correctly:

  • Checked = FortiManager managed

  • Unchecked = FortiGate

      

• Here's some context of what we're adding throughout this Passive+ option

• We'll start off by grabbing our FortiGate URL / FortiManager URL's and adding one of them to the config

Step 2 - Create the Admin Profile

FortiManager? Skip this step

If using a FortiGate (no FortiManager):

1. Go to System  > Admin Profile
2. Select System, enable Read/Write.

Step 3 - Create the API user

Create the API user for the Knocknoc Agent to utilize.

• FortiGate (no FortiManager): Create a FortiGate REST API user

• FortiManager: Create a FortiManager API Rest Admin (with Super_User Admin Profile)

• Add the API User API key as the 'Authorisation Token'

Step 4 - Configure external resource

• Navigate to

  • FortiGate: Security Fabric > External Connectors

  • Or FortiManager: Fabric View > External Connectors

• Select Create New and choose IP Address > External Feed

• Set the External Connector name and then add that to our Knoc Configuration

• For FortiManager Only, add the ADOM

• For FortiManager only, add Device Targets you want to include

• For Both FortiGate / FortiManager, add a description

• All details should be filled out now

• Add any other option settings, then submit to get your External Connector details

• Set the Resource URI to the Knocknoc URL provided
• Set the Username and Password (token) under HTTP basic authentication

• Set the polling interval - this is the fallback reconciliation interval; the dynamic push handles real‑time updates, so this does not need to be aggressive
  

Step 5 - Create firewall policy (using external resource)

Create or edit a firewall policy:

• FortiGate: Navigate to Policy & Objects > Firewall Policy

• FortiManager: Navigate to Policy & Objects > Policy Packages > Firewall Policy

• In Source Address, select the external resource you created
• Configure destination, service, and action as appropriate
• Enable/save (FortiGate)
• Commit and push (FortiManager)

Instructions below are for FortiManager only

• Navigate to Device Manager > Device & Groups > Select your chosen FortiGates > Install > Install Wizard > Install Policy Package & Device Settings
• Choose your Policy Package where you stored your firewall rules

Step 6 - Testing

• Log in as a test user

• The user’s IP address should appear on the FortiGate(s) within 1-2 seconds

• Verify the firewall policy permits traffic from the user’s IP

• On logout or grant expiry, the IP is removed and access is revoked

Passive+ Checklist

Your Knoc has the correct settings:

• ✅ "I am using a FortiManager" is set correctly
• ✅ (FortiManager) ADOM and Device Targets are set if needed

Your allowlist details are correct:

• ✅ You noted the allowlist URL
• ✅ You created/selected the allowlist API key
• ✅ Credentials use the separate credentials format (not embedded in the URL)
• ✅ You have IP address restrictions that match the source firewall. Note the firewalls connect to Knocknoc, not the FortiManager

Your FortiGate external resource is correct:

• ✅ External Feed points to the allowlist URL
• ✅ Credentials match the allowlist API key
• ✅ External resource name exactly matches External Feed Name in the Knoc
• ✅ (FortiManager) External resource was created in FortiManager and pushed to FortiGates via Install Wizard

Your policy is correct:

• ✅ Firewall policy references the external resource
• ✅ Incoming and outgoing interfaces reflect the actual traffic path
• ✅ Policy is enabled
• ✅ (FortiManager) Policy package has been pushed to FortiGates

Your push path is correct:

• ✅ Agent can reach FortiGate or FortiManager
• ✅ Device API user exists and is IP-restricted to the agent (not the end user)
• ✅ API user has correct permissions:
  • FortiGate: System > Configuration (Custom) Read/Write
  • FortiManager (GUI): Super_User profile
• ✅ Minimum permissions are used (where possible)

Your testing is verified:

• ✅ External Connector entries appear under Security Fabric > External Connectors on the FortiGate (not under Policy & Objects > Addresses)

Option 2 - Active mode

Active mode has two "targets". Pick the one that matches what you’re trying to control:

• FortiGate (Direct) = controls firewall access by adding/removing user IPs in an address group your policy uses.

• FortiManager (Trusted Hosts) = controls who can log into FortiManager by updating Trusted Host slot 10 for an admin user (not a firewall rule).

Deploy an Orchestration Agent

Passive+ and Active require an Orchestration Agent to be deployed. This interacts with the Fortinet/Fortimanager device after obtaining instructions from the Knocknoc Server via an outbound subscription to the server. This should be deployed before following the below process. This Agent can be re-used for multiple configurations and devices. Read more here.

Step 1 - Create the Knoc in Knocknoc (Active)

• Select the Firewalls / Appliances Knoc type, choosing "Active"
• FortiGate (Direct): Add FortiGate URL, Insecure (if needed)
• FortiManager (Trusted Hosts): Add FortiManager URL, Insecure (if needed)

• Here's some context of what we're adding throughout this Passive+ option

• We'll start off by grabbing our FortiGate URL / FortiManager URL's and adding one of them to the config

Step 2 - Create Admin Profile

FortiManager? Skip this step

• If using FortiGate and no FortiManager: create a custom profile (least privilege)

  • Firewall: Read/Write

  • Everything else: None (or Read Only)

• FortiManager to skip this step

Step 3 - Create the API admin

• FortiGate (Direct): System > Administrators > Create New > REST API Admin

  • Assign the profile from Step 2

  • Restrict Trusted Hosts to the Knocknoc Agent IP

  • Save the API key

• FortiManager (Trusted Hosts): System Settings > Administrators > API Rest Admin

The 'Rest API Administrator User Name' must match your Knocknoc users 'User Name' 

• • Restrict source IP to the Knocknoc Agent IP

  • Save + generate the API key

 Instructions below are for FortiGate only

• FortiGate ONLY (Direct):

  • Navigate to Policy & Objects > Addresses > Address Group > Create New

  • Create a new Address Group (e.g., knocknoc-allowed)
    

• Add a description and that's all the details

Step 4 - Create what Knocknoc will update

• FortiGate (Direct): Policy & Objects > Firewall Policy > Create New 

  • In Source Address, select the address group you created

  • Configure destination, service, and action as appropriate, then save

   

• FortiManager (Trusted Hosts):

  1. Pick the FortiManager admin users you want Knocknoc to control

  2. For each admin user: set Trusted Host 1-9 to 127.0.0.1 (or a controlled backup IP)

     • Do not leave 1-9 as "allow all"

  3. Knocknoc will only write to Trusted Host 10

  4. Knocknoc username must match the FortiManager admin username exactly

Step 5 - Test

• Assign users/groups to the Knoc

• Log in as a test user

• Verify an address object is created and added to the address group

• Verify the policy permits traffic

• On logout/expiry, the address is removed from the group

Limitations

• This applies the built‑in FortiManager Trusted Host restriction. It is an authentication‑layer control, not a network‑level firewall rule.

• It will not prevent exploitation of FortiManager vulnerabilities, as network‑level access to the device is not restricted.

The Knocknoc username must match the FortiManager Administrator username exactly.

Active Checklist

Your Knoc has the correct settings:

• ✅ FortiGate/FortiManager URL is correct
  

Your API user is correct:

• ✅ API user is IP-restricted to the agent (not the end user)
• ✅ FortiGate: Admin profile has Firewall Read/Write (everything else None)
• ✅ FortiManager: Super_User profile

Your configuration is correct:

• ✅ (FortiGate) Address group exists and firewall policy references it
• ✅ (FortiManager) Trusted Hosts 1-9 are controlled (not unrestricted 0.0.0.0/0.0.0.0)
• ✅ (FortiManager) Knocknoc usernames match FortiManager admin usernames exactly (This is a must)

Your testing is verified:

• ✅ (FortiGate) Address objects appear in the address group on login and are removed on logout/expiry
• ✅ (FortiManager) Trusted Host 10 updates on login and clears on logout/expiry

Option 3 - Passive mode (no agent)

In Passive mode, FortiGates periodically poll a Knocknoc‑hosted allowlist (External Dynamic List / EDL) of authenticated user IP addresses and use it in firewall policy. No agent is required.

This mode works with both standalone FortiGates and FortiManager‑managed environments. In a FortiManager‑managed environment, you can configure the external resource and firewall policy via FortiManager policy push to deploy across all managed FortiGates.

Step 1 - Create Knoc in Knocknoc (Passive)

• Select the Firewalls / Appliances Knoc type

• Choose Passive as the Application Type

• For Both FortiGate / FortiManager, add a description

• All details should be filled out now

Step 2 - Configure external resources

• Navigate to

  • FortiGate: Security Fabric > External Connectors

  • Or FortiManager: Fabric View > External Connectors

• Select Create New and choose IP Address > External Feed

• Set the External Connector name and then add that to our Knoc Configuration

• For FortiManager only, add Device Targets you want to include

• Add any other option settings, then submit to get your External Connector details

• Set the Resource URI to the Knocknoc URL provided
• Set the Username and Password (token) under HTTP basic authentication

• Set the polling interval

Step 3 - Create firewall policy (using external resource)

Create or edit a firewall policy:

• FortiGate: Navigate to Policy & Objects > Firewall Policy

• FortiManager: Navigate to Policy & Objects > Policy Packages > Firewall Policy

• In Source Address, select the external resource you created
• Configure destination, service, and action as appropriate
• Enable/save (FortiGate)
• Commit and push (FortiManager)

 Instructions below are for FortiManager only

• Navigate to Device Manager > Device & Groups > Select your chosen FortiGates > Install > Install Wizard > Install Policy Package & Device Settings
• Choose your Policy Package where you stored your firewall rules

Step 4 - Testing

• Log in as a test user

• The user’s IP address should appear on the FortiGate(s) within 5 minutes (or your chosen interval)

• Verify the firewall policy permits traffic from the user’s IP

• On logout or grant expiry, the IP is removed and access is revoked

Passive Checklist

Your Knoc has the correct settings:

• ✅ Application Type is Passive

Your external resource is correct:

• ✅ External Feed points to the allowlist URL
• ✅ Credentials use the separate credentials format (not embedded in the URL)
• ✅ (FortiManager) External resource was pushed to FortiGates via Install Wizard

Your policy is correct:

• ✅ Firewall policy references the external resource
• ✅ Policy is enabled
• ✅ (FortiManager) Policy package has been pushed to FortiGates

Your testing is verified:

• ✅ EDL entries appear under Security Fabric > External Connectors on the FortiGate

API role/permissions summary

Troubleshooting

Agent logs

If you are experiencing issues, the first step is checking the orchestration agent logs. Common problems include:

• Invalid API key: The API token may have been regenerated or expired
• Network connectivity: The agent cannot reach the FortiGate or FortiManager
• Incorrect External Feed Name: The name configured in Knocknoc must exactly match the external resource name on the FortiGates (Passive+ modes)
• ADOM mismatch: If using multi-ADOM mode, ensure the ADOM in Knocknoc matches the ADOM where your devices are managed (FortiManager modes)
• Insufficient permissions: FortiManager API users require the Super_User admin profile for Active mode, or a custom least-privilege profile for Passive+ mode - see API Permissions

Push failures are non-fatal (Passive+ modes)

If the dynamic entry push fails, the agent logs a warning but does not fail the grant/revoke operation. The FortiGates will pick up the change on their next scheduled poll of the allowlist. Check agent logs for "passive+ dynamic entry push failed" or "direct FortiGate dynamic entry push failed" messages to diagnose push issues.

FortiGate is not updating (Passive / Passive+ modes)

• Verify the external resource is configured correctly on the FortiGate and is successfully polling the Knocknoc allowlist URL
• Check that the API key / credentials for the allowlist are correct
• Verify the FortiGate can reach the Knocknoc server over HTTPS
• On FortiGate, run diagnose system external-resource list to see external resource status
• Run diagnose system external-resource show <name> to see the current entries

Device Targets not working (Passive+ FortiManager)

If using Device Targets to scope the push to specific devices:

• Ensure the serial numbers or group names exactly match the devices configured in FortiManager
• Targets are referenced as adom/{adom}/device/{serial} in the API call
• If left empty, the default target is All_FortiGate in the configured ADOM

Trusted host not updating (Active FortiManager)

• Verify the Knocknoc username matches the FortiManager Administrator username exactly
• Check that trusted host entries 1–9 are not set to 0.0.0.0/0.0.0.0 (this would mask any changes to entry 10)
• Verify the API user has the Super_User admin profile (see API Permissions)
• Check agent logs for error code 202051 (admin user not found)

FortiManager non-super-admin

If you do want to use complete least privilege for FortiManager specifically, you can add these permissions to a custom profile:

config system admin profile
edit "knocknoc-passiveplus"
set device-manager read-write
set rpc-permit read-write
next
end

Error Codes

The Knocknoc orchestration agent reports structured error codes when Fortinet operations fail. These codes appear in agent logs and are surfaced to the Knocknoc server.

Error codes are formatted as (agent error #NNNNN) description in log output.

Connection and Authentication (202000-202049)

Code	Description	Common Causes
202000	Failed to connect to Fortinet device	Device is unreachable - check network connectivity, hostname, and port
202001	Authentication failed	Invalid or expired API key (HTTP 401)
202002	Authorization failed (insufficient permissions)	API user lacks required role or does not have access to the target ADOM (HTTP 403, or JSON-RPC status -5)
202003	TLS/SSL certificate error	Certificate is self-signed, expired, or hostname mismatch - enable Insecure if using an untrusted CA
202004	Connection timed out	Network timeout - check firewall rules and routing

Trusted Host Management - Active FortiManager (202050–202099)

Code	Description	Common Causes
202050	Failed to update trusted host	The JSON-RPC call to update the admin user's trusted host entry failed
202051	Admin user not found on FortiManager	The Knocknoc username does not match any administrator account on FortiManager (JSON-RPC status -2)

Dynamic Entry Push - Passive+ Modes (202100-202149)

Code	Description	Common Causes
202100	Failed to push dynamic entry	The push call failed - this is non-fatal; FortiGates will reconcile on next poll
202101	Target device or group not found	The Device Targets configuration references a device or group that does not exist in the ADOM (JSON-RPC status -2)
202102	External feed name not found on target FortiGates	The External Feed Name does not match any external resource configured on the target FortiGates

Response Parsing (202150-202199)

Code	Description	Common Causes
202150	Invalid or unexpected response	The response body could not be parsed as JSON, or the response structure was not in the expected format

FortiManager Status Codes

The agent maps FortiManager's API status.code values to the error codes above:

JSON-RPC Status	Meaning	Mapped Error Code
0	Success	-
-2	Object not found	202051 (admin user) or 202101 (proxy target)
-5	No permission	202002
-6	Invalid parameters	202150
-10	Invalid session ID	202001
-11	No permission (no session)	202002

Fortinet Documentation References

• Configuring an external feed - FortiOS external resource / threat feed setup
• Creating administrators for the FortiManager API - API user creation
  
• FortiManager authentication token for API administrators - API key generation
• Trusted hosts - FortiManager trusted host restrictions
• Administrative Domains (ADOMs) - FortiManager ADOM configuration