User-ID API Introduction¶
Overview¶
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 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:
Within the payload section you include a command. Each command has at least one entry.
There are several commands, but these are the most common:
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)