Palo Alto Networks User-ID
When a user’s network session starts, Airgate tells the Palo Alto Networks firewall which user has which IP address (User-ID). The firewall can then apply user- and group-based security policies to Wi-Fi and wired users without its own agent. When the session stops, Airgate logs the user out again. Optionally Airgate also registers the session’s roles as dynamic tags on the IP address, for dynamic address groups.
How it works
Section titled “How it works”Airgate sends a uid-message to https://<firewall>/api/ with
type=user-id, authenticated with an API key (X-PAN-KEY):
| Session event (RADIUS accounting) | Message |
|---|---|
session.start |
<login><entry name="CONTOSO\alice" ip="10.20.30.40" timeout="…"/></login> (+ <register> of the roles as tags) |
session.update (interim) |
the login again, only with Refresh login on interim updates |
session.stop |
<logout> (+ <unregister> of the tags) |
The messages of one IP address are sent in order, so a quick start and stop is always applied as login then logout. Each call is retried twice and written to the execution log.
Before you begin
Section titled “Before you begin”- RADIUS accounting from your switches and access points to Airgate, with
the client IP address (
Framed-IP-Address). Without a client IP in the session, nothing is sent. - A PAN-OS firewall or Panorama reachable from Airgate on HTTPS (directly or through a firewall rule that allows Airgate’s outbound addresses).
- A PAN-OS administrator account for Airgate (see Step 1).
- An Airgate administrator with
admin:write.
Step 1: Prepare the firewall
Section titled “Step 1: Prepare the firewall”-
In PAN-OS, open Device › Admin Roles and create a role with XML API › User-ID Agent enabled (and Operational Requests for the connection test). Disable web UI and CLI access for the role.
-
Open Device › Administrators and create an administrator
airgatewith that role and a strong password. -
Generate an API key for it, for example:
https://<firewall>/api/?type=keygen&user=airgate&password=<password>Copy the key from the
<key>element. Alternatively, let Airgate log in with the user name and password (it generates the key and keeps it 12 hours). -
Make sure User-ID is enabled on the zones where the users are (Network › Zones › Enable User Identification).
-
Commit.
Step 2: Add the firewall in Airgate
Section titled “Step 2: Add the firewall in Airgate”-
Open Settings › Webhooks, select the Integrations tab and, under Palo Alto Networks User-ID, select Add firewall (or Context servers › Add context server with the type Palo Alto Networks Firewall or Palo Alto Networks Panorama).
-
Fill in:
Field Value Name fw1Base URL https://fw1.contoso.comAuthentication API key (default) with the key, or Basic / user + password Palo Alto User-ID (login / logout on session start / stop) on User-ID domain for example CONTOSO: put in front of user names without\or@(alicebecomesCONTOSO\alice)Login timeout (minutes) 0uses the firewall’s default; otherwise the mapping’s timeoutRegister roles as dynamic IP tags on to tag the IP with the session’s roles Refresh login on interim updates on to refresh the mapping on interim accounting Skip MAC-address user names (MAB) on (default): MAC-authenticated devices have no user to map vsys for example vsys1on a multi-vsys firewallTarget firewall serial Panorama only: the managed firewall that receives the mapping Verify the server certificate on; add the firewall’s CA under Trusted CA certificate(s) when it is private -
Save and select Test connection. A success shows “PAN-OS XML API:” with the firewall’s system information.
Verify
Section titled “Verify”- Connect a test laptop with 802.1X.
- On the firewall:
show user ip-user-mapping ip <laptop IP>shows the user, with source XML API. With role tags:show object registered-ip ip <laptop IP>. - In Airgate, Settings › Webhooks › Integrations shows Sent (24h),
Failed (24h), Last success and Last error per firewall. The
User-ID log button opens the execution log with the
User-ID loginandUser-ID logoutcalls.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
| Nothing is sent | The session has no client IP (no Framed-IP-Address in accounting), the user name is a MAC address, or RADIUS accounting is off. |
Turn on accounting toward Airgate; check that interim updates carry the IP. |
Execution log: failed with a PAN-OS error 403 / “Invalid credentials” |
Wrong API key or the role lacks User-ID Agent. | Regenerate the key; check the admin role. |
| Mappings disappear early | The firewall’s default timeout is shorter than the session. | Set Login timeout (minutes), or turn on Refresh login on interim updates. |
| User names lack the domain on the firewall | User-ID domain is empty and users sign in with short names. | Set User-ID domain. |
| Panorama accepts the call but the firewall has no mapping | Target firewall serial is missing. | Enter the managed firewall’s serial. |