Configure 360Suite to communicate with SSL-enabled environments (Linux version)

Configure 360Suite to communicate with SSL-enabled environments (Linux version)

Overview

  • Goal: Configure the trustStore used by 360Suite on Linux so it can communicate with SSL-enabled BOBJ RESTful API services.

  • Target audience: System Administrator 

  • Estimated time: 15-30 minutes

Many 360Suite modules need to communicate with the BOBJ RESTful API to process specific actions, often related to Webi and UNX documents. The features using this RESTful API are the following:

  • 360Bind (opening and working with Webi documents)

  • 360Cast (opening and working with Webi documents)

  • 360Eyes (Webi job)

  • Premium: Repoint Webi (changing Webi data sources)

In such situations, 360Suite acts as a client and the RESTful API as the server (or service). When the service has been configured with SSL through a secured connection (HTTPS) - usually done using a certificate and a private key in a keyStore - then 360Suite also needs to have this certificate in its trustStore to be allowed to communicate with this RESTful service. A keyStore is used to configure a service (i.e. enable SSL for that service), whereas a trustStore is used to allow an application to communicate with SSL-enabled services.

Not configuring a client application accordingly usually results in an error preventing a process from completing successfully. A typical resulting error is:
  1. sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Warnings & Prerequisites

Warning
Warning: all subsequent information can be found online on public SSL-related articles and forums, as this is not 360Suite-specific. In case of doubt, please review it with a security expert. Wiiisdom can only provide basic help with these instructions.

Before you start, confirm:

  • You have root / sudo privilege (if you have to modify the tomcat service) or you use the tomcat administrator user

  • The required certificate(s) have been obtained from your infrastructure/security team

Environment

  • Product version(s): All 360Suite versions

  • Operating system: Linux

Procedure

Step 1: Fetch the proper certificate(s)

The certificate(s) required to communicate with the RESTful service are usually delivered by an infrastructure team managing security organisation-wide. These can come in different formats, such as:

  • .cer

  • .crt

  • .pem

Other formats like .jks, .p12, and .pfx are not certificates themselves, but rather keyStores (or trustStores, depending on their content) that contain certificates. It is possible to have a trustStore like this provided as a "certificate" if it contains only one certificate. In that case, the trustStore can be used as is, and the "Create a new trustStore" and "Import the certificate(s)" steps below can be skipped. Otherwise, the proper certificate must be extracted from this trustStore first.

Step 2: Create a new trustStore

Java embeds a default trustStore named cacerts in the <java_home>/lib/security folder, containing many default security certificates and certificate authorities (CA). Since it is not recommended to modify this default cacerts trustStore, make a copy of it and save it in a different (custom) location. This copy can be done manually, just like for any other file.

Example:

  • Copy the default cacerts trustStore from the 360 Tomcat JVM (<java_home>/lib/security/cacerts) to the location of your choice.

  • Rename it to something different from cacerts (e.g. 360Suite_trustStore.p12).


Step 3: Import the certificate(s)

Importing a certificate into a trustStore requires a tool named keytool, which is part of any Java deployment. If the keytool command isn't available globally in your environment, you can still use the one provided with the installation of the 360 Tomcat JVM, located at <java_home>/bin/keytool. Keytool helps manage keyStores and trustStores.

With Keytool, add your certificate to the trustStore created previously using the following command:
  1. keytool -importcert -alias <mycert> -file <certificate.file> -keystore <path_to_my_trustStore> -storepass <trustStore_password>
Where the italicized elements must be customized according to your settings:

  • <mycert> is the reference name given to the certificate in this trustStore.

  • <certificate.file> is the path to the actual certificate (in .cer, .crt, or .pem format).

  • <path_to_my_trustStore> is the path to the trustStore created in Step 2.

  • <trustStore_password> is the password of your trustStore.

Repeat this operation for every certificate that needs to be added to the trustStore.
Info
Note: Two types of trustStores exist: JKS and P12. Both can contain the certificates needed to allow communication between an application and an SSL-enabled service. The PKCS12 format is the preferred format and has been the default since Java 9.

Example:
  1. keytool -import -alias "RESTful_Certificate" -file "/opt/ssl/certificate.crt" -keystore "/opt/ssl/360Suite_trustStore.p12" -storepass "changeit"

Step 4: Reference the trustStore in Tomcat

Once the trustStore is complete, reference it in the Tomcat Java options. Add two arguments: javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword. Each argument needs a leading -D before its name, with its value appended after the equal sign (=). The first argument's value is the path to the trustStore to use; the second is that trustStore's password.

The Java options for 360Suite's Tomcat can be configured either in the Tomcat service configuration file (default location: /etc/systemd/system/tomcat.service), or in a dedicated file inside Tomcat's bin folder (usually: <360_Tomcat>/bin/setenv.sh).
Whichever method you use, these Java arguments must be applied when the Tomcat service starts.

Example:

  • In the Tomcat service configuration file:

Environment="JAVA_OPTS=-Djavax.net.ssl.trustStore=/opt/ssl/360Suite_trustStore.p12 -Djavax.net.ssl.trustStorePassword=changeit"

  • In the Tomcat setenv.sh file:

export JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=/opt/ssl/360Suite_trustStore.p12 -Djavax.net.ssl.trustStorePassword=changeit"

Step 5: Restart the Tomcat service

Once the certificate has been added to the trustStore and the path to the trustStore has been configured in the Tomcat Java options, restart the Tomcat service for the changes to be applied.

Validation & Verification

How to confirm success: 360Suite successfully communicates with the SAP BusinessObjects RESTful service (when configured with SSL), without triggering the PKIX/certification path error described above.

Warning
Warning: the information in this article only allows 360Suite to communicate with SSL-enabled services, such as SAP BusinessObjects' RESTful service. It does not configure the 360Suite application itself with SSL over HTTPS.

Troubleshooting

Problem Possible Cause Solution

javax.net.ssl.SSLException: Unexpected error: java.security.InvalidAlgorithmParameterException: the trustAnchors parameter must be non-empty

The trustStore file is empty or corrupted, so it does not contain any usable certificate (trust anchor).

Retrieve a new cacerts file from a trusted source (ex: Java from the 360Suite Setup) and reapply the procedure described in this article, starting from Step 2: Create a new trustStore.

See Also