Issue Details
When the xMatters integration agent log includes an AUTHENTICATION_ERROR entry, it's typically caused by a webserver user/password mismatch. This article will help you troubleshoot the most common causes of this error.
Specific Error Messages
Here is an example of the error that will be written to the IA log if the username (in <IAHome>\conf\iaconfig.xml) or password is incorrect.
2015-03-05 16:38:25,996 [Heartbeat-1] ERROR - The xMatters Server returned the response AUTHENTICATION_ERROR, which resulted in an exception. 2015-03-05 16:38:26,004 [Heartbeat-1] ERROR - HEARTBEAT_UNEXPECTED_ERROR
This message will be written every time a heartbeat is attempted (every 10 seconds by default.)
If the password file cannot be located, then a message similar to the following will be written when the integration first starts up:
2015-03-05 16:39:03,841 [WrapperSimpleAppMain] WARN - Unable to decrypt the Web Service user password file located at ./.wspasswds. An empty password will be used, but this will likely cause the Integration Agents heartbeats to be rejected.
com.alarmpoint.integrationagent.exceptions.FileNotFoundException: The path ./.wspasswds was resolved to C:\xMatters\integrationagent-5.1.4\conf\.wspasswds, but does not refer to an existing file.
Subsequently, the "HEARTBEAT_UNEXPECTED_ERROR" messages will be written as described above.
If the Company name does not match a company that exists in xMatters, the messages in the IA log will be similar to the following:
2015-03-05 16:46:18,329 [Heartbeat-1] ERROR - The xMatters Server returned the response COMPANY_DOES_NOT_EXIST, which resulted in an exception.
2015-03-05 16:46:18,330 [Heartbeat-1] ERROR - HEARTBEAT_UNEXPECTED_ERROR
com.alarmpoint.integrationagent.exceptions.HeartbeatRejectedException: The xMatters Server at http://10.2.0.121:8888/api/services/AlarmPointWebService rejected the heartbeat/registration with the following reason: COMPANY_DOES_NOT_EXIST
Note that the company name is not case-sensitive.
Solution
By default, new integration agent installs don't have the .wspasswd file (this is where the password is stored for the IA_User that is referenced in the IAConfig.xml file).
To begin troubleshooting this issue, first confirm that the password file exists. Open the IAConfig.xml file and locate the <web-services-auth> section:
<web-services-auth>
<!--
| A string that is trimmed of leading/trailing whitespace and may be left blank.
+-->
<user>IA_User</user>
<!--
| A path (relative to this file), that refers to a file containing the
| encrypted (via iapassword), WS user's password. If the path is blank
| or does not refer to an existing file, an empty string is used for the password.
+-->
<password>
<file>./.wspasswd</file>
</password>
<!--
| A string that is trimmed of leading/trailing whitespace and may be left blank
| to refer to the default company.
+-->
<company>Default Company</company>
</web-services-auth>
The <user> field
The <user> field is the webservice user that the integration agent uses to connect to the xMatters web server. To ensure this value exists and the spelling is exactly the same, log in to the xMatters user interface as an administrator and search for this value under the Users tab, in the "WEB SERVICE USERS" section. (The default username is IA_User.)
Also ensure that this web service user account has the 'Register Integration Agent', 'Submit APXML', and 'Receive APXML' permissions enabled in the xMatters user interface. In some cases we've encountered, security-conscious admins have been removing these rights from the IA_User account and thus caused errors.
The <file> field
The <file> field value is the path to where the encrypted password is stored. Confirm that the referenced file contains the password created using the iapassword utility (for details, see the Integration Agent Guide). (The default password is ia_complex).
The <company> field
The last section is the <company> field, which normally causes the UNKNOWN_COMPANY error to be logged when misconfigured. Ensure that the content of this field matches the company that is present in the web user interface. For example, sometimes the <company>field includes special characters (e.g., the registered trademark symbol); in these cases, copy the Company name from the UI and paste it into the <company> field in the IAConfig.xml file. (The default value is Default Company.)
If you're still experiencing the AUTHENTICATION_ERROR
If confirming the proper values in the fields above does not resolve the issue, set the log level to DEBUG in the log4j.xml file by ensuring the following lines are not commented out:
<!-- Heartbeats --> <logger name="com.alarmpoint.integrationagent.heartbeat"> <level value="DEBUG"/> </logger> <!-- APXML Message Exchanger --> <logger name="com.alarmpoint.integrationagent.messaging"> <level value="DEBUG"/> </logger>
Comments
3 commentsPlease sign in to leave a comment.
Oh man. I hit this all the time and I bash my head against the desk. This is a great reminder for all the things to check.
Glad you like this one, Travis. Thanks to Kim for filing the ticket, and to Jeremy B. for helping me 'interpret' Kim.
The <company> field section. Piece of advice, this section wants you to check/amend the company name field in you systems properties, not xMatters. We had this issue in ServiceNow as our NP/Non Production instances need to talk with the xMatters NP instance for testing. So the company property needs amending post clone to match the NP instance of xMatters.