Securing behind a proxy

It is recommended to run SonarQube behind a proxy if it should be accessible from outside.

For most production instances, traffic encryption (and therefore HTTPS) is required. As SonarQube only supports plain HTTP for inbound traffic, a reverse proxy is necessary to terminate SSL/TLS encryption before SonarQube.

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 to make SonarQube Server service accessible from outside.

General guidelines

For security reasons, we recommend only giving external access to the main port.

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, 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 Managing your 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/

WITH HTTP

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

WITH HTTPS

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

You may need to increase the max URL length since SonarQube requests can have URLs longer than 2048.

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 [email protected]
  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 HAproxy

The example below shows the configuration of an HAproxy for a Data Center Edition (load balancer and reverse proxy at the same time).

frontend http-in
    bind *:80
    bind *:443 ssl crt /etc/ssl/private/<server_certificate>
    http-request redirect scheme https unless { ssl_fc }
    default_backend sonarqube_server
backend sonarqube_server
    balance roundrobin
    http-request set-header X-Forwarded-Proto https
    option httpchk GET /api/system/status
    http-check expect rstring UP|DB_MIGRATION_NEEDED|DB_MIGRATION_RUNNING
    default-server check maxconn 200
    server node1 <server_endpoint_1>
    server node2 <server_endpoint_2> 

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

ISS enabled

Internet Information Services (IIS) must be enabled with the following extensions:

• The Url Rewrite extension for IIS

• The Application Based Routing extension for IIS

To make sure the extensions are enabled, restart your IIS Manager after you install them.

In the example used below, IIS is enabled on the same machine as the SonarQube instance.

SSL certificate

You must provide a self-signed SSL certificate, or a real one and import it (see TLS certificates on client side) to the Java truststore of the machine running the scanner.

Microsoft limit on HTTP requests

cBecause of possibly long query strings with SonarQube web API, you must increase the Microsoft limit on HTTP requests by setting the following attributes to much larger values:

• maxQueryString (default is 2048)

• maxQueryStringLength

If you don’t, request filtering will be applied which can yield HTTP 404 errors. For example, this may cause projects to not appear on the projects dashboard.

To adjust these values:

1. Enter the Request Filtering module for your IIS site.

2. Right-click and select Edit Feature Settings…

3. Increase the Maximum query string value to a much larger value.

Alternatively, you can add the following to your Microsoft’s web.config file for the associated IIS site (adjust maxQueryString and maxQueryStringLength as needed):

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

See Request Limits <requestLimits> | Microsoft Learn for more information.

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"

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

   1. At the server level in IIS, go to Application Request Routing > Server proxy settings.

   2. Uncheck the box Reverse rewrite host in response headers.

   3. Apply the change.

   4. 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 setup, see Configuration methods.

Related pages

• Network rules (Developer and Enterprise editions)

• Network rules (Data Center Edition)