Retrieve User Mappings from a Terminal Server Using the PAN-OS XML API
Table of Contents
Expand All
|
Collapse All
Next-Generation Firewall Docs
-
PAN-OS 10.0 (EoL)
- PAN-OS 11.1 & Later
- PAN-OS 11.0 (EoL)
- PAN-OS 10.2
- PAN-OS 10.1
- PAN-OS 10.0 (EoL)
- PAN-OS 9.1 (EoL)
- Cloud Management of NGFWs
-
- Management Interfaces
-
- Launch the Web Interface
- Configure Banners, Message of the Day, and Logos
- Use the Administrator Login Activity Indicators to Detect Account Misuse
- Manage and Monitor Administrative Tasks
- Commit, Validate, and Preview Firewall Configuration Changes
- Export Configuration Table Data
- Use Global Find to Search the Firewall or Panorama Management Server
- Manage Locks for Restricting Configuration Changes
-
-
- Define Access to the Web Interface Tabs
- Provide Granular Access to the Monitor Tab
- Provide Granular Access to the Policy Tab
- Provide Granular Access to the Objects Tab
- Provide Granular Access to the Network Tab
- Provide Granular Access to the Device Tab
- Define User Privacy Settings in the Admin Role Profile
- Restrict Administrator Access to Commit and Validate Functions
- Provide Granular Access to Global Settings
- Provide Granular Access to the Panorama Tab
- Provide Granular Access to Operations Settings
- Panorama Web Interface Access Privileges
-
- Reset the Firewall to Factory Default Settings
-
- Plan Your Authentication Deployment
- Configure SAML Authentication
- Configure Kerberos Single Sign-On
- Configure Kerberos Server Authentication
- Configure TACACS+ Authentication
- Configure RADIUS Authentication
- Configure LDAP Authentication
- Configure Local Database Authentication
- Configure an Authentication Profile and Sequence
- Test Authentication Server Connectivity
- Troubleshoot Authentication Issues
-
- Keys and Certificates
- Default Trusted Certificate Authorities (CAs)
- Certificate Deployment
- Configure the Master Key
- Export a Certificate and Private Key
- Configure a Certificate Profile
- Configure an SSL/TLS Service Profile
- Configure an SSH Service Profile
- Replace the Certificate for Inbound Management Traffic
- Configure the Key Size for SSL Forward Proxy Server Certificates
-
- HA Overview
-
- Prerequisites for Active/Active HA
- Configure Active/Active HA
-
- Use Case: Configure Active/Active HA with Route-Based Redundancy
- Use Case: Configure Active/Active HA with Floating IP Addresses
- Use Case: Configure Active/Active HA with ARP Load-Sharing
- Use Case: Configure Active/Active HA with Floating IP Address Bound to Active-Primary Firewall
- Use Case: Configure Active/Active HA with Source DIPP NAT Using Floating IP Addresses
- Use Case: Configure Separate Source NAT IP Address Pools for Active/Active HA Firewalls
- Use Case: Configure Active/Active HA for ARP Load-Sharing with Destination NAT
- Use Case: Configure Active/Active HA for ARP Load-Sharing with Destination NAT in Layer 3
- HA Clustering Overview
- HA Clustering Best Practices and Provisioning
- Configure HA Clustering
- Refresh HA1 SSH Keys and Configure Key Options
- HA Firewall States
-
- Use the Dashboard
- Monitor Applications and Threats
- Monitor Block List
-
- Report Types
- View Reports
- Configure the Expiration Period and Run Time for Reports
- Disable Predefined Reports
- Custom Reports
- Generate Custom Reports
- Generate the SaaS Application Usage Report
- Manage PDF Summary Reports
- Generate User/Group Activity Reports
- Manage Report Groups
- Schedule Reports for Email Delivery
- Manage Report Storage Capacity
- View Policy Rule Usage
- Use External Services for Monitoring
- Configure Log Forwarding
- Configure Email Alerts
-
- Configure Syslog Monitoring
-
- Traffic Log Fields
- Threat Log Fields
- URL Filtering Log Fields
- Data Filtering Log Fields
- HIP Match Log Fields
- GlobalProtect Log Fields
- IP-Tag Log Fields
- User-ID Log Fields
- Decryption Log Fields
- Tunnel Inspection Log Fields
- SCTP Log Fields
- Authentication Log Fields
- Config Log Fields
- System Log Fields
- Correlated Events Log Fields
- GTP Log Fields
- Syslog Severity
- Custom Log/Event Format
- Escape Sequences
- Forward Logs to an HTTP/S Destination
- Firewall Interface Identifiers in SNMP Managers and NetFlow Collectors
- Monitor Transceivers
-
- User-ID Overview
- Enable User-ID
- Map Users to Groups
- Enable User- and Group-Based Policy
- Enable Policy for Users with Multiple Accounts
- Verify the User-ID Configuration
-
- App-ID Overview
- App-ID and HTTP/2 Inspection
- Manage Custom or Unknown Applications
- Safely Enable Applications on Default Ports
- Applications with Implicit Support
- Application Level Gateways
- Disable the SIP Application-level Gateway (ALG)
- Maintain Custom Timeouts for Data Center Applications
-
- Best Practices for Securing Your Network from Layer 4 and Layer 7 Evasions
- Set Up Antivirus, Anti-Spyware, and Vulnerability Protection
- Set Up File Blocking
- Prevent Brute Force Attacks
- Customize the Action and Trigger Conditions for a Brute Force Signature
- Enable Evasion Signatures
- Monitor Blocked IP Addresses
- Threat Signature Categories
- Create Threat Exceptions
- Custom Signatures
- Share Threat Intelligence with Palo Alto Networks
- Threat Prevention Resources
-
- Decryption Overview
-
- Keys and Certificates for Decryption Policies
- SSL Forward Proxy
- SSL Forward Proxy Decryption Profile
- SSL Inbound Inspection
- SSL Inbound Inspection Decryption Profile
- SSL Protocol Settings Decryption Profile
- SSH Proxy
- SSH Proxy Decryption Profile
- Profile for No Decryption
- SSL Decryption for Elliptical Curve Cryptography (ECC) Certificates
- Perfect Forward Secrecy (PFS) Support for SSL Decryption
- SSL Decryption and Subject Alternative Names (SANs)
- TLSv1.3 Decryption
- High Availability Support for Decrypted Sessions
- Decryption Mirroring
- Configure SSL Forward Proxy
- Configure SSL Inbound Inspection
- Configure SSH Proxy
- Configure Server Certificate Verification for Undecrypted Traffic
- Enable Users to Opt Out of SSL Decryption
- Temporarily Disable SSL Decryption
- Configure Decryption Port Mirroring
- Verify Decryption
-
- How Decryption Broker Works
- Layer 3 Security Chain Guidelines
- Configure Decryption Broker with One or More Layer 3 Security Chain
- Transparent Bridge Security Chain Guidelines
- Configure Decryption Broker with a Single Transparent Bridge Security Chain
- Configure Decryption Broker with Multiple Transparent Bridge Security Chains
- Activate Free Licenses for Decryption Features
-
- About Palo Alto Networks URL Filtering Solution
- How Advanced URL Filtering Works
- URL Filtering Inline ML
- URL Filtering Use Cases
- Plan Your URL Filtering Deployment
- URL Filtering Best Practices
- Activate The Advanced URL Filtering Subscription
- Test URL Filtering Configuration
- Configure URL Filtering
- Configure URL Filtering Inline ML
- Log Only the Page a User Visits
- Create a Custom URL Category
- URL Category Exceptions
- Use an External Dynamic List in a URL Filtering Profile
- Allow Password Access to Certain Sites
- URL Filtering Response Pages
- Customize the URL Filtering Response Pages
- HTTP Header Logging
- Request to Change the Category for a URL
-
-
- Tap Interfaces
-
- Layer 2 and Layer 3 Packets over a Virtual Wire
- Port Speeds of Virtual Wire Interfaces
- LLDP over a Virtual Wire
- Aggregated Interfaces for a Virtual Wire
- Virtual Wire Support of High Availability
- Zone Protection for a Virtual Wire Interface
- VLAN-Tagged Traffic
- Virtual Wire Subinterfaces
- Configure Virtual Wires
- Configure an Aggregate Interface Group
- Configure Bonjour Reflector for Network Segmentation
- Use Interface Management Profiles to Restrict Access
- Virtual Routers
- Service Routes
- RIP
- Route Redistribution
-
- DNS Overview
- DNS Proxy Object
- DNS Server Profile
- Multi-Tenant DNS Deployments
- Configure a DNS Proxy Object
- Configure a DNS Server Profile
- Use Case 1: Firewall Requires DNS Resolution
- Use Case 2: ISP Tenant Uses DNS Proxy to Handle DNS Resolution for Security Policies, Reporting, and Services within its Virtual System
- Use Case 3: Firewall Acts as DNS Proxy Between Client and Server
- DNS Proxy Rule and FQDN Matching
- Dynamic DNS Overview
- Configure Dynamic DNS for Firewall Interfaces
-
- NAT Rule Capacities
- Dynamic IP and Port NAT Oversubscription
- Dataplane NAT Memory Statistics
-
- Translate Internal Client IP Addresses to Your Public IP Address (Source DIPP NAT)
- Enable Clients on the Internal Network to Access your Public Servers (Destination U-Turn NAT)
- Enable Bi-Directional Address Translation for Your Public-Facing Servers (Static Source NAT)
- Configure Destination NAT with DNS Rewrite
- Configure Destination NAT Using Dynamic IP Addresses
- Modify the Oversubscription Rate for DIPP NAT
- Reserve Dynamic IP NAT Addresses
- Disable NAT for a Specific Host or Interface
-
-
- Policy Types
- Policy Objects
- Track Rules Within a Rulebase
- Enforce Policy Rule Description, Tag, and Audit Comment
- Move or Clone a Policy Rule or Object to a Different Virtual System
-
- External Dynamic List
- Built-in External Dynamic Lists
- Configure the Firewall to Access an External Dynamic List
- Retrieve an External Dynamic List from the Web Server
- View External Dynamic List Entries
- Exclude Entries from an External Dynamic List
- Enforce Policy on an External Dynamic List
- Find External Dynamic Lists That Failed Authentication
- Disable Authentication for an External Dynamic List
- Register IP Addresses and Tags Dynamically
- Use Dynamic User Groups in Policy
- Use Auto-Tagging to Automate Security Actions
- CLI Commands for Dynamic IP Addresses and Tags
- Test Policy Rules
-
- Network Segmentation Using Zones
- How Do Zones Protect the Network?
-
PAN-OS 11.1 & Later
- PAN-OS 11.1 & Later
- PAN-OS 11.0 (EoL)
- PAN-OS 10.2
- PAN-OS 10.1
-
- Tap Interfaces
-
- Layer 2 and Layer 3 Packets over a Virtual Wire
- Port Speeds of Virtual Wire Interfaces
- LLDP over a Virtual Wire
- Aggregated Interfaces for a Virtual Wire
- Virtual Wire Support of High Availability
- Zone Protection for a Virtual Wire Interface
- VLAN-Tagged Traffic
- Virtual Wire Subinterfaces
- Configure Virtual Wires
- Configure a PPPoE Client on a Subinterface
- Configure an IPv6 PPPoE Client
- Configure an Aggregate Interface Group
- Configure Bonjour Reflector for Network Segmentation
- Use Interface Management Profiles to Restrict Access
-
- DHCP Overview
- Firewall as a DHCP Server and Client
- Firewall as a DHCPv6 Client
- DHCP Messages
- Dynamic IPv6 Addressing on the Management Interface
- Configure an Interface as a DHCP Server
- Configure an Interface as a DHCPv4 Client
- Configure an Interface as a DHCPv6 Client with Prefix Delegation
- Configure the Management Interface as a DHCP Client
- Configure the Management Interface for Dynamic IPv6 Address Assignment
- Configure an Interface as a DHCP Relay Agent
-
- DNS Overview
- DNS Proxy Object
- DNS Server Profile
- Multi-Tenant DNS Deployments
- Configure a DNS Proxy Object
- Configure a DNS Server Profile
- Use Case 1: Firewall Requires DNS Resolution
- Use Case 2: ISP Tenant Uses DNS Proxy to Handle DNS Resolution for Security Policies, Reporting, and Services within its Virtual System
- Use Case 3: Firewall Acts as DNS Proxy Between Client and Server
- DNS Proxy Rule and FQDN Matching
-
- NAT Rule Capacities
- Dynamic IP and Port NAT Oversubscription
- Dataplane NAT Memory Statistics
-
- Translate Internal Client IP Addresses to Your Public IP Address (Source DIPP NAT)
- Create a Source NAT Rule with Persistent DIPP
- PAN-OS
- Strata Cloud Manager
- Enable Clients on the Internal Network to Access your Public Servers (Destination U-Turn NAT)
- Enable Bi-Directional Address Translation for Your Public-Facing Servers (Static Source NAT)
- Configure Destination NAT with DNS Rewrite
- Configure Destination NAT Using Dynamic IP Addresses
- Modify the Oversubscription Rate for DIPP NAT
- Reserve Dynamic IP NAT Addresses
- Disable NAT for a Specific Host or Interface
-
- Network Packet Broker Overview
- How Network Packet Broker Works
- Prepare to Deploy Network Packet Broker
- Configure Transparent Bridge Security Chains
- Configure Routed Layer 3 Security Chains
- Network Packet Broker HA Support
- User Interface Changes for Network Packet Broker
- Limitations of Network Packet Broker
- Troubleshoot Network Packet Broker
-
- Enable Advanced Routing
- Logical Router Overview
- Configure a Logical Router
- Create a Static Route
- Configure BGP on an Advanced Routing Engine
- Create BGP Routing Profiles
- Create Filters for the Advanced Routing Engine
- Configure OSPFv2 on an Advanced Routing Engine
- Create OSPF Routing Profiles
- Configure OSPFv3 on an Advanced Routing Engine
- Create OSPFv3 Routing Profiles
- Configure RIPv2 on an Advanced Routing Engine
- Create RIPv2 Routing Profiles
- Create BFD Profiles
- Configure IPv4 Multicast
- Configure MSDP
- Create Multicast Routing Profiles
- Create an IPv4 MRoute
-
-
PAN-OS 11.2
- PAN-OS 11.2
- PAN-OS 11.1
- PAN-OS 11.0 (EoL)
- PAN-OS 10.2
- PAN-OS 10.1
- PAN-OS 10.0 (EoL)
- PAN-OS 9.1 (EoL)
- PAN-OS 9.0 (EoL)
- PAN-OS 8.1 (EoL)
- Cloud Management and AIOps for NGFW
End-of-Life (EoL)
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.
- 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 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. - 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-20099Similarly, 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-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