Securing Bitbucket Server behind HAProxy using SSL
This page describes how to establish a network topology in which the HAProxy server acts as a reverse proxy for Bitbucket Server. Typically, such a configuration would be used when either when:
- Bitbucket Server is installed in a protected zone 'behind the firewall', and HAProxy provides a gateway through which users outside the firewall can access Bitbucket Server.
- Bitbucket Server needs to be served on protected ports (e.g. ports < 1024 on Linux). Bitbucket Server cannot access these ports directly as it must not be run as a privileged user (e.g root). In this case HAProxy can bind to these ports and forward the requests to Bitbucket Server.
On this page:
The configuration described on this page results in a scenario where:
- External client connections with HAProxy are secured using SSL. Connections between HAProxy and Bitbucket Server are unsecured.
- Bitbucket Server and HAProxy run on the same machine.
- Bitbucket Server is currently available at
http://mycompany.com:7990/. - Bitbucket Server is to be made available at
https://mycompany.com/bitbucket.
Important considerations
- We assume that you already have a running instance of HAProxy.
- SSL certificates must be installed on the server machine.
- Any existing links with other applications will need to be reconfigured using the new URL for Bitbucket Server.
- Securing Git operations between the user's computer and Bitbucket Server is a separate consideration - see Enabling SSH access to Git.
- It is also possible to get Bitbucket Server to directly use SSL without the help of a proxy as documented in Securing Bitbucket Server with Tomcat using SSL.
Note that the Atlassian Support Offering does not cover HAProxy integration, but you can get assistance with HAProxy from the Atlassian community on answers.atlassian.com, or from an Atlassian Expert.
Step 1: Set a context path for Bitbucket Server
Bitbucket Server and HAProxy need to be serving from the same context. Bitbucket Server is currently accessed at http://mycompany.com:7990. It needs to be changed to serve from http://mycompany.com:7990/bitbucket to match context https://mycompany.com/bitbucket.
- Locate the
bitbucket.propertiesfile in the shared directory of your<Bitbucket Server home directory>. Change the context path for Bitbucket Server by adding
server.context-path=/bitbucket- Save the file.
Good to know
- If you use a context path, it is important that the same path is appended to the context path of Bitbucket Server's base URL (Step 2).
- The context path for serving from the root context is
path=""(i.e notpath="/").
Step 2: Change Bitbucket Server's base URL
- Open a browser window and log into Bitbucket Server using an administrator account.
- Go to the Bitbucket Server administration area and click Server settings (under 'Settings'), and change Base URL to match the URL HAProxy will be serving. For this example, use
https://mycompany.com/bitbucket.
Step 3: Configure the Tomcat Connector
Following our example, you need to configure these attributes that tell Tomcat how HAProxy is serving Bitbucket Server so it can generate correct URLs.
Locate the <Bitbucket Server home directory>/shared/bitbucket.properties file, and add the following:
server.secure=true
server.scheme=https
server.proxy-port=443
server.redirect-port=443
server.proxy-name=mycompany.com
What these attributes do
proxyPortis set to 443 to indicate that HAProxy is accepting connections over on the standard HTTPS port 443.
proxyNameandschemeare are set to the values that HAProxy is serving Bitbucket Server over.secureattribute is also set totrueto tell Bitbucket Server that the connection between the client and HAProxy is considered secure.redirectPortis set to 443 so that Tomcat knows how to send a user to a secure location when necessary (this is not really necessary in this example because this connector is alreadysecure).
For more information about configuring the Tomcat Connector, refer to the Apache Tomcat 7.0 HTTP Connector Reference.
Step 4: Configure HAProxy
Merge the example below into your HAProxy configuration (e.g /etc/haproxy/haproxy.cfg). This is a complete HAProxy 1.5.x configuration. Note that HAProxy 1.5.x or greater is required for SSL support. You can just take the bits that fit your needs. The important configuration is in the bitbucket_http_frontend and bitbucket_http_backend.
global
log /dev/log local0
log /dev/log local1 notice
user haproxy
group haproxy
daemon
ssl-default-bind-options no-sslv3
maxconn 1000
defaults
log global
mode http
option httplog
option dontlognull
timeout connect 5000
timeout client 50000
timeout server 50000
# Tells HAProxy to start listening for HTTPS requests. It uses the SSL key
# and certificate found within certAndKey.pem. All requests will be routed
# to the bitbucket_http_backend.
frontend bitbucket_http_frontend
bind *:443 ssl crt /etc/haproxy/certAndKey.pem ciphers HIGH:!aNULL:!MD5
default_backend bitbucket_http_backend
# This is an optional rule that will redirect all requests to https://mycompany.com
# to https://mycompany.com/bitbucket.
redirect location /bitbucket if { path -i / }
# The bitbucket_http_backend simply forwards all requests onto http://mycompany.com:7990/.
# It will only allow 50 concurrent connections to the server at once.
backend bitbucket_http_backend
mode http
option httplog
option forwardfor
option http-server-close
option httpchk
server bitbucket01 mycompany.com:7990 maxconn 50(Optional) Step 4: Redirect SSH connections
HAProxy also has the ability to proxy all Bitbucket Server SSH traffic. See Setting up SSH port forwarding for details.