Retrieve User Mappings from a Terminal Server Using the PAN-OS XML API

1. 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> 

2. (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 Server agent uses.

   If the Terminal Server agent does not send a setup message, the firewall will automatically create a Terminal Server 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.
3. 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.
4. 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
5. 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

6. 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”

7. 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-5250> 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-5250> 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