User-ID XML API setup on Windows UID agent
24738
Created On 03/20/19 16:23 PM - Last Modified 03/21/19 09:38 AM
Symptom
In PanOS 8.0.x and later, when using XML API calls to add/delete user-IP mappings on a windows-based User-ID agent, the calls do not add the necessary mappings to the agent and subsequently, the traffic fails. This is seen to be true even if the XML API's were seen to work without any issues in the previous versions.
Cause
In PanOS 8.0.x and above, the windows-based User-ID agent now requires the API clients to authenticate themselves using an identity certificate issued by a Trusted Root CA server. This is done to avoid any malicious mappings from being listed or any mappings being maliciously removed by a unauthenticated user.
Resolution
With the re-introduction of the usage of XML API for the purpose of User-IP mapping addition on a Windows-based User-ID agents in 8.0, there is an additional requirement to make use of a client certificate on the API client for the purpose of authentication.
The following are the broad requirements for the Client ceritifcate:
1. The Client certificate can be issued either by Domain/Enterprise Root CA or by the Firewall CA server directly.
2. The issuing CA certificate needs to be placed in the "Trusted Root Certificate Authority" certificate store on the server/host where the Windows-based UID agent is installed.
3. The client needs to make use of the issued certificate to connect to the windows UID agent.
Once the identity certificate is issued to the Client, please consider using the following steps to configure and verify XML API connectivity to the windows-UID agent:
+ On the linux machine the client certificate should be imported in .pem format. In this scenario the client certificate is 'cert_xmlapi_clientcert.pem'
+ Use the command below to test sending the message to the userid agent
$ cat userid.xml | openssl s_client -cert cert_xmlapi_clientcert.pem -connect 10.193.113.143:5006
+ The following is a sample decode of the certificate information used in this process.
~$ openssl x509 -in cert_xmlapi_clientcert.pem -text -noout Certificate: Data: Version: 3 (0x2) Serial Number: 22 (0x16) Signature Algorithm: sha256WithRSAEncryption Issuer: CN=paloaltonetworks.local Validity Not Before: Jul 19 10:16:54 2017 GMT Not After : Jul 19 10:16:54 2018 GMT Subject: CN=xmlapi.paloaltonetworks.local Subject Public Key Info: Public Key Algorithm: rsaEncryption Public-Key: (2048 bit) Modulus: 00:d7:06:bf:46:86:1a:7d:36:4e:78:01:dd:4e:27: ff:7a:b6:0a:70:f6:06:8c:7f:35:c0:e8:07:ef:1c: e8:9d:a5:bb:c9:7b:b1:77:26:2a:7a:6e:dd:8b:0d: 09:7e:72:41:5a:0b:23:2c:96:08:ed:9e:4b:9b:ee: 2c:11:66:66:c5:b8:ba:9a:11:17:79:65:54:5a:ab: 99:5a:1e:5f:2c:71:af:a4:da:75:68:1a:11:ea:a0: 6e:a1:5d:db:11:bd:29:94:a5:fb:dc:cb:bf:33:36: b8:96:40:04:7d:5d:3a:32:24:0b:d1:c3:75:9c:a2: f8:ba:dd:28:87:6f:50:9f:45:3d:02:3d:1d:b0:bf: 32:ba:93:53:b8:07:4f:72:ad:fb:e4:72:5a:4d:92: 83:3d:b3:e4:dc:94:20:7b:00:e9:86:d6:79:e7:6f: 60:68:c0:a5:66:1a:a9:cf:83:24:f7:c6:ba:7a:60: df:db:fe:5a:de:27:6b:db:fd:b9:1a:7e:2e:e7:40: 3d:50:38:00:2a:71:71:2b:5f:f6:8e:b7:b6:87:bd: 00:7f:48:82:68:14:ce:a4:0b:92:51:2c:d2:8b:b8: 04:aa:6c:a3:aa:a9:74:99:80:cc:67:3e:5b:3c:9d: 3e:fc:0f:53:37:3f:0d:14:42:db:16:6d:f1:0a:fb: 92:55 Exponent: 65537 (0x10001) X509v3 extensions: X509v3 Basic Constraints: CA:FALSE X509v3 Key Usage: Digital Signature, Key Encipherment, Data Encipherment, Key Agreement X509v3 Extended Key Usage: TLS Web Server Authentication, TLS Web Client Authentication, IPSec End System X509v3 Authority Key Identifier: 0. X509v3 Subject Key Identifier: 5B:97:AF:6D:D2:99:E5:FE:AE:9E:24:A3:4B:F2:F6:7E:57:94:30:30 Signature Algorithm: sha256WithRSAEncryption bc:53:f4:68:8c:36:48:42:2f:3e:c0:43:ed:1e:a6:e6:96:61: c5:53:6a:37:42:ca:c6:e2:4c:be:76:3d:a5:18:70:f3:1a:9b: a1:42:d0:37:c9:3d:ff:dd:13:8c:55:a4:c6:aa:da:57:a1:19: 6e:f0:ed:82:6c:fd:b4:57:f9:26:21:46:d5:cd:95:8c:81:5e: ec:15:0f:86:4a:f8:f3:dc:d8:3b:50:bf:c9:cf:52:ec:80:62: 10:0b:7c:37:2c:b6:8e:85:45:23:bf:03:46:ee:c8:ab:5a:1a: 09:89:af:fb:4d:59:23:61:00:dc:73:9f:78:5e:fb:98:cf:cb: ca:d1:28:cb:0a:a6:e8:35:fe:b6:b1:64:bd:48:2b:d0:15:df: 9d:28:1f:5a:e7:0b:72:fe:f8:3a:c3:0a:f6:25:ef:eb:f4:80: 04:fc:01:f0:a9:2f:d9:31:e3:dd:42:18:df:70:8f:44:78:89: 0c:61:a4:c8:eb:8e:d7:0c:53:a3:f6:29:49:d6:7a:8d:8a:a5: ef:f7:c4:c2:73:21:25:dd:e9:3c:58:ba:5d:6f:c7:25:a8:a1: f5:d3:4a:b7:9e:81:d2:44:19:38:7f:65:23:48:e7:ba:16:35: 3f:ff:e5:e6:ff:86:9d:db:31:2c:74:25:d8:57:cc:2d:89:2b: db:02:c1:aa
+ Once the client is verified to be using the correct certificate, Install the CA certificate which issued the API client's client certificate in the Trusted Root Certifcation Store on the Windows server where User-ID agent is running, so that it would be validated as a trusted certificate.
+ To do so, run the command "mmc" from the Windows Run window. Once the MMC console opens, please add the "Certificates" Snap-in from the file menu. Add the snap-in for the Machine account.
+ Once added, please place the issuer CA certificate into "Certificates (Local Computer) -> Trusted Root Certificate Authorities -> Certificates"
Once the certificate is placed in the "Trusted Root Certificate Authority" store, please restart the User-ID agent service as the service reads the Certificate Store only once during initial startup.
+ After restarting the service, now enable the UID agent to receive XML API calls, using the option under User Identification -> Setup -> Edit -> Agent Service and select the option "Enable User-ID XML API" and specify the port as shown below:
Once the above steps are completed, you will start seeing the User-IP mapping being listed as indicated below:
Verification:
The logs for the successfull connection to the XMPALI client, certificate validation and user mapping etc can be seen in the UaDebug file of the User-ID agent on the windows server as listed below:3:10:22:314[ Info 703]: New xml api connection 10.193.113.134 : 1959:1497568953. 07/19/17 13:10:22:314[ Info 747]: XML api thread 0 from 10.193.113.134 : 1959 is started. 07/19/17 13:10:22:314[Debug 355]: Event: type="XML API connection" name="10.193.113.134" status="Connected" 07/19/17 13:10:22:314[Debug 1778]: Device thread 0 send server status 10.193.113.134 : 1959 Connected (XML API) 07/19/17 13:10:22:314[Verbo 1264]: send out 268B msg post:server_status time 1500462622 with 0B body 07/19/17 13:10:22:314[Verbo 209]: CStrPairUpdate 10.193.113.134 : 1959 Connected (XML API) is freed. 07/19/17 13:10:22:317[Debug 419]: Verifying cert = /CN=xmlapi.paloaltonetworks.local 07/19/17 13:10:22:317[Debug 465]: A new certificate context has been created for /CN=xmlapi.paloaltonetworks.local. 07/19/17 13:10:22:318[Debug 381]: Got the issuer context for paloaltonetworks.local 07/19/17 13:10:22:318[ Info 371]: The self signed issuer is found in the trust store 07/19/17 13:10:22:318[Debug 481]: Certificate with subject : /CN=xmlapi.paloaltonetworks.local is valid 07/19/17 13:10:22:318[Debug 419]: Verifying cert = /CN=xmlapi.paloaltonetworks.local 07/19/17 13:10:22:318[Debug 465]: A new certificate context has been created for /CN=xmlapi.paloaltonetworks.local. 07/19/17 13:10:22:318[Debug 381]: Got the issuer context for paloaltonetworks.local 07/19/17 13:10:22:318[ Info 371]: The self signed issuer is found in the trust store 07/19/17 13:10:22:318[Debug 481]: Certificate with subject : /CN=xmlapi.paloaltonetworks.local is valid 07/19/17 13:10:22:318[Debug 419]: Verifying cert = /CN=xmlapi.paloaltonetworks.local 07/19/17 13:10:22:318[Debug 465]: A new certificate context has been created for /CN=xmlapi.paloaltonetworks.local. 07/19/17 13:10:22:319[Debug 381]: Got the issuer context for paloaltonetworks.local 07/19/17 13:10:22:319[ Info 371]: The self signed issuer is found in the trust store 07/19/17 13:10:22:319[Debug 481]: Certificate with subject : /CN=xmlapi.paloaltonetworks.local is valid 07/19/17 13:10:22:327[ Info 619]: XML api thread 0 accept finished 07/19/17 13:10:22:327[Debug 659]: XML api thread 0 SSL subject: /CN=xmlapi.paloaltonetworks.local 07/19/17 13:10:22:327[Debug 672]: XML api thread 0 SSL issuer: /CN=paloaltonetworks.local 07/19/17 13:10:22:328[Debug 325]: UserIpMap: IP 10.1.1.1 with login name domain\uid1 and timeout 1200 is added type (1). tId (3736) 07/19/17 13:10:22:328[Debug 1060]: Adding ip to chg tbl 10.1.1.1 for Add 07/19/17 13:10:22:332[ Info 580]: XML api thread 0 timeout or SSL error: 5-10053. 07/19/17 13:10:22:332[Debug 590]: XML api thread 0 ssl shutdown. 07/19/17 13:10:22:332[Verbo 1264]: send out 163B msg post:xml_data time 1500462622 with 174B body 07/19/17 13:10:22:332[Debug 355]: Event: type="XML API connection" name="10.193.113.134" status="Disconnected" 07/19/17 13:10:22:333[Debug 415]: XML api thread 0 exits. 07/19/17 13:10:22:333[ Info 417]: XML api connection 10.193.113.134 : 1959 closed. 07/19/17 13:10:22:333[Debug 431]: All XML api connection stopped! 07/19/17 13:10:22:370[Verbo 1264]: send out 163B msg post:xml_data time 1500462622 with 174B body 07/19/17 13:10:22:384[Debug 472]: UserIpMap: IP (10.1.1.1) Username (domain\uid1) queued for xmission to firewall 07/19/17 13:10:22:435[Debug 1778]: Device thread 0 send server status 10.193.113.134 : 1959 Disconnected (XML API) 07/19/17 13:10:22:435[Verbo 1264]: send out 271B msg post:server_status time 1500462622 with 0B body 07/19/17 13:10:22:435[Verbo 209]: CStrPairUpdate 10.193.113.134 : 1959 Disconnected (XML API) is freed.