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

Reminder: When Pages Domain is enabled all repository content is available to anonymous users

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 available since version 3.7.0

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.

The folder becomes a root folder for the web server and configured folder name shouldn’t be a part of external urls

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>

XML

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;
        }
    }
}

CODE