Using external domain for pages

Motivation

Configuring the Pages for Bitbucket Server to serve via an external domain allows hosting arbitrary Javascript and CSS without the risk of XSS vulnerabilities. When pages are served via another domain, the browser same-origin policy ensures that no Bitbucket session information is available in malicious javascript.

Effects of enabling serving via an external domain

• All pages served are available publicly, since Bitbucket authentication is not available.

• Javascript and CSS sanitization is turned off, since it is not required.

• Attempting to access content at the old URL will result in a redirect to the new location at the external domain.

How to enable serving via external domain

An external domain is enabled by specifying a “Pages Domain” on the global “Pages configuration” page available to administrators:

To turn off the external domain configuration, simply clear the field and save.

Selecting sub-folder to serve

The option is intended to use along with external domain. If it’s configured anonymous users can only access files in the specified folder. This is useful for the cases when no access to the source code is requires but generated documentation needs to be available for everyone.

If external folder is not configured then option is hidden and has no effect on web server

Configuring a reverse proxy

The external domain pages domain must be configured to re-direct to Bitbucket using a reverse proxy. For some background on configuring a reverse proxy: reference 1, reference 2.

Under the hood the plugin checks X-Forwarded-Host header to determine if request made through pages domain.

Apache example configuration:

Here is example of virtual host configuration for the Apache http server:

<VirtualHost *:80>
    ServerName bitbucket-pages.local
     
    ProxyRequests Off
    ProxyVia Off
     
    <Proxy *>
         Require all granted
    </Proxy>
 
    ProxyPass /pages http://localhost:7990/bitbucket/pages
    ProxyPassReverse /pages http://localhost:7990/bitbucket/pages
</VirtualHost>

Nginx example configuration:

worker_processes  1;

events {
    worker_connections 1024;
}

http {
    server {
        listen 8080;
        server_name bitbucket-pages.local;

        location /pages/ {
            proxy_pass http://localhost:7990/bitbucket/pages/;
            proxy_set_header X-Forwarded-Host $host;
        }
    }
}