Question

How do I set up the Integration Agent to accept HTTPS requests?

Environment

All versions of xMatters

Answer

In its out-of-box configuration, the Integration Agent (IA) is capable of sending requests to external systems (for example, the xMatters hosted instance) via HTTPS. However, if data needs to be received by the IA via HTTPS requests, then you will need to modify the configurations.

For help with SSL concepts and terminology, see SSL Troubleshooting for xMatters Integrations.

Installing an SSL/TLS Certificate on the Integration Agent

In order for an external system to successfully send HTTPS requests to the IA, the entity must trust the IA. This trust relationship requires that an SSL/TLS certificate is installed on the IA.

There are two types of certificate that can be installed to achieve this:

• A commercial/paid certificate (preferred)
• A self-signed certificate

Using a commercial/paid certificate

Although the preferred format for importing a commercial/paid certificate into the IA's keystore is as a .pfx file, commercial/paid certificates are generally not provided in .pfx format. Therefore, you can either:

• Convert the .cer and .key files provided by the certificate vendor into a .pfx file. You can find instructions on how to do this here. Or;
• Follow the certificate vendor's instructions for importing the certificate into a Java keystore.
  Note: The IA does not use the JRE's default trust store for storing its server certificate, so you won't be able to use the vendor's instructions if they result in the creation of a new .keystore file.

Importing a commercial/paid certificate

1. Open a command prompt or terminal window and cd to <IAHome>\conf
2. Back up the IA's existing .keystore file by copying it (e.g. to .keystore.orig).
3. If your certificate is in a .pfx file, import it into the IA's existing .keystore file using:

   ..\jre\bin\keytool -importkeystore -srckeystore \path\to\pfxfile\filename.pfx -srcstoretype pkcs12 -destkeystore .keystore

   Alternatively, you can use the vendor's instructions for importing the certificate into an existing java keystore.
4. Verify that the certificate has been imported:

   ..\jre\bin\keytool -list -keystore .keystore -storepass alarmpoint

   The result should be similar to:

   Keystore type: jks
   
   Keystore provider: SUN
   
   Your keystore contains 2 entries
   
   apia, Dec 6, 2007, PrivateKeyEntry,
   
   Certificate fingerprint (SHA1): 84:A6:(etc)
   
   new-cert, Aug 22, 2018, PrivateKeyEntry,
   
   Certificate fingerprint (SHA1): 82:7A:(etc)

   Note: The apia certificate is the one used by the iadmin tool.
5. In \conf\iaconfig.xml, configure the IA to accept HTTPS requests by replacing:

   <service-gateway ssl="false" port="8081"/>

   with

   <service-gateway ssl="true" port="8081"/>

   Then, restart the IA.
6. If the certificate was imported successfully, the management system will be able to send HTTPS requests to the IA. If non-HTTPS requests are being sent to the IA's port 8081, you will see a message like the following in the IA's log file:

   Unrecognized SSL message, plaintext connection?

7. You can test the installation of the IA's SSL certificate by using Curl to send an HTTPS post request to the IA's port 8081. If the IA's sample-plan integration service is enabled in IAConfig.xml, an example would be:

   curl -v -d "<?xml version="1.0" encoding="UTF-8"?><event><properties><building>\"Building A\"</building><city>Victoria</city></properties><recipients><targetName>bsmith</targetName></recipients></event>" https://hostname.domain.com:8081/http/applications_sample-plan

   Note: The host name and domain used for this request must match the FQDN in the SSL certificate that is installed in the IA's .keystore file.

For detailed troubleshooting information, see SSL Troubleshooting for xMatters Integrations.

Using a self-signed certificate

The alternative to using a commercial/paid certificate is to use a self-signed certificate. These certificates are advantageous as they don't cost anything and, as they only contain a single file, can be easier to import. The disadvantage is that self-signed certificates are not considered trustworthy, so a browser or other client software sending an HTTPS request will not accept a self-signed certificate unless that client has been specifically configured to do so.

Network administrators will often use self-signed certificates on internal servers. The installation process is essentially the same as for a commercial certificate as described above.

Importing a self-signed certificate

To configure a self-signed certificate installed on the IA, it is necessary to export the IA's public certificate, and then import it into the management system's Trust Store. The Trust Store contains SSL/TLS certificates that are considered trustworthy, even though they are not issued by a commercial provider.

1. Export the IA's self-signed certificate by accessing the IA's port 8081, which you can do by using a browser to export the certificate to a file. Instructions vary depending on the browser; for more information, you can use this reference.
2. Import the certificate from the file to the management system. Again, instructions will vary from one management system to another. However, if the system uses Java, you can use the same keytool utility as used in the paid/commercial certificate process. For example:

   <JREHome>\bin\keytool -importcert -keystore ../lib/security/cacerts -storepass changeit -file /path/to/somecert.cer -alias somecert

3. Ensure that the management system is sending requests to the same server that is named in the certificate's SubjectAlternativeName field. For example, if the certificate has server1.company.com in its SubjectAlternativeName field, then the management system will need to be sending its HTTPS requests to https://server1.company.com:8081 and not https://192.168.10.11:8081.
4. Finally, ensure that the management system can resolve the host name in the certificate's SubjectAlternativeName field.

For further troubleshooting information, see SSL Troubleshooting for xMatters Integrations.

xMatters does not necessarily endorse or support the information contained in the content linked from this article.