Configure 360Suite to communicate with SSL-enabled environments

Configure 360Suite to communicate with SSL-enabled environments

Overview

  • Goal: Configure the trustStore used by 360Suite on Windows 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:

  • That you have local administrator rights to modify the Tomcat service

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

Environment

  • Product version(s): All 360Suite versions

  • Operating system: Windows

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 360Suite's embedded Java (C:\Windows\360Suite\jdk-<version>\lib\security\cacerts) to the location of your choice (e.g. D:\SSL).

  • 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 360Suite for Windows, located at C:\Windows\360Suite\jdk-<version>\bin\keytool.exe. 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 "D:\SSL\certificate.crt" -keystore "D:\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.

A shortcut to 360Suite's Tomcat configuration can be found at <360Suite_installation_folder>/360.suite4.3/360Suite_Tomcat_For_BI_4.3.exe (for 360Suite for SAP BusinessObjects 4.3 in this case).

Example:

  • -Djavax.net.ssl.trustStore=D:\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