Add self-signed certificates to the backend trust store

Owned by Thomas Körbler
May 23, 2024
3 min read

General

If your Portrait instance needs to connect to other services over HTTPS, but the connection is encrypted with a self-signed certificate, you need to add this certificate to the list of trusted authorities inside the backend.

Java holds its own trust store that contains all valid Certificates. You can update a trust store to include your self-signed certs. This can be done with the keytool command, which comes included with the JDK/JRE.

The default location of the trust store is:

java-home/lib/security/cacerts

you can add a cert to this truststore with:

keytool -importcert -alias yourCert -file yourCert.cer -trustcacerts -cacerts

For details, please consult the official doc.

How To

This process has to be repeated each time a certificate needs to be renewed. Furthermore, it is important that your certificates should be added to the provided truststore. Do not create a new empty trust store and use only the self-signed certificates. This will impact other services!

1. Gather the .cer Files in your Portrait Config (vscode)

image-20240220-161954.png

2. Connect via SSH to the server

You will need to run shell commands on the server your portrait instance is running on.

3. Attach a shell to the backend container

Get the container name:

root@DOCKER:/home/support/portrait/prod# docker-compose ps Name Command State Ports ----------------------------------------------------------------------------------------------------- prod_backend_1 /__cacert_entrypoint.sh sh ... Up

Attach a shell:

docker exec -it prod_backend_1 /bin/bash

4. Import the certificate into default cacerts truststore

When asked about password use changeit
When asked for confirmation enter y

Repeat this step for each certificate.

5. Copy the modified cacerts to your vscode

6. Configure Portrait to use the custom truststore

Exit the backend container shell, if not done yet:

Then modify your .env file in the docker-compose.yml directory:

Now modify the line starting with BACKEND_JAVA_OPTS and add the referral to the trust store and password:

6. Restart

To make the changes work, “down” and “up” (not restart) the backend now: using docker-compose down and docker-compose up in your portrait instance folder.

Troubleshooting

In case you experience issues, or have troubles getting the new certs to run, you can start troubleshooting with extending the log output.

Add the -Djavax.net.debug=all inside the docker-compose.yml to the backend command:

Example:

Then docker-compose down and docker-compose up.

Afterwards, more information will be logged. However, not in the log file, only on the console in docker-compose.
To see the logs:

When using docker-compose restart, it is required to start the command again as it terminates when the container is stopped.

You search for something similar to this:

Do not forget, to remove the debug-logging property after you finished debugging.