User-ID API Introduction

Overview

_images/userid-overview.png

The User-ID API is used for all dynamic changes to the firewall, not just User to IP mappings. A dynamic change is any change that doesn’t require a commit and includes the following:

User-ID API
User Login / Logout Creates and removes User to IP mappings
User / Group Membership Often retrieved from AD, you can supplement group info with the API
Host Information Profile (HIP) Information about the OS, disk encryption, antivirus, etc. of a host
Dynamic Address Groups Tag IP addresses with metadata and enforce policy on tags
Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API. Such external systems might include an Active Directory Server, Wireless AP Controller, Virtual Desktop Manager, Virtualization Orchestrator, or AWS Public Cloud. The API is used for systems that are not natively supported, such as a proprietary app, non-standard Radius server, or VPN concentrator. You can send updates to the firewall from these system using the User-ID API.

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document. The XML document is called a UID Message and is structured with 3 main parts:

_images/userid-message.png

Within the payload section you include a command. Each command has at least one entry.

_images/userid-command.png

There are several commands, but these are the most common:

User-ID API Commands
login Create a user to ip mapping
logout Remove a user to ip mapping
register Create a tag to ip mapping
unregister Remove a tag to ip mapping
register-user Create a tag to user mapping
unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation.

User-ID with pan-python

The panxapi.py -U option performs the type=user-id API request to perform dynamic updates. The cmd argument specifies the update message, and is an XML document. cmd can be an XML string, a path to a file containing XML, or the value “-” (single minus character) to specify the XML is on stdin.

The user-id API uses the <uid-message/> XML document for several types of dynamic updates, including:

  • User to IP mapping (ip-user)
    • show user ip-user-mapping ...
  • User to group mapping
    • show user group ...
  • tag to IP mapping (registered-ip)
    • show object registered-ip ...
    • Used in Dynamic Address Groups (DAGs)
  • tag to user mapping (registered-user)
    • show object registered-user ...
    • Used in Dynamic User Groups (DUGs)