Technical Guide: A detailed guide to FSSO Mobility Agent

Description

This article describes what the FSSO Mobility Agent is, and how to install and use it. The article also details limitations and provides steps for troubleshooting.

Scope

FortiAuthenticator, FortiClient.

Solution

FSSO (Fortinet Single Sign-On) is a method that allows FortiGates to reuse user logins from other sources (usually Active Directory). One of the more precise sources for login information is the dedicated Mobility Agent, or using FortiClient with the Mobility Agent feature set enabled.

Table of Contents:

• Introduction
• How Mobility Agent works
• How to configure FortiAuthenticator
• How to install the Mobility Agent
• How to configure the Mobility Agent
• How to verify that Mobility Agent sends information
• Forwarding Mobility Agent logins to FortiGate
• Troubleshooting
• Related documents

Introduction:
The FSSO Mobility Agent is an agent running on individual workstations. It reports the logged-in user, domain information, and any interface IPs to a specified FortiAuthenticator. It can run in local Windows AD environments or Entra ID environments.
Note: Mobility Agent requires the use of a FortiAuthenticator with a specific add-on license. It does not work with the FSSO Collector Agent.

The Mobility Agent exists in three different versions:

1. As a feature of a fully-licensed FortiClient,
2. As a feature in the VPN-only (unlicensed) version of FortiClient,
3. Or as a standalone SSO Mobility Agent (only Windows).

As a VPN-only or fully-licensed FortiClient, the Mobility Agent is available on Windows workstations, Windows Servers, and macOS endpoints. It is not available on Linux workstations, iOS, or Android. The standalone version only runs on Windows OS. More information can be found here: FortiClient feature comparison.

On a fully-licensed FortiClient, the mobility agent feature can be enabled via EMS. EMS also specifies the FortiAuthenticator IP or hostname to which the login information should be sent. FortiClient EMS and FortiAuthenticator itself do not communicate with each other directly.
On a VPN-only version of FortiClient, the mobility agent feature can be toggled on manually under Settings -> Advanced:

Note: The FortiClient must be unlocked for the feature toggle to be available.

The standalone SSO Mobility Agent does not have a graphical interface. The FortiAuthenticator IP or hostname can be specified during installation as outlined in this article: Technical Tip: How to install a standalone Windows FSSO Mobility Agent. Alternatively, the FortiAuthenticator hostname or IP can be set via registry after installation.

How Mobility Agent works:

Mobility Agent reports the username, domain information, and local interface and VPN tunnel IPs to FortiAuthenticator via a short-lived TCP session. It then reports any changes (like a change in IP) on demand, and sends a keep-alive every few minutes (the interval is determined by FortiAuthenticator).

FortiAuthenticator can maintain up to 2048 TCP sessions with Mobility Agents in parallel; as these TCP sessions are of short duration, in effect, FortiAuthenticator can manage SSO logins for a larger number of Mobility Agents. If a Mobility Agent is not able to connect, it will retry after a few seconds.

How to configure FortiAuthenticator:
For FortiAuthenticator to receive and process updates from Mobility Agent, the Mobility Agent service must be enabled under Fortinet SSO -> Settings -> Methods:

The settings include specifying a port (TCP 8001 is the default, but this overlaps with the FSSO SSL port used by FortiGate!) and configuring a preshared key, as well as a keep-alive interval and timeout.

Important: FortiAuthenticator requires an additional license to accept more than five FortiClient (Mobility Agent) connections at a time! The maximum number of connections it accepts is either the number of licensed FortiClient workstations or the number of licensed users, whichever is lower, as laid out in this article: Troubleshooting Tip: FortiClient SSO Mobility Agent license count too low. A Mobility Agent may report multiple (interface and VPN tunnel) IPs, which count as individual SSO sessions, but only consume one FortiClient license count. The SSO session limit is identical to the licensed user limit.

In an active-passive or load-balancing cluster, both nodes require their own licenses.

Example cases:

• A 200-user license and 100 FortiClient license means that FortiAuthenticator will accept a total of 100 different FortiClients, and have a limit of 200 FSSO sessions total.
• A 100-user license and a 200 FortiClient license mean that FortiAuthenticator will accept a total of 100 different FortiClients, and have a limit of 100 FSSO sessions total.
• A FortiClient reporting 3 different IPs (VPN tunnel, LAN interface, Wi-Fi interface) to FortiAuthenticator consumes 3 SSO sessions, and 1 FortiClient license count

For more information on licensing, including Mobility Agent licenses, limits, and clustering, see Licensing.

In FortiAuthenticator High Availability Setups, additional configuration may be required.

In active-passive clusters, both the Mobility Agent-related configuration and current FSSO sessions are synchronized, so a failover should be seamless and not result in any loss of FSSO Session information unless the failover takes more than five minutes to complete for some reason (FortiGate discards FSSO sessions if it loses connection to the FSSO Collector Agent/FortiAuthenticator for more than five minutes).

In load-balancing cluster setups, FSSO configuration is not synchronized by default and may need to be manually mirrored on load-balancing nodes. FSSO sessions are also not synchronized. Mobility Agent can either report logins to multiple FortiAuthenticators (as long as all use the same preshared key), or hierarchical FSSO (Tiering) may be set up for FortiAuthenticators to share SSO session information.

More information on load-balancing cluster setup and FSSO Tiering may be found here:

• Technical Tip: How to configure FortiAuthenticator load-balancing cluster
• Technical Tip : FortiAuthenticator and Single-Sign-On (SSO) Tiered Architecture 

How to install the Mobility Agent:
The mobility agent can either be installed as part of a FortiClient rollout, and the feature simply needs to be enabled afterward, or as a standalone SSO version.
The mobility agent can be downloaded from support.fortinet.com. All three versions are found in the FortiClient download directory.

