Summary

As an additional step to Securing your Remote Agents, you can optionally make use of a custom SSL certificate on the Bamboo ActiveMQ JMS service. 

This guide will walk you through the necessary steps to achieve it.

Solution

Request your SSL certificates

1. Have your SSL certificate files and private keys ready. This article will not cover how to request the certificates from your CA
2. The examples will use a PEM format keypair as a source and will generate JKS format as an output
3. You will need to have certificates and private keys for your Bamboo Server and for any Remote Agents

Create a Java Keystore that will be used exclusively by the Bamboo Server

1. Create a JKS Keystore file from a PEM keypair. Assign "bamboo" as the password to both Keystore and the private key

   This Keystore file can be shared with the one used by Tomcat

   $ openssl pkcs12 -export -in certificate.cer -inkey certificate.key -name bambooserver -out bambooserver.p12 -password pass:bamboo
   $ keytool -importkeystore -deststorepass bamboo -srcstorepass bamboo -destkeystore bambooserver.jks -srckeystore bambooserver.p12 -srcstoretype PKCS12

   In the commands above, make sure to replace:

   • certificate.cer with the certificate file name
   • certificate.key with the private key file name
2. Copy the "bambooserver.jks" file to the <bamboo-install>/conf directory
3. Copy your Java truststore cacerts file to the <bamboo-install>/conf directory. It is usually found on your JAVA_HOME/jre/lib/security (JDK8) or JAVA_HOME/lib/security (JDK11 and later)

4. Add the following entries to your Bamboo system properties, usually on <bamboo-install>/bin/setenv.sh/.bat (for Windows Service or Docker, please check the article):

   -Dbamboo.manage.jms.ssl=false \
   -Djavax.net.ssl.trustStore=<bamboo-install>/conf/cacerts \
   -Djavax.net.ssl.keyStore=<bamboo-install>/conf/bambooserver.jks \
   -Djavax.net.ssl.keyStoreAlias=bambooserver

5. Add the following entry to your <bamboo-install>/conf/catalina.properties (so no passwords are exposed on the OS process list)

   # Extra bamboo init properties
   javax.net.ssl.keyStorePassword=bamboo

6. Optional: import your Remote Agent certificates into your Bamboo Server custom truststore.

   The truststore still uses the default 'changeit' password. You can modify it and assign a custom java.net.ssl.trustStorePassword to the Bamboo system properties.

   This step is only necessary if your Remote Agent certificates Root CA or Intermediate CA are not already trusted by your Bamboo Server truststore. i.e. self-signed certificates.

   You can import the .pem file or the certificate (.cer) itself. E.g., agent1.pem or agent1.cer.

   $ keytool -import -alias agent1 -storepass changeit -keystore <bamboo-install>/conf/cacerts -v -file agent1.cer
   $ keytool -import -alias agent2 -storepass changeit -keystore <bamboo-install>/conf/cacerts -v -file agent2.pem
   $ keytool -import -alias agent3 -storepass changeit -keystore <bamboo-install>/conf/cacerts -v -file agent3.cer
   $ keytool -import -alias agent4 -storepass changeit -keystore <bamboo-install>/conf/cacerts -v -file agent4.pem
   (...)

7. Restart Bamboo

Configure your Remote Agent to use a custom client certificate and to trust the Bamboo Server

1. Create a JKS Keystore file for your remote agent from a PEM keypair. Assign "bamboo" as the password to both the Keystore and the private key. 

   You can repeat the same steps from the section above, "Create a Java Keystore that will be used exclusively by the Bamboo Server", replacing the Bamboo Server certificate and key with the Remote Agent's one.

2. Copy the resulting JKS Keystore (e.g., "agent.jks") file to the <bamboo-agent-home>/conf directory
3. Copy your Java truststore cacerts file to <bamboo-agent-home>/conf. It is usually found on your JAVA_HOME/jre/lib/security (JDK8) or JAVA_HOME/lib/security (JDK11 and later)

4. Add the following entries to <bamboo-agent-home>/conf/wrapper.conf:

   wrapper.java.additional.4=-Djavax.net.ssl.keyStoreAlias=agent1
   wrapper.java.additional.5=-Djavax.net.ssl.keyStorePassword=bamboo
   wrapper.java.additional.6=-Djavax.net.ssl.keyStore=<bamboo-agent-home>/conf/agent.jks
   wrapper.java.additional.7=-Djavax.net.ssl.trustStore=<bamboo-agent-home>/conf/cacerts

   Make sure to point to the JKS file you've just created and copied to the /conf directory. In the example above, it's called "agent.jks".

5. Optional: import your Remote Agent certificates into your Bamboo Server custom truststore

   This step is only necessary if your Bamboo Server certificate Root CA or Intermediate CA is not trusted by your Remote Agent truststore. I.e. self-signed certificates.

   You can import the .pem file or the certificate (.cer) itself. E.g., agent1.pem or agent1.cer.

   $ keytool -import -alias bambooserver -storepass changeit -keystore <bamboo-agent-home>/conf/cacerts -v -file bambooserver.cer

6. If that is the first time you are installing the Remote Agent, make sure to create the jmsclient.ts truststore file containing the Bamboo Server SSL certificate:

   $ keytool -printcert -sslserver <bamboo_hostname>:443 -rfc > tempfile
   $ keytool -importcert -alias broker -storepass bamboo -storetype JKS -file tempfile -keystore <bamboo-agent-home>/configuration/jmsclient.ts

7. Restart the Remote Agent