Securing SonarQube Community Build behind a proxy

This page helps you configure SonarQube if you want to run it behind a proxy. This can be done for security concerns or to consolidate multiple disparate applications.

If you deploy SonarQube on Kubernetes, you’ll need an ingress controller. An ingress controller is a specialized load balancer for Kubernetes that acts as a reverse proxy and manages traffic routing to services within the Kubernetes cluster. See Creating an Ingress in Customizing the Helm chart. 

General guidelines

The reverse proxy should be configured to set the following standard headers:

• X-Forwarded-Proto
• X-Forwarded-For

This setting is mandatory if you use HTTPS or SAML authentication for SonarQube.

In the example below, where HTTPS is used from the client to the reverse proxy and HTTP from the reverse proxy to SonarQube, the reverse proxy will set:

• X-Forwarded-Proto to HTTPS
• X-Forwarded-For to <clientIpAddress>

In addition, the reverse proxy may be configured to forward the following custom headers:

• SonarQube-Authentication-Token-Expiration
  This header is added to a web service response when using tokens to authenticate. Forwarding this header is not required for the SonarQube features to work properly.
• Sonar-MD5
  This header is used to verify the integrity of the plugins downloaded by the scanner. You must forward this header to successfully execute analyses that use plugins.

For information about tokens, see Understanding tokens.

Using Nginx proxy

Nginx configuration will vary based on your own application's requirements and the way you intend to expose SonarQube to the outside world. If you need more details about Nginx, see Nginx documentation.

In the following, we assume that you've already installed Nginx, that you are using a Virtual Host for www.somecompany.com and that SonarQube is running and available on http(s)://sonarhost:sonarport/.

At this point, edit the Nginx configuration file:

• Include the code below to expose SonarQube at http://www.somecompany.com/ or https://www.somecompany.com/

# the server directive is Nginx's virtual host directive
server {
  # port to listen on. Can also be set to an IP:PORT
  listen 80;
  # sets the domain[s] that this vhost server requests for
  server_name www.somecompany.com;
  location / {
    proxy_pass http://<sonarhost>:<sonarport>;
  }
}

# the server directive is Nginx's virtual host directive
server { 
 # port to listen on. Can also be set to an IP:PORT 
 listen 443 ssl;
 ssl_certificate <path_to_your_certificate_file>;
 ssl_certificate_key <path_to_your_certificate_key_file>;
 location / {
   proxy_pass <address-of-your-sonarqube-instance-behind-proxy>;
   proxy_set_header Host $host;
   proxy_set_header X-Forwarded-For $remote_addr;
   proxy_set_header X-Forwarded-Proto https;
 }
}

Using Apache proxy

Apache configuration is going to vary based on your own application's requirements and the way you intend to expose SonarQube to the outside world. If you need more details about Apache HTTPd and mod_proxy, see the Apache documentation. 

In the following, we assume that you've already installed Apache 2 with module mod_proxy, that SonarQube is running and available on http://private_sonar_host:sonar_port/, and that you want to configure a Virtual Host for www.public_sonar.com.

At this point, edit the HTTPd configuration file for the www.public_sonar.com virtual host:

• Include the following to expose SonarQube via mod_proxy at http://www.public_sonar.com/

ProxyRequests Off
ProxyPreserveHost On
<VirtualHost *:80>
  ServerName www.public_sonar.com
  ServerAdmin admin@somecompany.com
  ProxyPass / http://private_sonar_host:sonar_port/
  ProxyPassReverse / http://www.public_sonar.com/
  ErrorLog logs/somecompany/sonar/error.log
  CustomLog logs/somecompany/sonar/access.log common
</VirtualHost>

Using F5 proxy

Use an iRule to insert the original client IP address in an X-Forwarded-For HTTP header (see also F5 documentation) as illustrated below.

when HTTP_REQUEST {
    HTTP::header insert X-Forwarded-For [IP::remote_addr]
    HTTP::header insert X-Forwarded-Proto "https"
}

Using IIS on Windows

Using IIS on Windows, you can create a website that acts as a reverse proxy and access your SonarQube instance over SSL.

Prerequisites

<system.webServer>
  <security>
    <requestFiltering>
      <requestLimits maxQueryString="32768"/>
    </requestFiltering>
  </security>
</system.webServer>
<system.web>
    <httpRuntime maxQueryStringLength="32768" maxUrlLength="65536"/>
</system.web>

Step 1: Create an IIS website

1. In the IIS Manager, select Your machine > Sites > Add Website...
2. Under Site name, enter a name for your website.
3. Under Content Directory > Physical path, select a physical path for your website’s folder. Based on the default IIS website, we recommend creating a %SystemDrive%\inetpub\wwwroot_sonarqube folder and using it as a physical path.
4. In Binding, select Type > https.
5. For Host name, enter the hostname you will use to access SonarQube.
6. Under SSL certificate, select an SSL certificate.
7. Click OK.

Step 2: Configure your IIS website as a reverse proxy

Once you’ve created your website using the IIS Manager, you can use the URL Rewrite extension to use that website as a reverse proxy:

1. From the IIS Manager home page, select your website and open URL Rewrite.
2. Click Add Rule(s) to create a new rule.
3. Select Reverse Proxy from the list of templates.
4. Enter the destination server URL. It can be localhost:9000 or a remote server.
5. Click OK to create the rule. The URL Rewrite page now displays a reverse proxy inbound rule.

Step 3: Add the HTTP_X_FORWARDED_PROTO server variable

Using the URL Rewrite module, you can create a server variable to handle the HTTP_X_FORWARDED_PROTO header and pass it to SonarQube. 

From the URL Rewrite page:

1. Click View Server Variables. This opens the Allowed Server Variables page.
2. To add a server variable, click Add..., enter HTTP_X_FORWARDED_PROTO in the field and click OK. The server variable is now displayed on the Allowed Server Variables page.
3. Click Back to Rules to go to the URL Rewrite rules list.
4. Select the reverse proxy inbound rule for your website. Under Inbound Rules, click Edit.
5. Expand the Server variables section of the rule definition.
6. Add the HTTP_X_FORWARDED_PROTO server variable and give it the value https.
7. Apply the changes.

SonarQube can now be accessed over SSL.

Step 4: If SAML authentication is used

For SAML through IIS, you must perform the following additional steps:

1. Make sure the host headers are preserved. This is set at the IIS server level, by executing the following command:

 %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/proxy -preserveHostHeader:true /commit:apphost

You should then see an output that says something like:
Applied configuration changes to section "system.webServer/proxy" for "MACHINE/WEBROOT/APPHOST" at configuration commit path "MACHINE/WEBROOT/APPHOST"

2. Disable the Reverse rewrite host in the response headers as follows:

• At the server level in IIS, go to Application Request Routing > Server proxy settings.
• Uncheck the box Reverse rewrite host in response headers.
• Apply the change.
• Restart IIS.

Step 5: Check that the connection is enabled

With your SonarQube instance and your IIS website running, open the IIS Manager and click the link under Your website > Browse Website > Browse, or enter the website’s URL in a browser. You should see the login or home page of your SonarQube instance.

Step 6: Additional optional configuration

You can configure your SonarQube instance to only accept traffic from your reverse proxy, by setting the sonar.web.host system property to 127.0.0.1.

Another option is to use the Windows Firewall to only accept traffic from localhost.

For information about system properties, see Setting system properties.

Related pages

• Configuring network rules