• FortiClientSetup_[...] is the full version, requiring a FortiClient EMS license to operate.
• FortiClientVPNSetup_[...] is the VPN-only version, requiring no EMS license.
  
• FortiClientSSOSetup_[...] is the standalone Mobility Agent without a GUI.

Note: Only one FortiClient version can be installed on an endpoint at a time. As the FortiPAM client is technically a variation of FortiClient, it is not possible to install the FortiPAM-specific client and another version, like VPN-only or standalone Mobility Agent. In case both PAM-support and Mobility Agent are required, this guide may be followed: Add FortiPAM agent to SSOMA. More information on installing FortiClient or a standalone Mobility Agent may be found in the following documents:

• Initially deploying FortiClient
• Manually installing FortiClient 
• Technical Tip: How to install a standalone Windows FSSO Mobility Agent

How to configure the Mobility Agent:
The Mobility Agent, no matter which version, does not require significant configuration. It needs to know the FortiAuthenticator IP or hostname, what port to use (TCP/8001 is the default), and the preshared key for the connection. FortiClient/Mobility Agent is able to send login information to multiple FortiAuthenticators, but only if they all use the same preshared key.

On EMS, the settings can be added to the FortiClient's endpoint profile via XML. A more detailed guide can be found here: Configuring SSOMA with AD.

Information on the available XML tags can be found here: SSOMA 

FortiSASE endpoint profiles can also enable the Mobility Agent feature.

On VPN-only FortiClients, the settings can be made via GUI, editing the configuration backup XML tags, or editing the related registry keys on Windows workstations.

On standalone mobility agents, the settings can be configured either during installation with CLI parameters as outlined in the article above, or by editing the registry afterward. The registry keys are located in this registry hive: 'HKEY_LOCAL_MACHINE\SOFTWARE\Fortinet\FortiClient\FA_SSOMA'.

In the case of an Entra ID or hybrid environment, some additional configuration may be necessary so FortiAuthenticator can process the logins properly.

In particular, the FortiClient or standalone Mobility Agent may need to have the 'prefer_azure' option enabled (in registry or XML configuration), and FortiAuthenticator must have an OAuth server entry configured for Azure Directory so it can look up group information. Tenant ID and domain name may also need to be specified in SSO Methods on FortiAuthenticator.

More information can be found in Use Case B listed here: Configuring SSOMA with AD.

How to verify that the Mobility Agent sends information:
Once Mobility Agents are deployed and send login information, the logins should start showing on FortiAuthenticator under Monitor -> SSO > SSO Sessions. The login source should show as Mobility Agent.

If this is not the case, the connection between Mobility Agent and FortiAuthenticator can be checked with the following tools:

1. Packet capture on FortiAuthenticator to verify it receives traffic, in particular, filtering on the port used for Mobility Agent communication. Information on how to take a packet capture on FortiAuthenticator can be found here: Technical Tip: How to run a Packet Capture with FortiAuthenticator.
2. Debug logs for FSSO may be found under https://<FortiAuthenticator>/debug/fsso-agent/. The debug level is set in the GUI under Fortinet SSO -> Settings -> Log Config. Changing the debug level restarts the FSSO service.
3. Logs on FortiClient/Mobility Agent side; these can be found in the installation directory.
4. Global pre-filter on FortiAuthenticator, to ensure the login is not filtered out.

Forwarding Mobility Agent logins to FortiGate:
By default, FortiAuthenticator will send all FSSO logins, no matter their source (DC Agent, polling, Mobility Agent, etc.) to any connected FortiGate, as long as the FSSO logins match the filters set on FortiGate and/or FortiAuthenticator.
As those filters typically rely on group information, it is important that FortiAuthenticator can determine what groups a Mobility Agent user belongs to. To this end, Mobility Agent includes information on the domain of the workstation it is running on. Mobility Agent may not work correctly, or return errors, if running on a non-domain-joined workstation.
Usually, FortiAuthenticator determines group membership by querying the LDAP server linked to the domain information sent by Mobility Agent. In Entra ID or hybrid environments, FortiAuthenticator instead uses OAuth to connect to the Entra ID instance and collect group information from there, as long as the 'prefer_azure' option is enabled in FortiClient.
With that group information in hand, FortiAuthenticator then sends any logins to connected FortiGates based on matching the group filters.

Troubleshooting:
In addition to the steps listed in the section 'How to verify that Mobility Agent sends information', the following steps can help in identifying and resolving issues with Mobility Agent and FortiAuthenticator:

1. Set the preshared key again on FortiAuthenticator and Mobility Agent. Note that for the standalone agent, some special characters are not allowed; more information can be found in the installation guide linked above.
2. Check that TCP/8001 (or whatever custom port is set) is allowed between Mobility Agent and FortiAuthenticator.
3. Verify that the same port is set in Mobility Agent and on FortiAuthenticator.
4. Check that both FortiAuthenticator and the Mobility Agent host use a reliable NTP; if there are differences in system time between FortiAuthenticator and Mobility Agent, logins may end up discarded with error 'expired cache item' in FSSO debug.
5. Ensure FortiAuthenticator can reach an LDAP server or an OAuth server for the domain the user belongs to.
6. Verify that the maximum number of SSO Sessions has not been reached. The limit is the same as the licensed user count, and non-Mobility Agent FSSO sessions count to this limit as well.
7. Verify that the maximum number of connected FortiClients has not been reached.

Related documents:

• FortiClient SSO Mobility Agent
• Logging into a Windows host using SSOMA
• SSOMA for native Microsoft Entra ID joined workstation