Windows, BitBucket & Let's Encrypt Tutorial

[Jay Hayman]

This is probably better as an article, but here's my experience of setting up a free Let's Encrypt certificate on a Windows server running BitBucket 4 or 5. Lots of moving parts, so take your time. This is based on my set up so your mileage may vary depending on your own setup/environment.

This is using Atlassian's built-in server on port 8443 to function, but this is easily adapted for your own port/proxy/forwarder set up. If you're forwarding SSL via IIS, I highly recommend "win-acme" (used to be called lets-encrypt-win-simple) which can automate renewals; https://github.com/PKISharp/win-acme/releases

Things go wrong, and you're sensible, right? You're a good server admin and you're going to back up any changes first, right? Well done.

A Let's Encrypt certificate needs to be renewed every 3 months - this takes around 10 minutes each time so 40 minutes a year to renew a "free" certificate is pretty good.

Pre-requisites

• Windows 10 (Fall/Autumn Creators v1709 or later), or a box/VM with Linux installed, Ubuntu for example. Just alter the paths below to copy your file between devices. The WSL route is by far the best and I'm using WSL more and more in my daily dev.
• Windows 10 WSL enabled (Windows Subsystem for Linux): https://winaero.com/blog/enable-wsl-windows-10-fall-creators-update/ 
• Install Ubuntu (or your fav version of Linux with OpenSSL installed) from the store: https://www.microsoft.com/store/productId/9NBLGGH4MSV6 - OpenSSL is usually pre-installed, if not, look up apt-get to find it.

Create / Renew Cert 

• Go to: https://www.sslforfree.com 
• Create an account or log in to an existing one.
• Add or renew a certificate in your list. Going to assume you've got an FQDN set up and pointing at your server IP, e.g., bitbucket.myserverdomain.co.uk
• If you're adding a new cert for the first time, you'll need to verify you own the domain (Let's Encrypt uses the domain validation scheme to authenticate you). This usually involves adding a file to the root of the server with the code they supply or adding DNS settings (my preferred method) with the same unique key as a TXT record.
• Once validated, tick box (or click the link) to download all the certificates generated for you. Feel free to do CSR, it's not a requirement for this tutorial.
• Unzip the files into a location you can remember, e.g., "/Downloads/ssl/".

Convert to P12 format

• Create a new file called "bundle.pem", e.g., Right click -> New Text File.
• In this order, paste the contents of the downloaded files into the new .pem file. 

private.key 

certificate.cer 

ca_bundle.cer 

• Open Ubuntu WSL command prompt and CD to the SSL location (e.g. /mnt/c/youraccountfolder/downloads/ssl/. If you're running a Linux VM or box, copy the file to your Linux home folder and alter the following paths as required.
• Run: openssl pkcs12 -export -in bundle.pem -inkey private.key -out bitbucket.p12
•  Copy the "bitbucket.p12" file to your BitBucket server and paste it to "C:\Atlassian\ApplicationData\Bitbucket\shared\config\ssl-keystore", which is the default home directory for BitBucket.

Import into keystore

• If it exists, delete or rename the existing "bitbucket.jks" file from "C:\Atlassian\ApplicationData\Bitbucket\shared\config\ssl-keystore".  I tend to re-create the PKS file every time
• In command prompt, paste - and change the password (!): "%JAVA_HOME%\bin\keytool" -importkeystore -deststorepass yourpassword -destkeystore C:\Atlassian\ApplicationData\Bitbucket\shared\config\ssl-keystore\bitbucket.jks -srckeystore C:\Atlassian\ApplicationData\Bitbucket\shared\config\ssl-keystore\bitbucket.p12 -srcstoretype PKCS12 

Server Config / Properties

The first time you set up SSL, you'll need to alter the v4 server.xml file or in v5 the BitBucket.properties file, both found here: "C:\Atlassian\ApplicationData\Bitbucket\shared".

For version 4:

<Connector
port="8443"
maxHttpHeaderSize="8192"
SSLEnabled="true"
maxThreads="150"
minSpareThreads="25"
maxSpareThreads="75"
enableLookups="false"
disableUploadTimeout="true"
useBodyEncodingForURI="true"
acceptCount="100"
scheme="https"
secure="true"
clientAuth="false"
sslProtocol="TLSv1.2"
keystoreFile="file:///C:/Atlassian/ApplicationData/Bitbucket/shared/config/ssl-keystore/bitbucket.jks"
keystorePass="yourpassword"
/>

For version 5:

server.port=8443
server.secure=true
server.scheme=https
server.ssl.enabled=true
server.ssl.client-auth=want
server.ssl.protocol=TLSv1.2
server.ssl.key-alias=1
server.ssl.key-store=C:/Atlassian/ApplicationData/Bitbucket/shared/config/ssl-keystore/bitbucket.jks
server.ssl.key-store-password=w1llywonka
server.ssl.key-password=w1llywonka

I've made no other changes to these files.

Restart BitBucket Service

Restart the BitBucket server and head off to your domain but instead of ":7990" in the end (if you're running in the default Windows set up of BitBucket), change the port to 8443 (or whatever port you set up in the config file).

Optional: Export for JIRA 

If you're also self-hosting JIRA, you're likely going to want to export the certificate so that you can import it into JIRA's keystore.

• In command prompt: "%JAVA_HOME%\bin\keytool" -export -alias 1 -file C:\Atlassian\ApplicationData\Bitbucket\shared\config\ssl-keystore\bitbucket.cer -keystore C:\Atlassian\ApplicationData\Bitbucket\shared\config\ssl-keystore\bitbucket.jks 
• This creates a new .cer file in the same directory as the .jks file.
• Assuming you have JIRA installed in the same default location as mine, use the path shown. If asked for a password, the default keystore password is usually "changeit". You may need to create a new keystore for JIRA (or this may create it, I can't remember). If you're renewing, and have not deleted the existing JIRA keystore file, increment the "alias" number at the end of the line (you can use a name if you prefer). In command prompt, paste and alter as required: "%JAVA_HOME%\bin\keytool" -importcert -file C:\Atlassian\ApplicationData\Bitbucket\shared\config\ssl-keystore\bitbucket.cer -keystore "C:\Program Files\Atlassian\JIRA\jre\lib\security\cacerts" -alias 1

That's it, so we now have BitBucket running on a quarterly renewable Let's Encrypt certificate with the same cert imported into JIRA to authenticate access to BitBucket from within JIRA. If you want to secure JIRA with SSL, not that I've done that yet, I'm sure you could repeat these steps and adapt them for JIRA's installation paths and config files.

[Silvio Frick]

Thank you. Glad this guide exists. Worked like a breeze!

[Brian Gabrick]

Following this guide got me over the last hurdle in setting up jira and bitbucket Application Links using a LetsEncrypt wildcard cert! 

Thanks!