Skip to content

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.

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.

  • 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.
  1. 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.

  2. Open Device › Administrators and create an administrator airgate with that role and a strong password.

  3. 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).

  4. Make sure User-ID is enabled on the zones where the users are (Network › Zones › Enable User Identification).

  5. Commit.

  1. 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).

  2. Fill in:

    Field Value
    Name fw1
    Base URL https://fw1.contoso.com
    Authentication 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 @ (alice becomes CONTOSO\alice)
    Login timeout (minutes) 0 uses the firewall’s default; otherwise the mapping’s timeout
    Register 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 vsys1 on a multi-vsys firewall
    Target 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
  3. Save and select Test connection. A success shows “PAN-OS XML API:” with the firewall’s system information.

  1. Connect a test laptop with 802.1X.
  2. 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>.
  3. 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 login and User-ID logout calls.
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.
© 2026 Airowire Networks Pvt. Ltd. Airgate is a product of Airowire.Product · Release notes · Security