1. Purpose
This article outlines the functionality of Versa's Terminal Server Agent (TSA), its use case, and walks users through its configuration, monitoring, and troubleshooting procedures.
2. Use Case
2.1 Scenario
A large financial institution with multiple branches uses Windows-based terminal servers to allow employees to access core banking applications. These terminal servers host multiple concurrent users, each accessing different financial tools and client data.
2.2 Challenge
The institution enforces strict user-based access control policies to protect sensitive customer data. However, their Next-Generation Firewall (NGFW) relies on the source IP address to identify users. In a terminal server environment where multiple users share the same IP address, the NGFW cannot differentiate between individual users. This creates a security gap, making it impossible to enforce role-based access policies effectively.
2.3 Solution
To address this, the institution deploys the Versa Terminal Server Agent (TSA) on its Windows-based terminal servers. The TSA dynamically assigns a distinct port range to each user, ensuring that each user's network traffic is uniquely identifiable — even when multiple users share the same IP address.
3. Overview of Versa Terminal Server Agent
3.1 How It Works
The VOS appliance identifies users using the IP address mapped against the username. In Versa, the IP2User module in the VOS appliance is responsible for this functionality. NGFWs — including Versa's — rely on the IP address to identify users. When multiple users share the same IP address in a multi-user virtual or physical desktop environment, it becomes impossible for the NGFW to enforce user-based policies.
Versa's Terminal Server Agent resolves this by assigning a distinct port range to each user on virtual desktop instances such as Windows-based terminal servers. The TSA notifies the connected VOS appliance about these port assignments, enabling the appliance to create an IP-address-to-port user mapping table and enforce actions based on user and group identities.
The underlying principle is to enhance user identification by managing port allocations for each user through the Versa TS Agent installed on the server. By sharing this data with the VOS appliance, user identification is achieved through a combination of source IP address and source port information.
3.2 Network Topology
The diagram below illustrates a typical Versa TSA deployment, showing the relationship between the Windows Terminal Server (with TSA installed), the VOS appliance, the intranet, and remote users connecting through the network.
3.3 TSA vs. VMS: Key Differences
Versa TSA is a passive authentication tool, similar to VMS (Versa Management System). However, there are important architectural differences between the two:
|
|
VMS |
Versa TSA |
|
Placement |
Alongside the AD server |
On the terminal server (multi-user host) |
|
Data shared |
User-to-IP mapping with branch locations |
IP address + per-user port block to VOS appliance |
3.4 Key Benefits
- Granular user identification: Differentiates individual users sharing the same IP address through unique port range assignments.
- Policy enforcement: Enables the VOS appliance to enforce role-based access control and security policies per user, even in shared IP environments.
- Passive authentication: No active user interaction required — the agent operates transparently in the background.
- Windows terminal server support: Specifically designed for multi-user Windows desktop environments commonly used in enterprise settings.
4. Configuration Steps
Complete the following steps in order to deploy and configure the Versa Terminal Server Agent in your environment.
Step 1: Generate a self-signed End Entity certificate from the VOS.
Step 2: Configure captive portal service in the VOS device.
Step 3: Configure TSA profile.
Step 4: Map the TSA profile to the "General" TSA configuration.
Step 5: Create security policies with the Windows server users.
Step 6: Install the Versa TS Agent in the Windows server.
Link to download TSA software:
https://versanetworks.app.box.com/s/83g84wklcgq7k2uy292qfdyjusym12p7
Step 7: Ensure name resolution to the FQDN using a name server or local host entry.
Step 8: Export the certificate from the appliance and install it in the server's trust store.
Copy to Windows server and open the certificate. Press "Install certificate"
Step 9: Register the TS Agent to the captive portal.
5. Versa TS Agent UI
The Versa TS Agent UI on the Windows server provides visibility into the current state of the agent and its configuration. Key areas to verify:
- TSA profile configuration: The TSA profile pushed from the VOS is reflected in the agent UI, confirming that the VOS and the TS Agent are in sync.
- Port block allocation (Monitor tab): The "Monitor" tab displays the port blocks currently allocated to each logged-in user on the terminal server. Each user should have a unique, non-overlapping port range.
- User login/logout events (Event Audit Log tab): The "Event Audit Log" tab shows a timestamped record of user login and logout events. This confirms that the agent is correctly tracking session changes and updating the VOS with real-time user mapping information.
- Troubleshooting (Log Export): The Versa TS Agent UI provides an option to export logs directly from the TSA server. These logs are essential for diagnosing registration failures, port allocation issues, and communication errors between the TS Agent and the VOS appliance. Exporting and reviewing these logs should be the first step when troubleshooting any TSA-related issue.
6. TSA User Mapping in the VOS
On the VOS appliance, the IP-address-to-port user mapping table can be verified to confirm that the TSA is correctly reporting user sessions. Each entry in the table should reflect an active user on the terminal server, along with their assigned source IP address and port block. This mapping is what enables the VOS to apply user-specific security policies to traffic originating from the shared terminal server IP address.
Command — View TSA Message History:
admin@B1-cli> show orgs org-services T1 secure-access history tsa messages brief
Output:
MESSAGE
ID ID TYPE USERNAME IP ADDRESS BLOCKSIZE BLOCKS STATUS
--------------------------------------------------------------------------------------------------
1 76 login system@nt authority 172.50.0.10 500 [ 10000 ] success
2 76 login system@nt authority 10.192.119.134 500 [ 10000 ] success
3 77 login administrator@versatac.com 172.50.0.10 500 [ 10500 ] success
4 77 login administrator@versatac.com 10.192.119.134 500 [ 10500 ] success
5 78 login sarath@versatac.com 172.50.0.10 500 [ 11500 ] success
6 78 login sarath@versatac.com 10.192.119.134 500 [ 11500 ] success
7 79 login administrator@versatac.com 172.50.0.10 500 [ 12000 ] success
8 79 login administrator@versatac.com 10.192.119.134 500 [ 12000 ] success
The output above shows each login event reported by the TSA. Each user is assigned a unique block of 500 ports. Multiple entries per user reflect assignments across different IP interfaces on the terminal server.
Command — View Live User Mappings:
admin@B1-cli> show orgs org-services T1 user-identification live-users tsa detail
Output:
user-identification live-users tsa detail 172.50.0.10
hit-count 0
blocksize 500
ports 10000-10499
hit-count 0
user-name "system@nt authority"
user-id 0
login-timestamp "2026-09-08 22:34:23"
ports 10500-10999
hit-count 0
user-name administrator@versatac.com
user-id 0
login-timestamp "2026-09-08 22:34:23"
ports 11000-11499
hit-count 0
user-name sarath@versatac.com
user-id 0
login-timestamp "2026-09-08 22:34:23"
ports 11500-11999
hit-count 0
user-name sarath@versatac.com
user-id 0
login-timestamp "2026-09-08 22:34:23"
ports 12000-12499
hit-count 0
user-name administrator@versatac.com
user-id 0
login-timestamp "2026-09-08 22:34:23"
ports 12500-12999
hit-count 0
user-name "system@nt authority"
user-id 0
login-timestamp "2026-09-08 22:34:23"
The live-users output confirms the current port-to-user mapping on the VOS. Each port block of 500 is bound to a specific user, with a login timestamp indicating when the session was registered. This table is the source of truth used by the VOS to enforce user-based security policies.
Command — View Live User Session List:
admin@B1-cli> show orgs org-services T1 user-identification live-users list brief
Output:
TIME
SESSION TO EXPIRATION
IP ADDRESS NAME STATUS HITS EXPIRY MODE
--------------------------------------------------------------------
172.50.0.10 tsa-multiuser Live 0 60 inactivity
10.192.119.134 tsa-multiuser Live 0 60 inactivity
This confirms that both IP interfaces on the terminal server have active TSA multi-user sessions registered on the VOS, with an inactivity expiry of 60 seconds.
Command — View All TSA User Mappings by IP:
vsm-vcsn0> show identity tsa mapping all-users T1-2 172.50.0.10
Output:
Blocksize : 500
----------------------------------------------------------
Username Ranges
----------------------------------------------------------
administrator@versatac.com 12000-12499, 10500-10999
local service@nt authority 13500-13999
network service@nt authority 13000-13499
sarath@versatac.com 11000-11499, 11500-11999
system@nt authority 12500-12999, 10000-10499
----------------------------------------------------------
Total users : 5
This command provides a consolidated view of all users and their assigned port ranges for the given IP address. Each user may hold multiple port blocks if they have logged in across multiple sessions.
Command — Look Up User by Source Port:
vsm-vcsn0> show identity tsa mapping by-source-port T1-2 172.50.0.10 11500
Output:
Node blocksize : 500
User details,
name : sarath@versatac.com
range : 11500-11999
id : 0
grp_cnt : 0
login_timestamp : 2026-09-08 22:34:23
timestamp : 0
hit_count : 0
This command is particularly useful during troubleshooting — given a specific source port observed in traffic logs, it immediately identifies the user associated with that port. In this example, source port 11500 maps to sarath@versatac.com with a port range of 11500–11999.
7. Traffic flow and Troubleshooting
The following section covers common issues encountered during TSA deployment and registration, along with recommended resolution steps.
7.1 Traffic Flow
7.2 TS Agent Fails to Register with the Captive Portal
Symptoms: The Versa TS Agent cannot connect or register to the captive portal service on the VOS.
Possible Causes & Resolution:
- Certificate not trusted: Verify that the VOS certificate has been exported and correctly installed in the Windows server's trust store (Step 8). Open the Certificate Manager on the server and confirm the certificate appears under Trusted Root Certification Authorities.
- FQDN not resolvable: Confirm that the FQDN of the VOS is resolvable from the terminal server. Run nslookup <VOS-FQDN> from the server. If it fails, add the FQDN-to-IP mapping in the local hosts file or update the DNS server (Step 7).
- Captive portal service not running: Log in to the VOS and verify that the captive portal service is active and bound to the correct interface (Step 2).
- Firewall blocking port: Ensure that no host-based or network firewall is blocking the port used by the captive portal service between the terminal server and the VOS.
7.3 Users Not Appearing in the IP-to-User Mapping Table
Symptoms: The VOS appliance does not show user-to-port mappings even after the TS Agent is registered.
Possible Causes & Resolution:
- TSA profile not mapped: Confirm that the TSA profile has been mapped to the "General" TSA configuration in the VOS (Step 4). An unmapped profile will not push user data to the appliance.
- No active user sessions on the server: The TS Agent only reports active sessions. Log in to the terminal server with a domain user and re-check the mapping table.
- IP2User module not active: Verify that the IP2User module is enabled and running on the VOS appliance. Check appliance logs for any module errors.
7.4 Security Policies Not Enforced Per User
Symptoms: All users on the terminal server are subject to the same policy regardless of their identity or role.
Possible Causes & Resolution:
- Security policies missing user/group conditions: Review the security policies on the VOS (Step 5) and confirm that rules reference the correct Windows 2019 server user accounts or groups. Policies that match only on IP without port range will not differentiate users.
- Port range overlap: Check the TSA profile configuration to ensure each user is assigned a unique, non-overlapping port block. Overlapping ranges will cause the VOS to misidentify users.
- Stale mapping entry: If a user logged off and a new user received the same port block, an outdated mapping may persist. Verify that the TS Agent is correctly sending logoff events to the VOS to clear stale entries.
7.5 Certificate Errors During Agent Communication
Symptoms: SSL/TLS handshake failures or certificate validation errors appear in the TS Agent logs.
Possible Causes & Resolution:
- Expired certificate: Check the validity period of the self-signed End Entity certificate generated in Step 1. Re-generate and re-export if it has expired, then reinstall in the server's trust store.
- Certificate CN/SAN mismatch: Ensure the certificate's Common Name (CN) or Subject Alternative Name (SAN) matches the FQDN used by the TS Agent to connect to the VOS. A mismatch will cause TLS verification to fail.
- Wrong certificate store: The certificate must be installed under Trusted Root Certification Authorities on the Windows server, not Personal or Intermediate stores.