Page Comparison

Motivation

Configuring the Pages for Bitbucket Server to serve via through an external domain allows hosting you to host arbitrary Javascript and CSS without the risk of XSS vulnerabilities. When pages are served via another domain, the browser browser’s same-origin policy ensures helps to ensure 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 results in a redirect to the new location at the external domain.

...

Enable serving via external domain

...

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

...

.

1. Click the Administration icon ⚙️ > Pages configuration to open the Pages configuration page.

2. In the External Domain > Pages Domain text field, provide your custom domain. This can be any domain other than the Bitbucket domain.

3. Click Save.

4. To turn off the external domain configuration,

...

1. clear the

...

1. Pages Domain field and click Save.

Selecting a sub-folder to serve

...

The Sub-folder to serve option is intended to use along with the external domain. When configured, anonymous users can only access files in the specified folder. This is useful for cases when no access to the source code is required, but generated documentation needs to be available for everyone.

If an external folder is not configured, the option does not affect the web server.

1. Select a repository and click Repository settings > Web Pages to open the Web pages page.

2. Enter the path used as root of web server in the Sub-folder to serve field and click Save. Using this option limits access to the repository through the web server. Only the contents of the specified folder are served as pages.

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, reference2 reference 2.

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

Apache example configuration:

Here is example of virtual Example - Virtual host configuration for the Apache http 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;
        }
    }
}

...