Troubleshooting Tip: How to troubleshoot TSAgent connectivity and user mapping issues

Description

This article describes a troubleshooting methodology to verify TSAgent (Terminal Server Agent) connectivity and user mapping in a FortiGate FSSO environment.

Scope

Product: FortiGate.

Feature: FSSO, TSAgent.

Version: FortiOS v7.x and later.

Solution

TSAgent is used in terminal server environments to provide user identity information to FortiGate for policy enforcement. Incorrect configuration or communication issues can prevent user mapping.

This procedure verifies installation, communication, and user detection.

Troubleshooting flow:

1. If the TSAgent service is not running, start the service and verify the system startup configuration.

2. If TSAgent is running but no port is listening, verify the configuration and restart the service.

3. If sessions are not detected, verify the terminal server session status.

4. If connectivity fails, verify routing and firewall configuration.

5. If communication exists but no users appear, analyze the fssod debug output.

6. If users appear intermittently, verify time synchronization and session stability.

Verification steps:

• Verify TSAgent service status.

On the terminal server, open PowerShell and run:

Get-Service -Name TSAgent

Expected result:

The service status is 'Running'.

If the service is not running, start the service and verify the startup type.

• Verify listening ports on the terminal server.

Open PowerShell and run the following command:

netstat -an | findstr 8000

Expected result:

The TSAgent process listens on the configured port (default is 8000).

If no listening port is detected, verify the TSAgent configuration.

• Verify the TSAgent configuration file.

Navigate to the TSAgent installation directory and review the configuration file.

Verify the following:

1. The correct FortiGate IP address is configured.

2. Port configuration matches the expected value.

3. The IP address range for terminal sessions is correctly defined.

• Verify connectivity from FortiGate.

On FortiGate CLI, run:

diagnose debug enable
diagnose debug application fssod -1

Expected result:

Logs show successful communication with TSAgent and user logon events.

Disable debug after verification:

diagnose debug disable

• Verify user detection on FortiGate.

On FortiGate CLI, run the following command:

diagnose firewall auth list

Expected result:

Logged users from the terminal server appear with correct IP and username mapping.

• Verify Windows Event Viewer.

On the terminal server:

1. Open Event Viewer.

2. Navigate to Windows Logs -> Application.

3. Check for TSAgent-related errors.

Expected result:

No critical errors related to the TSAgent service or communication.

• Verify active user sessions.

On the terminal server, open PowerShell and run the following command:

query user

Expected result:

Active user sessions are listed with session IDs.

• Verify network connectivity.

On the terminal server, open PowerShell and run the following command:

Test-NetConnection -ComputerName <FortiGate_IP> -Port 8000

Expected result:

TcpTestSucceeded : True

If connectivity fails, verify firewall rules and network routing.

• Verify firewall policies on FortiGate.

Ensure that policies allow communication between FortiGate and the terminal server.

• Verify time synchronization.

Ensure that FortiGate and the terminal server use synchronized time sources.

Time differences can affect authentication and logging.

Expected result:

The time difference is minimal between devices.

• Common failure indicators:

1. No output in fssod debug indicates network communication failure.

2. Sessions present in Windows but not on FortiGate indicate TSAgent mapping failure.

3. Users appearing with incorrect IP indicates incorrect IP pool configuration.

4. Intermittent mapping indicates timing or session instability.

• Additional notes:
  TSAgent depends on accurate session tracking in Windows.
  Network latency may affect session updates.
  Ensure compatibility between FortiGate firmware and TSAgent version.

Related articles:
Troubleshooting Tip: General troubleshooting for FSSO