How to customize your gRPC certificate in Bamboo Data Center

Summary

This guide provides step-by-step instructions for configuring custom gRPC certificates in Bamboo Data Center. It covers preparing certificate files, configuring Bamboo, and handling encrypted private keys to ensure secure and effective integration. By default, Bamboo Data Center uses a self-signed certificate for SSL gRPC communication between nodes in a cluster, listening on port 9090. Security scanners can flag this as insecure because the issuer is not a known Certificate Authority (CA). If a custom certificate is not provided, Bamboo will generate a self-signed certificate when a node starts.

Environment

The solution has been validated in Bamboo Data Center version 10.2.3 but may be applicable to other versions. This only affects Bamboo Data Center running on a Bamboo Cluster.

Solution

Step 1: Prepare Your Certificate and Key

1. Ensure both your certificate and private key are in the PEM format as it is required by Bamboo to properly read and utilize the files.

   • You can follow this external article to validate how to create your certificate.

2. If your certificate and key are separate, combine them into a single .pem file using the following command: cat certificate.pem key.pem > combined.pem

3. This combined file should contain both the certificate and the private key for smooth integration.

4. If your private key is encrypted, have the passphrase ready for later configuration steps.

5. Transfer the combined .pem file (e.g., combined.pem) to the $BAMBOO_HOME/shared/ssl/ directory. Bamboo looks for SSL certificates in this location.

Step 2: Configure Bamboo

1. If your file is not named custom_ca.pem, update Bamboo's configuration to recognize your custom filename:

   • -Dbamboo.grpc.authentication.root.ca.filename=<your_filename.pem>

2. Specify the passphrase and cipher method if using an encrypted private key:

   • -Dbamboo.grpc.authentication.root.ca.key.passphrase=<base64_encoded_passphrase> -Dbamboo.grpc.authentication.root.ca.cipher=<cipher_class>

3. If no cipher is defined, Bamboo assumes the passphrase is encoded using com.atlassian.secrets.store.base64.Base64SecretStore.

4. Ensure your passphrase is Base64-encoded, e.g., "admin" becomes "YWRtaW4=".

5. Encrypted passphrase handling: Bamboo uses the following methods of encryption, and if no cipher is referred, Bamboo will use com.atlassian.secrets.store.base64.Base64SecretStore as default. Please refer to Encrypt Methods Available.

   1 2 3 4 com.atlassian.secrets.store.base64.Base64SecretStore (Default) com.atlassian.secrets.store.algorithm.AesOnlyAlgorithmSecretStore com.atlassian.secrets.store.aws.AwsSecretsManagerStore com.atlassian.secrets.store.vault.VaultSecretStore

6. Your system properties file, <bamboo-install>/bin/setenv.sh, should look like the following

   1 2 JVM_SUPPORT_RECOMMENDED_ARGS="${JVM_SUPPORT_RECOMMENDED_ARGS} -Dbamboo.grpc.authentication.root.ca.filename=<combined-cert-and-key>.pem" JVM_SUPPORT_RECOMMENDED_ARGS="${JVM_SUPPORT_RECOMMENDED_ARGS} -Dbamboo.grpc.authentication.root.ca.key.passphrase=<encrypted-password>"

Step 3: Restart Bamboo

1. Restart all Bamboo server instances to apply the changes. This step is crucial for ensuring that the new configuration takes effect across your environment.

2. Use one of the following based on your OS

   1. Linux = setenv.sh

   2. Windows = setenv.bat.

3. While the nodes are online you can check by running the openssl command to validate the certificate that's been reflected.

   • openssl s_client -connect localhost:9090 -showcerts

4. The result may show the default certificate Server certificate subject=CN=<your-CN> issuer=CN=<your-cert-name>

If running a Bamboo Data Center cluster, repeat these steps on all nodes to ensure consistent configuration across the cluster.