Configure 360Suite to communicate with SSL-enabled environments

Configure 360Suite to communicate with SSL-enabled environments

Context

Many 360Suite modules need to communication with the BOBJ RESTful API to process specific actions, often "Webi and UNX"-related actions. The features using this RESTful API are the following ones:
  1. 360Bind (opening and working with Webi documents)
  2. 360Cast (opening and working with Webi documents)
  3. 360Eyes (Webi job)
  4. 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 ensure it is 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 would usually result in an error preventing a process to complete 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

Configuration

Alert
Disclaimer: 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 provide basic help with these instructions only.

Fetch the proper certificate(s)

The certificate(s) required to communicate with the RESTful service are usually delivered by an infrastructure team, managing the security organisation-wide. These can come in different formats like:
  1. .cer
  2. .crt
  3. .pem
Other formats like .jks, .p12, and .pfx are not certificates themselves, rather keyStores (or trustStores, depending on their content) that contain certificates. It is therefore possible to have a trustStore such as this, provided as "certificate", if it contains only 1 certificate. In such case, this trustStore can be used as is and the "Create a new trustStore" and "Import the certificate(s)" steps below can be skipped. If not, then it will be required to extract the proper certificate from this trustStore.

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). As it is not recommended to modify this default "cacerts" trustStore, instead we will make a copy of this trustStore and save it in a different (custom) location. This copy can be done manually, just like any other file.

Example: copy and rename the default "cacerts" trustStore from 360Suite's embedded Java: "C:\Windows\360Suite\jdk-<version>\lib\security\cacerts" to "D:\SSL\360Suite_trustStore.p12".

Import the certificate(s)

Importing a certificate into a trustStore requires a tool named "Keytool", which is part of any Java deployment, meaning that if the keytool command isn't available globally in your environment, it is still possible to use the one provided with the installation of 360Suite for Windows, located in "C:\Windows\360Suite\jdk-<version>\bin\keytool.exe". Keytool helps managing keyStores and trustStores.

With the help of Keytool, we will add our 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 elements in italic to customise according to your settings:
  1. <mycert> is the name given as a reference in this trustStore for the given certificate,
  2. <certificate.file> is the path to the actual certificate (in .cer, .crt, or .pem format),
  3. <new_trustStore_name> is the name given to your to-be-created trustStore,
  4. <new_trustStore_password> is the password given to your trustStore.
Repeat this operation for every certificate that needs to be added to the trustStore.
Info
Note: 2 types of trustStores exist: JKS and P12. Both can contain the certificates needed to allow the communication between an application and an SSL-enabled service.
The PKCS12 format is the preferred format and is the default one since Java 9.

Example:
  1. keytool -improt -alias "RESTful_Certificate" -file "D:\SSL\certificate.crt" -keystore "D:\SSL\360Suite_trustStore.p12" -storepass "changeit"

Referencing the trustStore

Now that the trustStore is complete, it can be referenced in the Tomcat Java options. For that, we will add 2 arguments to the Java options: "javax.net.ssl.trustStore" and "javax.net.ssl.trustStorePassword". These arguments (or options) will need to have a leading -D before their name, and their value will be appended after the equal sign (=). The value of the first argument will be the path to the trustStore to use, and the second argument's value will be that trustStore's password.
A shortcut to 360Suite's Tomcat configuration can be found in <360Suite_installation_folder>/360.suite4.3/360Suite_Tomcat_For_BI_4.3.exe" (for 360Suite for SAP BusinessObjects 4.3 in this case).

Example:
  1. -Djavax.net.ssl.trustStore=D:\SSL\360Suite_trustStore.p12
  2. -Djavax.net.ssl.trustStorePassword=changeit

Final step

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

Alert
Important: the information provided in this article only allow the 360Suite application to communicate with SSL-enabled services like SAP BusinessObjects' RESTful service.
This will not make the 360Suite application configured with SSL over HTTPS.

    • Related Articles

    • How to configure SQL Server with Windows Authentication

      Symptom When trying to configure a SQL Server database using Windows Authentication as part of the 360eyes database configuration, the following error is returned: "The driver is not configured for integrated authentication". Environment 360Eyes ...

    • DB011/DB02 - How to configure the 360Suite database with SQL Server AD Domain account

      Symptom When configuring the database in the Web Platform Administration Console with a AD Domain account for SQL Server, you encounter one of the following errors : - DB012: Could not find driver - DB011: This driver is not configured for integrated ...

    • Configure 360Eyes to run on SAP Business Objects 4.3SP2

      Symptom You run 360Eyes using the 360Eyes GUI or Command-Line against an SAP Business Objects Environment 4.3SP2. or  java -Xmx1024m -cp "../libs/;*%SDK_LIB_FOLDER%/*" com.gbs.eyes.Launcher <job> <cms> <BO_user> <BO_user_passwd> <auth> <360Eyes_dir> ...

    • SEN015 warning when configuring the SMTP server

      Symptom The following warning appears: SEN015 The request was aborted: Could not create SSL/TLS secure channel. When an email is sent by the application: SMTP Configuration Test in the Administration Console. Email notifications in a task, watcher, ...

    • How to promote a single folder

      How to Promote a Single Folder Using 360Plus Overview This article explains the steps to promote a single public folder using 360Plus. This functionality is useful when you want to migrate specific content between SAP BusinessObjects environments ...