How to use Mutual TLS for Jenkins and Bitbucket integration?

Bitbucket Post Webhooks supports mutual TLS. In this guide you will find more details on how to set it up.

This guide is for Post Webhooks for the Bitbucket Atlassian Marketplace application.

Mutual TLS, also known as client certificate authentication, adds an extra layer of security to the communication between the app and the webhook endpoint. With mutual TLS, both the client (the app) and the server (the webhook endpoint) authenticate each other using digital certificates.

Enabling mutual TLS ensures that only trusted clients with valid and verified certificates can establish a connection with the webhook endpoint.

Configurations

This functionality is available on all configuration levels:

Global Configurations for Bitbucket admins

Project Level Configurations

Repository Level Configurations

Find our application Post Webhooks on the level that suits your needs best: Global, Project, or Repository.
From the Configurations tab, click
Tick the checkbox Enable Mutual TLS and specify all the necessary parameters.
Complete the rest configuration parameters according to your needs.
After you have specified all the necessary parameters click on the Save button.

Below you can find a short definition of each parameter you have to specify to enable Mutual TLS:

Parameter	Definition
`Path to Key Store`	contains the private key and the associated certificate used for Mutual TLS authentication.
`Path to Trust Store`	contains trusted certificates used to verify the authenticity of other parties during Mutual TLS authentication.
`Key Store Password`	the password required to access the Key Store file.
`Trust Store Password`	password needed to access the Trust Store file.

Mutual TLS for Jenkins integration

Server key store and trust store

Create the directory “server/cert”, then run the next commands

CODE

keytool -genkeypair -keyalg RSA -keysize 2048 -alias server -dname "CN=Hakan,OU=Amsterdam,O=Luminis,C=NL" -ext "SAN:c=DNS:localhost,IP:127.0.0.1" -validity 3650 -keystore server/cert/identity.jks -storepass secret -keypass secret -deststoretype pkcs12
keytool -exportcert -keystore server/cert/identity.jks -storepass secret -alias server -rfc -file server/cert/server.cer
keytool -keystore client/cert/truststore.jks -importcert -file server/cert/server.cer -alias server -storepass secret

Client key store and trust store

Create directory “client/cert”

BASH

keytool -genkeypair -keyalg RSA -keysize 2048 -alias client -dname "CN=Suleyman,OU=Altindag,O=Altindag,C=NL" -validity 3650 -keystore client/cert/identity.jks -storepass secret -keypass secret -deststoretype pkcs12
keytool -exportcert -keystore client/cert/identity.jks -storepass secret -alias client -rfc -file client/cert/client.cer
keytool -keystore server/cert/truststore.jks -importcert -file client/cert/client.cer -alias client -storepass secret

Start Jenkins with certificates

To start Jenkins we use a docker image with the required parameters.

CODE

docker run -it \
    -p 8083:8083 \
    -p 8080:8080 \
    --name jenkins \
    -v server/cert:/cert \
    --env JAVA_OPTS="-Djavax.net.ssl.trustStore=/cert/truststore.jks -Djavax.net.ssl.trustStorePassword=secret" \
    --env JENKINS_OPTS="--httpPort=8080 --httpsPort=8083 --httpsKeyStore=/cert/identity.jks --httpsKeyStorePassword=secret" jenkins:2.60.3

Jenkins accepts connection on HTTP and HTTPS ports.

-Djavax.net.ssl.trustStore=/cert/truststore.jks -Djavax.net.ssl.trustStorePassword=secret replaces default Java trust store

--httpsKeyStore=/cert/identity.jks --httpsKeyStorePassword=secret specifies key store for Jenkins

After the setup of the project is complete, a build can be triggered by REST: JENKINS_URL/job/test/build?token=TOKEN_NAME or /buildWithParameters?token=TOKEN_NAME