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.
