/
Add self-signed certificates to the backend trust store

Add self-signed certificates to the backend trust store

Owned by Thomas Körbler
Last updated: Feb 22, 2024 by Dominik Rainer
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

keytool -importcert -alias yourAlias -file /opt/portrait/app/config/certificates/customCert1.cer -trustcacerts -cacerts

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

cp $JAVA_HOME/lib/security/cacerts /opt/portrait/app/config/cacerts_WithCustomCerts

6. Configure Portrait to use the custom truststore

Exit the backend container shell, if not done yet:

exit

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

nano .env

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

BACKEND_TAG=stable-6.4.4 FRONTEND_TAG=stable-6.4.4 PYTHON_RUNTIME_TAG=stable-6.4.4 BACKEND_JAVA_OPTS="-Djavax.net.ssl.trustStore=/opt/portrait/app/config/cacerts_WithCustomCerts -Djavax.net.ssl.trustStorePassword=changeit -XX:MaxRAMPercentage=50"

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:

backend: image: treskon/portrait:${BACKEND_TAG:?err} restart: unless-stopped command: sh -c "chmod 777 config/wait-for.sh && ./config/wait-for.sh -t 25 index:9200 -- java -Djavax.net.debug=all -Djavax.net.ssl.trustStore=/opt/portrait/app/config/portrait_truststore -Djavax.net.ssl.trustStorePassword=changeit ${BACKEND_JAVA_OPTS} -jar portrait-app.jar --spring.config.location=config/application-prod.yml,optional:config/application-prepopulateUsers.yml && tail -F anything"] depends_on: - index

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:

docker-compose logs --follow --tail 10 backend > app/logs/realLog.log

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:

[36prod-backend-1 |[0m javax.net.ssl|DEBUG|10|main|2024-02-20 15:38:51.080 UTC|TrustStoreManager.java:113|trustStore is: /opt/portrait/app/config/portrait_truststore [36prod-backend-1 |[0m trustStore type is: pkcs12 [36prod-backend-1 |[0m trustStore provider is: [36prod-backend-1 |[0m the last modified time is: Tue Feb 20 15:32:33 UTC 2024 [36prod-backend-1 |[0m javax.net.ssl|DEBUG|10|main|2024-02-20 15:38:51.081 UTC|TrustStoreManager.java:334|Reload the trust store [36prod-backend-1 |[0m javax.net.ssl|DEBUG|10|main|2024-02-20 15:38:51.227 UTC|TrustStoreManager.java:342|Reload trust certs [36prod-backend-1 |[0m javax.net.ssl|DEBUG|10|main|2024-02-20 15:38:51.229 UTC|TrustStoreManager.java:347|Reloaded 3 trust certs [36prod-backend-1 |[0m javax.net.ssl|DEBUG|10|main|2024-02-20 15:38:51.248 UTC|X509TrustManagerImpl.java:82|adding as trusted certificates ( [36prod-backend-1 |[0m "certificate" : { [36prod-backend-1 |[0m "version" : "v3", [36prod-backend-1 |[0m "serial number" : "5C000014C0A1867AC0AFA2E6920000000014C0", [36prod-backend-1 |[0m "signature algorithm": "SHA512withRSA",

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

 

Related content

Copyright Treskon GmbH.