Skip to main content
Skip table of contents

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.

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

  1. Find our application Post Webhooks on the level that suits your needs best: Global, Project, or Repository.

  2. Click on the Add webhook button in the left corner and create a new configuration.

  3. Tick the checkbox Enable Mutual TLS and specify all the necessary parameters.

  4. Complete the rest configuration parameters according to your needs.

  5. 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

Bitbucket Post Webhook plugin

To check if the URL can be handled Test connection button can be used.

In all cases, authentication is required.

  • HTTPS URL without additional parameters:

  • HTTPS URL with Skip SSL Certificate Validation:

  • HTTPS URL with Enable Mutual TLS:

Key Store and Trust Store files should be on the same box where Bitbucket is running:

  • Path to Key Store - client/cert/identity.jks

  • Path to Trust Store - client/cert/truststore.jks

  • Key Store and Trust Store Passwords - secret.

Results can be checked on the Jenkins platform:

To learn more follow the links:

https://hub.docker.com/_/jenkins/

https://support.cloudbees.com/hc/en-us/articles/203821254-How-to-install-a-new-SSL-certificate

https://stackoverflow.com/questions/40126736/enable-https-in-jenkins

https://devopscube.com/configure-ssl-jenkins/

Updated:

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.