How to configure IBM Docs for secure internal communications

First things first:

IBM does not officially support secure internal communications via HTTPS in IBM Docs.
So, if you want to keep your support via PMRs, then you should probably not implement this – or be able to reset it if necessary (- yes it’s possible!).

Now to the interesting part:

The configuration is actually pretty easy, since each installation comes with the “cfg.properties” file, where you can simply configure secure URLs to activate HTTPS.
Let’s visualise this on an example file for the Docs component:

[Docs]
docs_install_root=/ibm/Docs
shared_data_dir=/ibm/data/shared
was_install_root=/ibm/WebSphere/AppServer
was_soap_port=8879
scope=Cluster
scope_name=DocsCluster
node_name=
db_type=db2
db_hostname=db.host.com
db_port=50001
db_name = CONCORD
db_jdbc_driver_path=/ibm/WebSphere/db2
conversion_url=https://connections.host.com/conversion
ic_admin_j2c_alias=docsAdmin
files_url=https://connections.host.com/files
email_url=https://connections.host.com/connections
auth_type=FORM
auth_host=
mt=false
software_mode = Premise
spreadsheet_nodejs_install=false

Do this for all components and you are almost good to go! Almost that is…
If you configured self-signed certificates on your HTTP server, you will run into problems and the environment will not work! Even if you have trusted the self-signed certificate into the trust store of the cell (WAS), the Docs components will not work.

Cause:

This behaviour is due to the fact that Docs does not check the WAS trust store for certificates but the trust store of the provided Java installation. Yes, these are completely different files.

Solution:

A really simple solution, which you should always consider, is using officially signed certificates. They are cheap to get and in most cases you save yourself some trouble.

In some environments however this does not make sense. For example in short living / rapidly changing internal setups like test or development. Here you would want to use your generated and self-signed certificates. For this to work, you will need to add these to the just mentioned Java trust store.
This is a bit tricky, because there is no build-in way to do this (or at least I don’t know any – correct me if I’m wrong). We use a small jar file which we put together for this:

https-tools-0.0.2-SNAPSHOT.jar

Usage:
java -jar JAR-FILE SERVER PATHTO DEFAULTPASS

JAR-FILE	= https-tools-0.0.2-SNAPSHOT.jar
SERVER		= "connections.host.com" (HTTP server)
PATHTO		= /ibm/WebSphere/AppServer/java/jre/lib/security/cacerts
DEFAULTPASS	= yourPassword (default: "changeit")

After adding the certificate(s) to the trust store, you will have to restart the environment for the changes to take effect. You will now use secure communications between the different Docs components.

If you are interested in the jar file, feel free to contact me or leave a comment. Just keep in mind that it comes without any support 🙂

One thought on “How to configure IBM Docs for secure internal communications

Leave a Reply

Your email address will not be published. Required fields are marked *