>
    Strata Copilot
    Apply User-ID Mapping and Populate Dynamic Groups (API)
    Focus
    Download PDF
    Focus
    1. Home
    2. Next-Generation Firewall
    3. PAN-OS XML API Use Cases
    4. Apply User-ID Mapping and Populate Dynamic Groups (API)
    Download PDF
    Next-Generation Firewall

    Apply User-ID Mapping and Populate Dynamic Groups (API)

    Table of Contents

    Apply User-ID Mapping and Populate Dynamic Groups (API)

    Use the type=user-id parameter to apply User-ID mapping information directly to the firewall. If you are using a third-party VPN solution or have users who are connecting to an 802.1x enabled wireless network, the User-ID API enables you to map users to groups so that you can capture login events and send them to the User-ID agent or directly to the firewall. Additionally, you can use the API to register the IP-to-user mapping information from the input file to populate the members of a dynamic address group or dynamic user group on the firewall. 
    curl -F key=<apikey> --form file=@<filename> "https://<firewall>/api/?type=user-id"
    or
    curl --data-urlencode key=<apikey> -d type=user-id --data-urlencode "cmd=xml-document" https://<firewall>/api/
    With your User-ID API requests, you can use the following optional parameters:
    • vsys=vsys_id—Specify the vsys where you want to apply User-ID mapping.
    • target=serialnumber—Specify the firewall by serial number when redirecting through Panorama.
    • Use a GET request if the URL query size is less than 2K and a POST request if the request size is between 2K to 5MB. Limit the query size to 5MB.
    • When multiple login or logout events are generated at the same time, make sure to follow these guidelines to ensure optimal firewall performance:
      • Design your application to queue events and perform batch API updates instead of sending single event or mapping updates.
      • Limit the number of concurrent API calls to five. The suggested limit ensures that there is no performance impact to the firewall web interface as the management plane web server handles requests from both the API and the web interface. Limits may vary depending on the type of request. The limit may be higher depending on requests.
    • (Panorama managed firewalls only) You cannot view the IP addresses of a DAG registered using XML API on the Panorama web interface. You must log in to the Panorama CLI to view the registered IP addresses of a DAG populated using XML API on Panorama and use the following command:
       show object registered-ip all
    Use the information in the following table to apply User-ID mapping information to a firewall:
    Mapping or Registration Action
    API Request
    User-ID mapping for a login, logout, or groups.
    Use this input file format when providing a User-ID mapping for a login event, logout event, or for groups:
    <uid-message> 
     <version>1.0</version> 
     <type>update</type> 
     <payload> 
          <login> 
               <entry name="domain\uid1" ip="10.2.1.1" timeout="20"> 
               </entry> 
          </login> 
          <groups> 
               <entry name="group1"> 
                    <members> 
                         <entry name="user1"/> 
                         <entry name="user2"/> 
                    </members> 
               </entry> 
               <entry name="group2"> 
                    <members> 
                         <entry name="user3"/> 
                    </members> 
               </entry> 
          </groups> 
     </payload> 
</uid-message>
    You can include a HIP report by including a<hip-report></hip-report> XML container within an<entry> parent element.
    Multi-User System Entry
    Use the following input file format to set up a terminal server entry on the firewall and to specify the port range and block size of ports that will be assigned per user. If you are using the default port range (1025 to 65534) and block size (200) you do not need to send amultiusersystem setup message; the firewall will automatically create the terminal server object when it receives the first login message.
    <uid-message>
<payload>   
          <multiusersystem> 
              <entry ip="10.2.1.2" startport="xxxxx" endport="xxxxx"
blocksize="xxx">   
          </multiusersystem> 
     </payload>   
     <type>update</type>   
     <version>1.0</version>   
</uid-message>
    User-ID XML multiuser system login event
    When the terminal servers sends a login event payload to the firewall, it can contain multiple login events. The firewall uses the information in the information in the login message to populate its user mapping table. For example, if the firewall received a packet with a source address and port of 10.2.1.23:20101, it would map the request to user jparker for policy enforcement.
    <uid-message>
