Configure User Mapping for Terminal Server Users
Individual terminal server users appear to have the same IP address and therefore an IP address-to-username mapping is not sufficient to identify a specific user. To enable identification of specific users on Windows-based terminal servers, the Palo Alto Networks Terminal Services agent (TS agent) allocates a port range to each user. It then notifies every connected firewall about the allocated port range, which allows the firewall to create an IP address-port-user mapping table and enable user- and group-based security policy enforcement. For non-Windows terminal servers, you can configure the PAN-OS XML API to extract user mapping information.
The following sections describe how to configure user mapping for terminal server users:
Configure the Palo Alto Networks Terminal Services Agent for User Mapping
Use the following procedure to install and configure the TS agent on the terminal server. To map all your users, you must install the TS agent on all terminal servers that your users log in to.
For information about the supported terminal servers supported by the TS Agent, refer to “Operating System (OS) Compatibility TS Agent” in the Terminal Services Agent Release Notes.
Configure the Palo Alto Networks Terminal Services Agent for User Mapping
Download the TS agent installer. Log in to the Palo Alto Networks Customer Support web site. Select Software Updates from the Manage Devices section. Scroll to the Terminal Services Agent section and Download the version of the agent you want to install. Save the TaInstall64.x64-x.x.x-xx.msi or TaInstall-x.x.x-xx.msi file (be sure to select the appropriate version based on whether the Windows system is running a 32-bit OS or a 64-bit OS) on the systems where you plan to install the agent.
Run the installer as an administrator. Open the Windows Start menu, right-click the Command Prompt program, and select Run as administrator. From the command line, run the .msi file you downloaded. For example, if you saved the .msi file to the Desktop you would enter the following: C:\Users\administrator.acme>cd DesktopC:\Users\administrator.acme\Desktop>TaInstall-6.0.0-1.msi Follow the setup prompts to install the agent using the default settings. By default, the agent gets installed to the C:\Program Files (x86)\Palo Alto Networks\Terminal Server Agent folder, but you can Browse to a different location. When the installation completes, Close the setup window. If you are upgrading to a TS Agent version that has a newer driver than the existing installation, the installation wizard prompts you to reboot the system after upgrading in order to use the new driver.
Define the range of ports for the TS Agent to allocate to end users. The System Source Port Allocation Range and System Reserved Source Ports fields specify the range of ports that will be allocated to non-user sessions. Make sure the values specified in these fields do not overlap with the ports you designate for user traffic. These values can only be changed by editing the corresponding Windows registry settings. Open the Windows Start menu and select Terminal Server Agent to launch the Terminal Services agent application. Select Configure in the side menu. Enter the Source Port Allocation Range (default 20000-39999). This is the full range of port numbers that the TS agent will allocate for user mapping. The port range you specify cannot overlap with the System Source Port Allocation Range. ( Optional ) If there are ports/port ranges within the source port allocation that you do not want the TS Agent to allocate to user sessions, specify them as Reserved Source Ports. To include multiple ranges, use commas with no spaces, for example: 2000-3000,3500,4000-5000 . Specify the number of ports to allocate to each individual user upon login to the terminal server in the Port Allocation Start Size Per User field (default 200). Specify the Port Allocation Maximum Size Per User, which is the maximum number of ports the Terminal Services agent can allocate to an individual user. Specify whether to continue processing traffic from the user if the user runs out of allocated ports. By default, the Fail port binding when available ports are used up is selected, which indicates that the application will fail to send traffic when all ports are used. To enable users to continue using applications when they run out of ports, clear this check box. Keep in mind that this traffic may not be identified with User-ID.
Configure the firewalls to connect to the Terminal Services agent. Complete the following steps on each firewall you want to connect to the Terminal Services agent to receive user mappings: Select Device > User Identification > Terminal Server Agents and click Add. Enter a Name for the Terminal Services agent. Enter the IP address of the Windows Host on which the Terminal Services agent is installed. Enter the Port number on which the agent will listen for user mapping requests. This value must match the value configured on the Terminal Services agent. By default, the port is set to 5009 on the firewall and on the agent. If you change it here, you must also change the Listening Port field on the Terminal Services agent Configure screen. Make sure that the configuration is Enabled and then click OK. Commit the changes. Verify that the Connected status displays as connected (a green light).
Verify that the Terminal Services agent is successfully mapping IP addresses to usernames and that the firewalls can connect to the agent. Open the Windows Start menu and select Terminal Server Agent. Verify that the firewalls can connect by making sure the Connection Status of each firewall in the Connection List is Connected. Verify that the Terminal Services agent is successfully mapping port ranges to usernames by selecting Monitor in the side menu and making sure that the mapping table is populated.
( Windows 2012 R2 servers only ) Disable Enhanced Protected Mode in Microsoft Internet Explorer for each user who uses that browser. This task is not necessary for other browsers such as Google Chrome or Mozilla Firefox. To disable Enhanced Protected Mode for all users, use Local Security Policy. Perform these steps on the Windows Server: Start Internet Explorer. Select Internet options > Advanced and scroll down to the Security section. Clear Enable Enhanced Protected Mode. Click OK. In Internet Explorer, Palo Alto Networks recommends that you do not disable Protected Mode, which differs from Enhanced Protected Mode.
Retrieve User Mappings from a Terminal Server Using the PAN-OS XML API
The PAN-OS XML API uses standard HTTP requests to send and receive data. API calls can be made directly from command line utilities such as cURL or using any scripting or application framework that supports RESTful services.
To enable a non-Windows terminal server to send user mapping information directly to the firewall, create scripts that extract the user login and logout events and use them for input to the PAN-OS XML API request format. Then define the mechanisms for submitting the XML API request(s) to the firewall using cURL or wget and providing the firewall’s API key for secure communication. Creating user mappings from multi-user systems such as terminal servers requires use of the following API messages:
<multiusersystem>—Sets up the configuration for an XML API Multi-user System on the firewall. This message allows for definition of the terminal server IP address (this will be the source address for all users on that terminal server). In addition, the <multiusersystem> setup message specifies the range of source port numbers to allocate for user mapping and the number of ports to allocate to each individual user upon login (called the block size ). If you want to use the default source port allocation range (1025-65534) and block size (200), you do not need to send a <multiusersystem> setup event to the firewall. Instead, the firewall will automatically generate the XML API Multi-user System configuration with the default settings upon receipt of the first user login event message. <blockstart>—Used with the <login> and <logout> messages to indicate the starting source port number allocated to the user. The firewall then uses the block size to determine the actual range of port numbers to map to the IP address and username in the login message. For example, if the <blockstart> value is 13200 and the block size configured for the multi-user system is 300, the actual source port range allocated to the user is 13200 through 13499. Each connection initiated by the user should use a unique source port number within the allocated range, enabling the firewall to identify the user based on its IP address-port-user mappings for enforcement of user- and group-based security rules. When a user exhausts all the ports allocated, the terminal server must send a new <login> message allocating a new port range for the user so that the firewall can update the IP address-port-user mapping. In addition, a single username can have multiple blocks of ports mapped simultaneously. When the firewall receives a <logout> message that includes a <blockstart> parameter, it removes the corresponding IP address-port-user mapping from its mapping table. When the firewall receives a <logout> message with a username and IP address, but no <blockstart> , it removes the user from its table. And, if the firewall receives a <logout> message with an IP address only, it removes the multi-user system and all mappings associated with it.
The XML files that the terminal server sends to the firewall can contain multiple message types and the messages do not need to be in any particular order within the file. However, upon receiving an XML file that contains multiple message types, the firewall will process them in the following order: multiusersystem requests first, followed by logins, then logouts.
The following workflow provides an example of how to use the PAN-OS XML API to send user mappings from a non-Windows terminal server to the firewall.
Use the PAN-OS XML API to Map Non-Windows Terminal Services Users
Generate the API key that will be used to authenticate the API communication between the firewall and the terminal server. To generate the key you must provide login credentials for an administrative account; the API is available to all administrators (including role-based administrators with XML API privileges enabled). Any special characters in the password must be URL/ percent-encoded. From a browser, log in to the firewall. Then, to generate the API key for the firewall, open a new browser window and enter the following URL: https://<Firewall-IPaddress>/api/?type=keygen&user=<username>& password=<password> Where <Firewall-IPaddress> is the IP address or FQDN of the firewall and <username> and <password> are the credentials for the administrative user account on the firewall. For example: https://10.1.2.5/api/?type=keygen&user=admin&password=admin The firewall responds with a message containing the key, for example: <response status="success"> <result> <key>k7J335J6hI7nBxIqyfa62sZugWx7ot%2BgzEA9UOnlZRg=</key> </result> </response>
( Optional ) Generate a setup message that the terminal server will send to specify the port range and block size of ports per user that your terminal services agent uses. If the terminal services agent does not send a setup message, the firewall will automatically create a Terminal Services agent configuration using the following default settings upon receipt of the first login message: Default port range: 1025 to 65534 Per user block size: 200 Maximum number of multi-user systems: 1,000 The following shows a sample setup message: <uid-message> <payload> <multiusersystem> <entry ip="10.1.1.23" startport="20000" endport="39999" blocksize="100"> </multiusersystem> </payload> <type>update</type> <version>1.0</version> </uid-message> where entry ip specifies the IP address assigned to terminal server users, startport and endport specify the port range to use when assigning ports to individual users, and blocksize specifies the number of ports to assign to each user. The maximum blocksize is 4000 and each multi-user system can allocate a maximum of 1000 blocks. If you define a custom blocksize and or port range, keep in mind that you must configure the values such that every port in the range gets allocated and that there are no gaps or unused ports. For example, if you set the port range to 1000–1499, you could set the block size to 100, but not to 200. This is because if you set it to 200, there would be unused ports at the end of the range.
Create a script that will extract the login events and create the XML input file to send to the firewall. Make sure the script enforces assignment of port number ranges at fixed boundaries with no port overlaps. For example, if the port range is 1000–1999 and the block size is 200, acceptable blockstart values would be 1000, 1200, 1400, 1600, or 1800. Blockstart values of 1001, 1300, or 1850 would be unacceptable because some of the port numbers in the range would be left unused. The login event payload that the terminal server sends to the firewall can contain multiple login events. The following shows the input file format for a PAN-OS XML login event: <uid-message> <payload> <login> <entry name="acme\jjaso" ip="10.1.1.23" blockstart="20000"> <entry name="acme\jparker" ip="10.1.1.23" blockstart="20100"> <entry name="acme\ccrisp" ip="10.1.1.23" blockstart="21000"> </login> </payload> <type>update</type> <version>1.0</version> </uid-message> The firewall uses this information to populate its user mapping table. Based on the mappings extracted from the example above, if the firewall received a packet with a source address and port of 10.1.1.23:20101, it would map the request to user jparker for policy enforcement. Each multi-user system can allocate a maximum of 1,000 port blocks.
Create a script that will extract the logout events and create the XML input file to send to the firewall. Upon receipt of a logout event message with a blockstart parameter, the firewall removes the corresponding IP address-port-user mapping. If the logout message contains a username and IP address, but no blockstart parameter, the firewall removes all mappings for the user. If the logout message contains an IP address only, the firewall removes the multi-user system and all associated mappings. The following shows the input file format for a PAN-OS XML logout event: <uid-message> <payload> <logout> <entry name="acme\jjaso" ip="10.1.1.23" blockstart="20000"> <entry name="acme\ccrisp" ip="10.1.1.23"> <entry ip="10.2.5.4"> </logout> </payload> <type>update</type> <version>1.0</version> </uid-message> You can also clear the multiuser system entry from the firewall using the following CLI command: clear xml-api multiusersystem
Make sure that the scripts you create include a way to dynamically enforce that the port block range allocated using the XML API matches the actual source port assigned to the user on the terminal server and that the mapping is removed when the user logs out or the port allocation changes. One way to do this would be to use netfilter NAT rules to hide user sessions behind the specific port ranges allocated via the XML API based on the uid. For example, to ensure that a user with the user ID jjaso is mapped to a source network address translation (SNAT) value of 10.1.1.23:20000-20099, the script you create should include the following: [root@ts1 ~]# iptables -t nat -A POSTROUTING -m owner --uid-owner jjaso -p tcp -j SNAT --to-source 10.1.1.23:20000-20099 Similarly, the scripts you create should also ensure that the IP table routing configuration dynamically removes the SNAT mapping when the user logs out or the port allocation changes: [root@ts1 ~]# iptables -t nat -D POSTROUTING 1
Define how to package the XML input files containing the setup, login, and logout events into wget or cURL messages for transmission to the firewall. To apply the files to the firewall using wget: > wget --post file <filename> “https://<Firewall-IPaddress>/api/?type=user-id&key=<key>&file-name=<input_filename.xml>&client=wget&vsys=<VSYS_name>” For example, the syntax for sending an input file named login.xml to the firewall at 10.2.5.11 using key k7J335J6hI7nBxIqyfa62sZugWx7ot%2BgzEA9UOnlZRg using wget would look as follows: > wget --post file login.xml “https://10.2.5.11/api/?type=user-id&key=k7J335J6hI7nBxIqyfa62sZugWx7ot%2BgzEA9UOnlZRg&file-name=login.xml&client=wget&vsys=vsys1” To apply the file to the firewall using cURL: > curl --form file=@<filename> https://<Firewall-IPaddress>/api/?type=user-id&key=<key>&vsys=<VSYS_name> For example, the syntax for sending an input file named login.xml to the firewall at 10.2.5.11 using key k7J335J6hI7nBxIqyfa62sZugWx7ot%2BgzEA9UOnlZRg using cURL would look as follows: > curl --form file@login.xml “https://10.2.5.11/api/?type=user-id&key=k7J335J6hI7nBxIqyfa62sZugWx7ot%2BgzEA9UOnlZRg&vsys=vsys1”
Verify that the firewall is successfully receiving login events from the terminal servers. Verify the configuration by opening an SSH connection to the firewall and then running the following CLI commands: To verify if the terminal server is connecting to the firewall over XML: admin@PA-5050> show user xml-api multiusersystem Host Vsys Users Blocks ---------------------------------------- 10.5.204.43 vsys1 5 2 To verify that the firewall is receiving mappings from a terminal server over XML: admin@PA-5050> show user ip-port-user-mapping all Global max host index 1, host hash count 1 XML API Multi-user System 10.5.204.43 Vsys 1, Flag 3 Port range: 20000 - 39999 Port size: start 200; max 2000 Block count 100, port count 20000 20000-20199: acme\administrator Total host: 1

Related Documentation