Configure SSL (HTTPS) in Pentaho BA Server

Business Need

If an user enters a username and password to login to an application, an attacker can easily see their username and password in clear text. This would allow someone else to impersonate your user, but it allows for a far more dangerous possibility.

If an attacker is able to intercept all data being sent between a browser and a web server, they can see and use that information.

In that case, how can we secure Pentaho server which contains sensitive information sent across the web?


SSL (Secure Sockets Layer) is a standard security technology for establishing an encrypted link between a server and a client—typically a web server and a browser

In order to implement SSL, a web server must have an associated Certificate for each external interface (IP address) that accepts secure connections.

The theory behind this design is that a server should provide some kind of reasonable assurance that its owner is who you think it is, particularly before receiving any sensitive information.

This certificate is cryptographically signed by its owner, and is therefore extremely difficult for anyone else to forge.

For the certificate to work in the visitors browsers without warnings, it needs to be signed by a trusted third party. These are called Certificate Authorities (CAs).

Java provides a relatively simple command-line tool, called keytool, which can easily create a “self-signed” Certificate.

Self-signed Certificates are simply user generated Certificates which have not been signed by a well-known CA and are, therefore, not really guaranteed to be authentic at all.
While self-signed certificates can be useful for some testing scenarios, they are not suitable for any form of production use.

If we already have an SSL certificate through a certificate authority such as Thawte or Verisign, we need to configure our Pentaho application server to use the certificate.


By default, the Pentaho BA Server and User Console are configured to communicate over HTTP. To switch to HTTPS, follow the instructions below that apply to your scenario.

Enable SSL in the BA Server with a Certificate Authority
Create a local Certificate Signing Request (CSR)

In order to obtain a Certificate from the Certificate Authority of our choice we have to create a so called Certificate Signing Request (CSR).

That CSR will be used by the Certificate Authority to create a Certificate that will identify your website as “secure”.

To create a CSR follow these steps:

Create a local self-signed Certificate (as described in the previous section):

keytool -genkey -alias tomcat -keyalg RSA -keystore

The CSR is then created with:

keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr -keystore

Now we have a file called certreq.csr that you can submit to the Certificate Authority (like, or In return we get a Certificate

Importing the Certificate

Now that we have our Certificate we can import it into our local keystore.

First of all we have to import a so called Chain Certificate or Root Certificate into our keystore.

After that we can proceed with importing our Certificate.

Download a Chain Certificate from the Certificate Authority we obtained the Certificate from.

Import the Chain Certificate into your keystore

keytool -import -alias root -keystore -trustcacerts -file

And finally import your new Certificate

keytool -import -alias tomcat -keystore -file

Enable SSL in the BA Server With a Self-Signed Certificate

Prepare the Certificate Keystore

The RSA algorithm should be preferred as a secure algorithm, and this also ensures general compatibility with other servers and components.

This command will create a new file, in the home directory of the user under which you run it, named “.keystore”.

To specify a different location or filename, add the -keystore parameter, followed by the complete pathname to your keystore file, to the keytool command shown above.

For example:

“%JAVA_HOME%\bin\keytool” -genkey -alias tomcat -keyalg RSA -keystore \path\to\my\.keystore
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore /path/to/my/.keystore

After executing this command, you will first be prompted for the keystore password. The default password used by Tomcat is “changeit” (all lower case), although you can specify a custom password if you like.

Edit the Tomcat Configuration File

We need to configure the Connector in the ../Pentaho/Server/biserver-ee/tomcat/conf/server.xml file.
Locate for the below line and comment using tags

 <Connector URIEncoding="UTF-8" port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
    maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
    clientAuth="false" sslProtocol="TLS" /> 

Also make sure the below lines are also commented

<Connector URIEncoding="UTF-8" port="8443" 
maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"/>

Add the new line below the above mentioned line in server.xml file

<Connector URIEncoding="UTF-8" port="8443" 
keystorePass="KEYSTORE PASSWORD" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150" SSLEnabled="true" scheme="https" secure="true" 
clientAuth="false" sslProtocol="TLS" />

Trust a Self-Signed Certificate

The instructions below explain how to complete the trust relationship between the BA Server (when it is configured for SSL) and the User Console.

Change to the home directory of the user account that starts the BA Server and Pentaho User Console processes or services.
cd ~
Using the default settings suggested by Pentaho, this will be /home/pentaho/.

Execute the following command, changing the storepass (pass in the example) and keypass (pass2 in the example) accordingly:

keytool -export -alias tomcat -file tomcat.cer -storepass pass -keypass pass2 -keystore .keystore

Change to the $PENTAHO_JAVA_HOME/jre/lib/security/ directory.

cd $PENTAHO_JAVA_HOME/jre/lib/security/
The PENTAHO_JAVA_HOME variable was established during your production installation procedure. If you are on Windows, environment variables are surrounded by percent signs, as in: cd %PENTAHO_JAVA_HOME%\jre\lib\security\. If you get an error about this path not being valid, then use JAVA_HOME instead of PENTAHO_JAVA_HOME.

Execute the following command, changing the alias (tomcat in the example), the file path to the certificate (the current user’s home directory in

the example), and the storepass (pass in the example) accordingly:

keytool -import -alias tomcat -file ~/tomcat.cer -keystore cacerts -storepass pass

Note: If the path to your certificate involves spaces, you must either escape the spaces (on Linux, Unix, and OS X), or put double quotes around

the path (on Windows) in order for the command to work properly.

Execute the following command and make note of the MD5 sum for the tomcat entry.

keytool -list -keystore cacerts

Change back to the home directory of the user account that starts the BA Server and User Console, and run this command:
keytool -list -keystore .keystore

Compare the tomcat entry’s MD5 sum to the one you generated previously and ensure that they match. If these sums do not match, you’ve made a mistake someplace in the certificate trust process. Go through the steps again and ensure that you’re working with the right user accounts and directories.
The BA Server is now configured to allow access via SSL.

Change the BA Server Fully Qualified URL

If you switch from HTTP to HTTPS, you must also change the BA Server’s tokenized fully qualified URL value to accommodate for the new port number. Follow the directions below to change the fully qualified URL.

Stop the BA Server if it is currently running.

Navigate to the pentaho/server/biserver-ee/pentaho-solutions/system directory.

Open the file with any text editor.

Locate this element and modify the port number to match your SSL-enabled port number(eg. 8443).


Save and close the file.

Start the BA Server and make sure that it is available through HTTPS on the specified port.
The BA Server is now configured to communicate on an SSL-aware port.

Common Problems

In case we use self signed certificate, it will prompt the pentaho user console to display a security alert because the certificate was not verified by a trusted Certificate Authority.
Self-signed certificates aren’t trusted by browsers because they are generated by our pentaho server, not by a CA.

A red cross mark will appear in the browser URL tab which indicates that the page is not trusted by CA.