<payload>   
          <login> 
               <entry name="acme\jparker" ip="10.2.1.23" blockstart="20100"> 
          </login> 
     </payload> 
     <type>update</type> 
     <version>1.0</version> 
</uid-message>
    User-ID XML multiuser system logout
    Upon receipt of a logout event message with ablockstart parameter, the firewall removes the corresponding IP address-port-user mapping. If the logout message contains a username and IP address, but noblockstart 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.
    <uid-message>
<payload>  
          <logout>  
              <entry user="domain\uid2" ip="10.2.1.2" blockstart="xxxxx">
</logout>    
     </payload>   
     <type>update</type>   
     <version>1.0</version>   
</uid-message>
    Dynamic address group IP address registration
    Use the following input file format to dynamically register and unregister IP addresses.
    You can configure a timeout as part of the member element to automatically unregister IP address-to-tag mapping after a specified amount of time. By default, no timeout is specified meaning the mapping will not timeout and must be manually unregistered. Additionally, a timeout of zero (0) seconds does not timeout. You can specify a timeout between zero (0) seconds and 2,592,000 seconds (30 days).
    <uid-message>  
     <version>1.0</version>  
     <type>update</type>  
     <payload>       
         <register>  
             <entry ip="10.2.1.1">  
               <tag> 
		<member timeout="3600">CBB09C3D-3416-4734-BE90-0395B7598DE3</member>  
	   </tag> 
         	 </entry> 
         </register>  
          <unregister>  
               <entry ip="10.2.1.3"/>  
     <tag> 
		<member>CBB09C3D-3416-4734-BE90-0395B7598DE5</member>  
	     </tag> 
               </entry> 
          </unregister>  
     </payload>  
</uid-message>
    Register tags for a user to add that user to a dynamic user group
    Use the following input file format to dynamically register tags to a user and include that user in a dynamic user group.
    To register a tag for a user, that user must have an existing user mapping or group mapping.
    You can configure a timeout to automatically unregister the user-to-tag mapping after a specified amount of time. By default, no timeout is specified meaning the mapping will not timeout and must be manually unregistered. You can specify a timeout between zero (0) and 2,562,000 seconds (30 days). 
    <uid-message>
  <version>1.0</version>
  <type>update</type>
  <payload>
    <register-user>
      <entry user="paloaltonetworks\john">
        <tag>
          <member>finished_ethics_training</member>
          <member>mac_user</member>
        </tag>
      </entry>
      <entry user="paloaltonetworks\jane">
        <tag>
          <member timeout="120">building_1</member>
          <member>pc_user</member>
        </tag>
      </entry>
    </register-user>
  </payload>
</uid-message>
    Unregister specific tags for a user to remove that user from the dynamic user group
    Use the following input file format to unregister a specific dynamic tag from a user and remove the user from the dynamic user group associated with that tag. 
    <uid-message>
  <version>1.0</version>
  <type>update</type>
  <payload>
    <unregister-user>
      <entry user="paloaltonetworks\john">
        <tag>
          <member>mac_user</member>
        </tag>
      </entry>
    </unregister-user>
  </payload>
</uid-message>
    Unregister all tags for a user
    Use the following input file format to unregister all tags for a specific user. 
    <uid-message>
  <version>1.0</version>
  <type>update</type>
  <payload>
    <unregister-user>
      <entry user="paloaltonetworks\john">
      </entry>
    </unregister-user>
  </payload>
</uid-message>
    Clear all tags for all users
    Use the following input file format to unregister all tags from all users. 
    <uid-message>
  <version>1.0</version>
  <type>update</type>
  <payload>
    <clear>
      <registered-user>
        <all/>
      </registered-user>
    </clear>
  </payload>
</uid-message>

    © 2026 Palo Alto Networks, Inc. All rights reserved.