Setting up the FortiGate

Matrix talks to the FortiGate's REST API (/api/v2/cmdb/…) with the token of a REST API administrator. This page is for the FortiGate's administrator. The examples use FortiOS 7.4 CLI; menu names and permission groups can differ between FortiOS versions, so verify the result with the check below.

Room policies

Matrix manages policies that you create and name; it never creates or deletes policies.

One IPv4 policy per room, all with the same direction: one source interface or zone (for example the students' zone Students) to one destination interface or zone (for example the SD-WAN zone INTERNET). Exactly one entry in srcintf and one in dstintf.
Names that follow one pattern with the room code in it, for example Internet Access for SB3-401, Internet Access for FB-102, Internet Access for HAC-202. The firewall's policy name pattern must match exactly these names and nothing else.
The source (srcaddr) of each room policy names the room's address group; its members are /32 address objects, one per computer (ipmask, mask 255.255.255.255). To let Matrix change them, a group must be used only by its room policy, without exclusions or nested groups, and each computer's object must be in that group only (Addresses and groups → What can be edited).
New room policies are picked up at the next report; there is nothing to restart. The policy's real policyid is used, whatever the room number.

Later ACCEPT policies defeat a disabled room

If an enabled ACCEPT policy after the room policies, with the same direction, also matches the rooms' computers (source all, or a network or group containing them), traffic of a disabled room falls through to it and still reaches the internet. Take the managed addresses out of such general policies, or add a suitable blocking policy after the rooms. Matrix reports such policies (later_accept_policy) but never changes them. Also consider IPv6 and other ways out, and that students may change their computer's IP.

Check firewall-session-dirty (globally, config system settings, or per policy): with check-all, established sessions are re-evaluated after a policy change, which does not guarantee that they are cut.

Allowed sites

Allowed sites are domains a room can still reach while its internet is off. Matrix never creates policies or groups: you create them once, and Matrix then only changes the groups' members. Allowed sites → FortiGate setup (tenant admins) shows the CLI for whatever is missing, with this firewall's interfaces and room groups:

What	Address group	ACCEPT policy
Shared list (every room)	`Matrix allowed sites`	srcaddr: every room's address groups; dstaddr: `Matrix allowed sites`
A room's own list (optional)	`Matrix allowed sites <room>`	srcaddr: that room's groups; dstaddr: its group

Example (shared list and SB1-102's own list; the # lines are comments that the FortiGate CLI ignores):

# Entrosity Matrix: allowed sites setup.
# Run as a super_admin in the FortiGate CLI, in VDOM "root". When VDOMs are enabled, enter it first:
#   config vdom
#   edit "root"
# New policies are appended at the end of the policy list: move each one above any DENY policy of
# "Students" -> "INTERNET" (config firewall policy / move <new id> before <deny id> / end).
# Check that "set nat" matches the room policies (change it when they do not use NAT).
# Wildcard domains (*.example.com) only work when the FortiGate sees the clients' DNS queries.
config firewall addrgrp
    edit "Matrix allowed sites"
        set member "none"
        set comment "Entrosity Matrix: allowed sites of every room"
    next
    edit "Matrix allowed sites SB1-102"
        set member "none"
        set comment "Entrosity Matrix: allowed sites of SB1-102"
    next
end
config firewall policy
    edit 0
        set name "Matrix allowed sites"
        set srcintf "Students"
        set dstintf "INTERNET"
        set action accept
        set srcaddr "SB1-102-Students address" "SB1-108-Students address"
        set dstaddr "Matrix allowed sites"
        set schedule "always"
        set service "ALL"
        set nat enable
        set logtraffic all
        set comments "Entrosity Matrix: allowed sites while a room's internet is off"
    next
    edit 0
        set name "Matrix allowed sites SB1-102"
        set srcintf "Students"
        set dstintf "INTERNET"
        set action accept
        set srcaddr "SB1-102-Students address"
        set dstaddr "Matrix allowed sites SB1-102"
        set schedule "always"
        set service "ALL"
        set nat enable
        set logtraffic all
        set comments "Entrosity Matrix: allowed sites of SB1-102"
    next
end

An address group cannot be empty: an empty list holds FortiGate's built-in address none, which matches nothing. Matrix replaces it with the first domain and puts it back when the last one is removed.
edit 0 appends the policies at the end of the policy list. The order relative to the room policies does not matter (an enabled room policy matches first; a disabled one lets the traffic fall through to these), but they must be above any DENY policy of the same interfaces that would catch the traffic: move <id> before <id>.
Match nat to the room policies. service may be narrowed to HTTP HTTPS DNS; Matrix finds the policies by their destination group, not by name, so you may rename them.
The CLI covers only what is missing. Rooms without a known address group are skipped with a warning, and policy names are cut to 35 characters (the FortiOS limit).
FortiGates set up with an earlier version also have the group Matrix Entrosity services as a second destination of the shared policy. Matrix no longer uses it; an admin can remove it (Troubleshooting → Removing the old Entrosity services group).
A room added later must also be added to the shared policy's sources; the check warns when a policy does not cover every room (sites_policy_not_covering).
Wildcard domains (*.example.com) only work when the FortiGate sees the computers' DNS queries: the FortiGate is their DNS server, or DNS passes through it.
The API administrator's profile already covers it (Firewall → Address read/write): Matrix creates fqdn objects matrix-site:<domain>, sets the groups' members, and deletes only its own objects that nothing uses any more.

REST API administrator

Access profile

Give the administrator only what Matrix uses:

What Matrix does	FortiGate API	Permission
Check the direction	`system/interface`, `system/zone`, `system/sdwan` (GET)	Network configuration: read
Read and switch room policies	`firewall/policy` (GET, PUT of `status` only)	Firewall → Policy: read/write
Read computers, change IPs, add computers; allowed sites	`firewall/address` (GET, PUT, POST, DELETE of Matrix's own unused FQDN objects), `firewall/addrgrp` (GET, PUT of `member`)	Firewall → Address: read/write
Everything else	–	none

Without address changes (Allow changing and adding computers off), Firewall → Address can be read only; Matrix still needs to read every address, group and policy to decide what is editable and to warn about later ACCEPT policies.

config system accprofile
    edit "entrosity-matrix"
        set netgrp read
        set fwgrp custom
        config fwgrp-permission
            set policy read-write
            set address read-write
        end
    next
end

A token cannot be limited to certain policies

FortiGate cannot restrict an API token to single policy IDs: the token can change any policy the profile allows. Matrix enforces its own strict allowlist (pattern, exact direction, VDOM, a re-read before every write, only the status field, the local guard). Keep the profile minimal and the token on the connector computer only.

The administrator

Trusted hosts: only the connector computer's IP address as the FortiGate sees it (after NAT, if any). Nothing else.
VDOM: only the rooms' VDOM (for example root).
PKI group / CORS: not needed.

config system api-user
    edit "entrosity-matrix"
        set comments "Entrosity Matrix connector"
        set accprofile "entrosity-matrix"
        set vdom "root"
        config trusthost
            edit 1
                set ipv4-trusthost 192.0.2.50 255.255.255.255
            next
        end
    next
end
execute api-user generate-key entrosity-matrix

192.0.2.50 is an example: use the connector computer's address. The last command prints the token once: store it in Matrix (Firewalls → API token) and do not keep other copies. To rotate, run execute api-user generate-key again and store the new token.

Management access

The connector reaches the FortiGate's HTTPS management port from the administration network. Student VLANs must reach neither the FortiGate's management port nor the connector computer: check it from a real student network.
Certificate: Matrix verifies the FortiGate's TLS certificate by default. Give Matrix the CA that issued it (CA certificate (PEM)), or install a certificate the connector computer trusts. Switch verification off only if you have no CA yet; the connection is still encrypted, but the FortiGate's identity is not checked.

Verify

Before switching changes on:

Run Check on the firewall's page (Firewalls → Check), or on the connector computer matrix-connector check --config local.json, which only sends GET requests (Matrix connector → Offline check). It must show the version, Direction … confirmed, the expected rooms and groups, and no warnings you have not accounted for.
auth_failed on the check means the token is wrong, the profile lacks a read permission, or the connector's IP is not a trusted host.
Whether the profile really allows the writes is only shown by a write. Agree on a test room (and, for addresses, a test computer and group), switch changes on, and switch that room off and on, then change that computer. A write the profile refuses is sent and answered with HTTP 403, so it shows as Unconfirmed (the connector does not assume that nothing happened); after Refresh the room is unchanged and the history's detail names auth_failed. Widen the profile and try again.

Room policies​

Allowed sites​

REST API administrator​

Access profile​

The administrator​

Management access​

Verify​