Description
This article describes Fortinet Single-Sign-On (FSSO) and its components in easily understood terms. It does not aim to provide a complete configuration guide.
It expands on introductory documentation as found FSSO - Fortinet Single Sign-On or FSSO.
Scope
FortiGate, FortiProxy, FortiAuthenticator, FSSO Agents.
Solution
Fortinet Single-Sign-On (FSSO), also known as FortiGate Server Authentication Extension (FSAE) in early documentation, is a method by which user logins are detected and shared with Fortinet devices, typically FortiGates, but also FortiProxy. This is most frequently used in a Windows AD environment.
An FSSO setup consists of various components. These may include:
| FortiGate/FortiProxy | It receives FSSO logins (usually from the Collector Agent), and uses FSSO groups in policies to allow/deny traffic accordingly. It can also act as a Collector Agent in a VERY limited capacity. |
| Collector Agent | An agent (usually hosted on a Windows Server) that can detect user logins through various methods |
| FortiAuthenticator | Acts as Collector Agent in this context; it can detect user logins through various methods, some of which are exclusive to FortiAuthenticator |
| DC Agent | Domain Controller Agent; a small agent that runs on Windows Domain Controllers and reads login activity from LSASS (Local Security Authority Subsystem Service), which it then sends to Collector Agent |
| TS Agent | Terminal Server Agent; an agent that runs on Terminal Servers (such as Citrix deployments), detects login activity and sends it to Collector Agent; it assigns port-ranges to users |
| Mobility Agent | A standalone agent or feature set on FortiClient; it runs on endpoints directly and reports user logins to FortiAuthenticator, but does NOT work with regular Collector Agent |
Note: The reminder of the article speaks primarily of FortiGate, but FortiProxy is essentially identical in function in this regard.
Broadly, login information is collected by and maintained on a Collector Agent. The Collector Agent shares the login information with any connecting FortiGate, which can then use the login information to match user traffic to various policies.
FSSO is principally an IP-based authentication method; a user is associated with one or more IPs, and any traffic coming from those IPs is treated by FortiGate as coming from the authenticated user. Only one user may exist per IP (except TS Agent), but multiple IPs may be associated with one user.
- Initial Setup.
Setting up FSSO usually starts with either a Collector Agent or FortiAuthenticator.
The Collector Agent must be installed on a host server; FortiAuthenticator needs to have FSSO services enabled on its interfaces, and various methods enabled in the FSSO General settings.
FortiGate needs to be configured to connect to Collector Agent or FortiAuthenticator. It does so via an External Connector (under Fabric Connector). Up to five Collector Agents may be defined in a single connector for redundancy purposes. FortiGate connects to them in a round-robin fashion, and only fails over to the next if the first Collector Agent is unresponsive. It will then persist with that agent, even if the first one should become available again.
Group filters apply to this connection, meaning only user logins that are members of the specified groups will be sent to FortiGate. The Collector Agent or FortiAuthenticator may list more FSSO logins than are forwarded to FortiGate.
The group filter may be configured on FortiGate directly or on Collector Agent/FortiAuthenticator. These are also called standard mode (group filter set on Agent/Authenticator) or advanced mode (group filter set on FortiGate). In standard mode, groups are expressed in standard Windows 'Domain\Group' format; in advanced mode, groups follow LDAP syntax like 'CN=group, OU=org, dc=domain, dc=suffix'.
The modes should not be mixed!
Note: The Collector Agent will run under a service account (usually also the installing account, unless otherwise specified), and use this for all interaction with the domain. The service account should be set with a non-expiring password.
Further reading:
- Technical Tip: How to install FSSO Collector Agent
- Technical Tip: Restricting a Fortinet Single Sign On Agent Service (FSSO) service account
- FortiGate: FSSO
- Technical Tip: FSSO Group Filter configured on Collector Agent
- FortiGate: Fortinet single sign-on agent
- FortiAuthenticator: FortiGate filtering
- Technical Tip: How to switch FSSO operation mode from Standard Mode to Advanced Mode
- Login Detection.
Once a Collector Agent or FortiAuthenticator is prepared and connected to FortiGate, it needs to detect user logins. Most commonly, FSSO is set up to detect Windows domain logins (logging into a workstation, accessing a network drive, accessing Outlook, etc.). This can cause issues with external users (connected via VPN, or non-domain users), as those will generate fewer or no domain logins at all. VPN logins themselves generally are NOT domain logins, even if domain credentials are used.
There are various methods available to detect logins:
- Agents.
DC Agent, TS Agent, and Mobility Agent detect logins on the servers/endpoints they are running on and forward those logins to Collector Agent or FortiAuthenticator.
DC Agents report the username and IP and/or workstation name and only detect Windows domain logins.
TS Agents report usernames and assigned port range of users logging into the Terminal Server itself, typically domain users as well. Users on a Terminal Server all share the same IP, so users are distinguished based on assigned port ranges instead of IP.
Mobility Agent (FSSOMA or SSOMA), standalone or as a FortiClient feature, reports the username and any local interface IP of the endpoint to FortiAuthenticator, which may require a separate license.
It can be used to detect VPN users but requires the users to be domain users as well. Mobility Agents cannot report to regular Collector Agents. Mobility Agent can integrate with Entra ID-joined workstations, or in a hybrid environment.
Further reading:
- Technical Tip: Configure FSSO in DC Agent mode
- Technical Tip: FortiAuthenticator FSSO with DC Agent
- FortiAuthenticator: FortiClient SSO Mobility Agent
- FortiAuthenticator: SSOMA for native Microsoft Entra ID joined workstation
- FortiClient XML Reference: SSOMA configuration
- Polling.
Polling mode is a method by which Collector Agent or FortiAuthenticator poll specified domain controllers for user logins.
This usually means the agent or authenticator accesses the Windows Security Event Log on a polled domain controller and looks for events generated by user login activity, meaning only Windows domain logins are detected. VPN users may not be picked up by polling mode, or only belatedly.
The Event IDs that Collector Agent or FortiAuthenticator look for can be found here: Technical Tip: Windows event IDs used by FSSO in WinSec polling mode.
FortiGate is also able to poll Domain Controllers directly, without requiring a Collector Agent. This is frequently called 'agent-less FSSO'.
FortiGate can only poll a very limited set of Event IDs, however, and it does consume additional resources on FortiGate, so agent-less FSSO is not recommended for larger deployments.
Further reading:
- Technical Tip: FSSO Agent in polling mode
- FortiAuthenticator: Windows event log sources
- Technical Tip: FSSO choose between DC Agent mode or Polling mode
- Technical Tip: Comparison between DC-Agent mode and polling mode
- Technical Tip: FSSO local poller (FSSOD) limitations compared to FSSO collector agent.
- Troubleshooting Tip: How to troubleshoot FSSO agentless polling mode issue
- RADIUS Accounting, Syslog.
Collector Agent and FortiAuthenticator can both be set up to receive syslog messages or RADIUS Accounting packets and parse the log/packet to identify username and user IP. This information can then be turned into an FSSO login session.
This (or Mobility Agent) is the usual solution for VPN users; the VPN gateway, whether FortiGate or a third-party product, may be configured to send syslog messages or RADIUS accounting packets to Collector Agent or Authenticator, which can then be set up to parse the information and generate FSSO logins.
Further reading:
- FortiGate: FSSO using Syslog as source
- FortiAuthenticator: Syslog sources
- FortiGate: Agent-based FSSO, RADIUS Accounting
- FortiAuthenticator: RADIUS accounting sources
- Technical Tip: Configure Fortinet Single Sign On (FSSO) for SSL-VPN users via Syslog
- Portals, API.
FortiAuthenticator can provide a variety of portal services, such as a captive portal, self-service portal, or SAML authentication. If a user logs in on some of these portals, the FortiAuthenticator can also generate an FSSO session from the user authentication.
FortiAuthenticator also offers an API that can generate FSSO sessions based on information posted to it.
Note: For SAML, FortiAuthenticator functions as a Service Provider (SP), NOT an Identity Provider (IdP).
Further reading:
- FortiAuthenticator: FSSO Portal Services
- FortiAuthenticator: FSSO SAML authentication
- FortiAuthenticator API: SSO authentication
- Login processing.
Once logins have been detected, some additional processing has to take place. This includes checking ignore lists, looking up group memberships of newly detected users, and DNS lookup, if no IP information is present.
- DNS lookup.
Collector Agent or FortiAuthenticator may be required to look up workstations via DNS. This happens if logins detected via polling or DC Agent only contain user and workstation information, but no IP. As FSSO is IP-based authentication, an IP is required for the user login. If no IP can be found, the user login is discarded.
FortiAuthenticator uses the DNS servers set under System -> Network -> DNS to this end.
Collector Agent uses its host's system DNS by default but may have other DNS servers specified.
DC Agent is also capable of looking up workstations via DNS before forwarding login information to Collector Agent or FortiAuthenticator.
Further reading:
- Technical Tip : How FSSO Collector Agent performs name resolution.
- Technical Tip: Disable the DNS resolution of the FSSO DCAgent
- Ignore Lists.
Collector Agent and FortiAuthenticator can be configured to ignore certain IP ranges or users.
Some user accounts, such as service accounts, should be excluded to prevent those accounts from replacing existing user logins on the same IP. Some IP ranges should be excluded to prevent FSSO logins from interfering with other authentication, such as VPN, for example.
Logins associated with an ignored IP and/or user are discarded.
Further reading:
- Technical Tip: Excluding IP addresses from FSSO logon events.
- Technical Tip: How and why to use the 'Ignore User List' option in FSSO Collector Agent
- Technical Tip: FSSO Filtering (FSSO Global Pre-Filter on FortiAuthenticator)
- Group lookup.
After a login has been detected and is not discarded due to an ignore list or DNS failure, FortiAuthenticator or Collector Agent needs to determine the user's group memberships. This is usually done as a lookup to LDAP.
FortiAuthenticator uses the LDAP Server(s) configured under Authentication -> Remote Auth Servers -> LDAP.
The Collector Agent uses the LDAP server configured under 'Directory Access Information'.
For logins detected via syslog or RADIUS Accounting, the group information may instead be parsed from the same log or accounting packet, if the log/accounting packet contains the group information.
Based on the group membership information, logins are then forwarded to FortiGate(s) with at least one matching group filter.
At this stage, logins are present on FortiGate, as are FSSO groups.
The FSSO groups can be set as filters in firewall groups, or used outright in firewall policies. Any traffic coming from an IP with an authenticated FSSO user and the correct group memberships may match into policies with the FSSO/Firewall groups that include the group object.
- Login maintenance.
FSSO logins require some maintenance to ensure they stay up to date. This falls into two categories, verifying IP and verifying user login.
Note: Agentless FSSO (local poller on FortiGate) does NOT perform any login maintenance!
- Verifying IP.
FSSO detection mechanisms are intended to detect new logins only. This means if a user changes IP in such a way that no new login is generated, the new IP is not associated with the FSSO user, and traffic may be blocked.
To this end, IP verification can be enabled. This essentially consists of queries to DNS servers every minute to look up IPs of all workstations. If additional or changed IPs are detected, Collector Agent or FortiAuthenticator updates the existing FSSO login accordingly and provides that information to FortiGate.
This does require that the DNS server(s) in question have up-to-date entries for each workstation at all times.
Further reading:
Technical Tip: Optimization of FSSO workstation IP address verification
- Verifying a logged-in user.
As Windows environments do not generate logoff events, a user may have logged off from a workstation without the Collector Agent/FortiAuthenticator detecting it. The FSSO session persists even though the user is already logged off.
To this end, workstation verification can be enabled. FortiAuthenticator or Collector Agent uses WMI to connect to each workstation and query it for the logged-on user. If no or a different user is returned, the FSSO session is updated accordingly.
If the WMI query fails, the FSSO session is in status 'Not Verified' and times out eventually; by default, it does so after eight hours.
Further reading:
- Troubleshooting.
Sometimes, there can be issues with FSSO - users may get logged off when they should not be, incorrect IPs are detected, FSSO is slow in processing logins, etc.
In that case, the following should be checked:
Configuration:
Ensure FortiGate, Collector Agent, FortiAuthenticator, etc are configured correctly. Check DNS servers, LDAP connection, pre-shared key, and encryption settings.
Make sure the Collector Agent was installed with the correct permissions.
Ensure the service account has the correct permissions and the password is not expired.
Network:
Ensure FortiGate, the Agent, the Authenticator, etc can reach each other. Make sure these ports are allowed:
- TCP 8000: used for unencrypted communication between FortiGate and CollectorAuthenticator; Authenticator also uses it for encrypted communication.
- TCP 8001: used for encrypted communication between FortiGate and Collector; used for encrypted communication between Mobility Agent and Authenticator.
- UDP 8002: used for unencrypted communication between DC/TS Agent and Collector/Authenticator.
- TCP 8003: used for encrypted communication between DC/TS Agent and Collector/Authenticator.
If custom ports are configured in FortiGate/Collector Agent/Authenticator, ensure the same custom ports are configured on each component, and those ports are allowed.
Also ensure that the same ports are allowed in Windows Firewall on any server running a DC Agent, TS Agent or Collector Agent; ensure both inbound and outbound traffic is allowed.
Check whether there is a deep inspection between FortiGate and the Collector Agent/FortiAuthenticator.
Make sure routing tables, IPs, etc are correct.
Collector Agent/FortiAuthenticator:
Check all the expected logins are present.
Test if there is a delay between receiving logins and processing them.
Check whether there are any errors in the FSSO log.
Make sure the system times are correct.
All the links listed above can be cross-referenced for configuration details and more in-depth troubleshooting.
