Configuring Proxies and Load Balancers for Tableau Server

In most enterprises, Tableau Server needs to communicate with the internet. Tableau Server was designed to operate inside a protected internal network. Do not set up Tableau Server directly on the internet or in a DMZ. Instead, communications between your network and the internet should be mediated using proxy servers. Forward proxy servers mediate traffic from inside the network to targets on the internet. Reverse proxy servers and load balancers mediate traffic from the internet to targets inside the network.

Who should read this article?

This article is for IT professionals who are experienced with general networking, load balancing and gateway proxy solutions. The article describes how and when Tableau requires internet access and describes how to configure your network and Tableau to use proxy servers and load balancers for access to and from the internet. There are many third-party solutions available, so some of the content in the article is necessarily generic.

Before you configure a proxy server, see Communicating with the Internet.

Configure a forward proxy server

To enable communication from Tableau Server to the internet, deploy Tableau Server behind a forward proxy server. When Tableau Server needs access to the internet, it doesn't send the request directly to the internet. Instead, it sends the request to the forward proxy, which in turn forwards the request. Forward proxies help administrators manage traffic out to the internet for tasks such as load balancing, blocking access to sites, etc.

If you use a forward proxy, you must configure the computers that run Tableau Server inside the network to send traffic to the forward proxy. Tableau Server doesn't support pass-through or manual proxy authentication.

If you are running OpenID authentication with a forward proxy solution, additional configurations are required. See Configure Tableau Server for OpenID Connect.

Configuring Tableau Server on Linux to work with a forward proxy

We recommend configuring Tableau Server to work with your forward proxy solution as part of the installation process. Specifically, configure Tableau Server when you run ./initialize-tsm as described in Install and Initialise TSM, or as part of Automated Installation of Tableau Server.

The procedure below describes how to create a forward proxy configuration file for Tableau Server on Linux.

The configuration file is stored in the following directory:

~<unprivileged_user>/.config/systemd/tableau_server.conf.d

By default, Tableau Server creates the unprivileged user, tableau. Therefore, the default path to the configuration directory is:

~tableau/.config/systemd/tableau_server.conf.d

The proxy configuration file name in this topic and in the configuration file below is referred to as 20-proxy.conf. You can name this file according to your own convention, but it must use the .conf extension. systemd will process files stored in the tableau_server.conf.d directory in lexical order according to file name.

Run the tsm stop command.
Start a session as the unprivileged user. By default, tableau, is the unprivileged user created by Tableau Server during installation. Run the following command:
sudo su -l tableau
Create or open the 20-proxy.conf file in the tableau_server.conf.d directory. If you configured forward proxy during setup, then the 20-proxy.conf file has already been created.
- Create the file. Run the following command:
  touch ~tableau/.config/systemd/tableau_server.conf.d/20-proxy.conf
- Open the 20-proxy.conf file in a text editor.
Copy the Proxy configuration file contents into the file. If you are editing an existing file, take care not to delete the configuration. The Proxy configuration file contents include instructions on how to set forward proxy configurations. After you have edited and saved the file go to Step 5.

Proxy configuration file contents


# Always edit this file on Tableau Server as the unprivileged user. By default, tableau, is the unprivileged user created by Tableau Server during installation.
# Set environment variables http_proxy and https_proxy to point to your proxy host.
# For example, to set the proxy to example-host for ports 80 and 443, run the following commands:
#
http_proxy=http://example-host:80/
https_proxy=http://example-host:443/
#
# Take care to use 'http' when you specify the URL for the https_proxy environmental variable.  
# Do not specify the 'https' protocol for the value of  the https_proxy environmental variable.
#                   
# To bypass the proxy server, specify exceptions in the no_proxy variable. Use this variable if your proxy server does not route internal addresses. 
# You must also add exceptions to this proxy configuration to guarantee that all communications within a local Tableau Server cluster (if you have one now or will have one later) do not route to the proxy server. 
# Enter both the host name and the IP address for each computer. Additionally, include the cannonical host name (localhost) and IP address (127.0.0.1) for the local computer.
# For example, to specify exceptions for a three-node cluster:
#
no_proxy="localhost,127.0.0.1,hostname1,hostname2,hostname3,IP1,IP2,IP3"
#									
# Where "hostname1" is the actual hostname of node 1, and "IP1" is the actual IP address of node 1, etc.

Exit the Tableau shell. Run the following command:
exit
Restart the TSM business services. Run the following script commands:
sudo /opt/tableau/tableau_server/packages/scripts.<version>/stop-administrative-services
sudo /opt/tableau/tableau_server/packages/scripts.<version>/start-administrative-services
Restart TSM.
tsm restart

Server crash reporter

If your organisation uses a proxy server to connect to the Internet then you must configure Tableau Server's crash reporter to use the proxy. Even if you have already configured Tableau Server to use a proxy, you must also configure server crash reporter separately. To configure proxy for server crash reporter, see Configure Server Crash Reporter.

How a reverse proxy and a load balancer works with Tableau Server

Reverse proxies and load balancers are servers that receive requests from external (internet) clients and forward them to Tableau Server. These solutions make Tableau Server available to the internet without having to expose the individual IP address of that particular Tableau Server to the internet. They may also act as authentication and pass-through devices so that no data is stored where people outside the company can get to it. This requirement can be important for organisations that are subject to various privacy regulations such as PCI, HIPAA or SOX.

The following diagram illustrates the communication path when a client makes a request to Tableau Server that is configured to work with a reverse proxy and/or load balancer (LB).

An external client initiates a connection to Tableau Server. The client uses the public URL that's been configured for the reverse proxy server/LB, such as https://tableau.example.com. (The client doesn't know that it's accessing a reverse proxy/LB.)
The reverse proxy maps that request in turn to a request to Tableau Server. In some scenarios, the reverse proxy may be configured to authenticate the client (using SSL/TLS) as a precondition to passing the request to Tableau Server.
Tableau Server gets the request and sends its response to the reverse proxy/LB.
The reverse proxy/LB sends the content back to the client. As far as the client is concerned, it just had an interaction with Tableau Server and has no way to know that the communication passed through intermediary server(s).

TLS/SSL

Depending on your gateway scenario, you should consider configuring your reverse proxy and load balancing servers to use TLS/SSL for any traffic that's external to your network. This helps to ensure privacy, content integrity and authentication. Unless you've deployed other security measures to protect traffic between your internet gateway and Tableau Server, we also recommend configuring SSL between the gateway proxy and Tableau Server. You can use internal or self-signed certificates to encrypt traffic between Tableau Servers and other internal computers.

Mobile access

Tableau Server adds an X-header to all HTTP responses for Tableau Mobile sessions. By default, most proxy solutions will preserve X-headers. If your gateway solution does not preserve X-headers, then you will need to configure your proxy server and load balancer to preserve the following header to all HTTP responses for Mobile client sessions: X-Tableau: Tableau Server.

If you have configured authentication at the gateway, then your proxy server/LB must respond to Tableau Mobile HTTP requests with an HTTP 302 response. The 302 must include a redirect to the identity provider login page. To view a diagram that describes the 302 authentication sequence, see Tableau Mobile Authentication Sequence(Link opens in a new window) in the Tableau Community.

Reverse proxy, load balancer and user authentication

Tableau Server will always authenticate users. This means that even if you are authenticating inbound connections at the gateway for your organisation, Tableau Server will still authenticate the user.

However, not all clients will support user authentication with a gateway solution:

For supported web browsers, you can use SAML, OpenID Connect, Kerberos, Trusted Tickets or manual authentication with a reverse proxy/LB.
Tableau Mobile supports SAML or manual authentication with a reverse proxy/LB. The iOS version of Tableau Mobile additionally supports Kerberos with a reverse proxy/LB. The same recommendation above applies.
Tableau Prep does not support authentication with a reverse proxy or load balancer. For remote access, use a VPN solution or configure your gateway services to route traffic from Tableau Prep directly to Tableau Server for authentication.
Tableau Desktop supports authentication with a reverse proxy provided that an authentication module is performing preauthentication on the reverse proxy before traffic is routed to Tableau Server for final authentication. For more information, see Part 5 - Configuring Web Tier(Link opens in a new window) of the Tableau Server Enterprise Deployment Guide and Configure Authentication Module with Independent Gateway.

If your organisation is authenticating with Active Directory:

Tableau Server must be configured for reverse proxy before configuring Tableau Server for Kerberos. For more information, see Configure Kerberos.

Configure Tableau Server to work with a reverse proxy server and/or load balancer

Before you configure Tableau Server, you'll need to collect the following information about the proxy server configuration. To configure Tableau Server, you use the tsm configuration set command. The information you need to collect corresponds to options you'll need when you run tsm.

Most of the following tsm options are also used to configure Tableau Server deployments that operate behind a load balancer. For more information, see Add a Load Balancer.

Item	Description	Corresponding `tsm configuration set` option
IP address or `CNAME`	You can either enter an IP address or a CNAME for this option. The public IP address or addresses of the proxy and load balancer servers. The IP address must be in IPv4 format, such as `203.0.113.0`, and it must be a static IP. If you are unable to provide a static IP, or if you are using cloud proxies or external load balancers, you can specify the CNAME (Canonical Name) DNS value that clients will use to connect to Tableau Server. This CNAME value must be configured on your reverse proxy solution to communicate with Tableau Server.	`gateway.trusted`
FQDN	The fully qualified domain name that people use to reach Tableau Server, such as `tableau.example.com`. Tableau Server doesn't support context switching for this option. For example, the following URL is not supported: `example.com/tableau`.	`gateway.public.host`
Non-FQDN	Any subdomain names for the proxy or LB servers. In the example of `tableau.example.com`, the subdomain name is `tableau`.	`gateway.trusted_hosts`
Aliases	Any public alternative names for the proxy or LB servers. In most cases, aliases are designated using CNAME values. An example would be a proxy server `bigbox.example.com` and CNAME entries of `ftp.example.com` and `www.example.com`.	`gateway.trusted_hosts`
Ports	Port numbers for traffic from the client to the reverse proxy server.	`gateway.public.port`

If you are using a distributed installation of Tableau Server, then run the following tsm commands on the initial node in your cluster.

Enter the following command to set the FQDN that clients will use to reach Tableau Server through the proxy and/or LB servers, where name is the FQDN:
tsm configuration set -k gateway.public.host -v 'name'
For example, if Tableau Server is reached by entering https://tableau.example.com in the browser, enter this command:
tsm configuration set -k gateway.public.host -v 'tableau.example.com'
Enter the following command to set the address or the CNAME of the proxy and or LB servers, where server_address is the IPv4 address or CNAME value:
tsm configuration set -k gateway.trusted -v 'server_ip_address'
If your organisation uses multiple proxy servers and/or LB servers, enter multiple IPv4 addresses, separating them with commas. IP ranges are not supported. To improve start up and initialisation of Tableau Server, minimise the number of entries for gateway.trusted.
Enter the following command to specify alternative names for the proxy/LB servers, such as their fully qualified domain names, any not fully qualified domain names and any aliases. If there's more than one name, separate the names with a comma.
tsm configuration set -k gateway.trusted_hosts -v 'name1, name2, name3'
For example:
tsm configuration set -k gateway.trusted_hosts -v 'proxy1.example.com, proxy1, ftp.example.com, www.example.com'
If the proxy server is using SSL to communicate with the internet, run the following command, which tells Tableau that the reverse proxy server is using port 443 instead of port 80:
tsm configuration set -k gateway.public.port -v 443
Note: If the proxy server is using SSL to communicate with Tableau Server, SSL must be configured and enabled on Tableau Server.
Enter the following command to commit the configuration change:
tsm pending-changes apply
If the pending changes require a server restart, the pending-changes apply command will display a prompt to let you know a restart will occur. This prompt displays even if the server is stopped, but in that case, there is no restart. You can suppress the prompt using the --ignore-prompt option, but this does not change the restart behaviour. If the changes do not require a restart, the changes are applied without a prompt. For more information, see tsm pending-changes apply.

Configure the reverse proxy or load balancing server to work with Tableau Server

When a client accesses Tableau Server through a reverse proxy or load balancer, specific message headers have to be preserved (or added). Specifically, all servers in the message chain must be represented in the gateway.trusted and gateway.trusted_hosts settings.

The following graphic shows example headers for a single-hop message chain, where the proxy server is communicating directly with Tableau Server:

The following graphic shows example headers for a multiple-hop message chain, where the message traverses two proxy servers before connecting to Tableau Server:

The following table describes what these headers are and how they relate to the configuration settings on Tableau Server:

Headers	Description	Related Tableau Server settings
`REMOTE_ADDR` and `X-FORWARDED-FOR` (`XFF`)	Tableau Server needs these headers to determine the IP address of origin for requests. `X-FORWARDED-FOR` header must present IP address chain to Tableau Server in the order the connections have occurred.	The IP address that you set in`gateway.trusted` must match the IP presented in `REMOTE_ADDR`. if you sent multiple addresses in`gateway.trusted`, one of them must match the IP presented in `REMOTE_ADDR`.
`HOST` and `X-FORWARDED HOST` (`XFH`)	These headers are used to generate absolute links to Tableau Server when it replies to the client. `X-FORWARDED-HOST` header must present host names to Tableau Server in the order the connections have occurred.	The host names that are presented in `X-FORWARDED-HOST` header must be included in the host names that you specify in `gateway.trusted_hosts`.
`X-FORWARDED-PROTO` (`XFP`)	This header is required if SSL is enabled for traffic from the client to the proxy, but not for traffic from the proxy to Tableau Server. The `X-FORWARDED-PROTO` headers are important for scenarios where HTTP or HTTPS is not maintained along each hop of the message route. For example, if the reverse proxy requires SSL for outside requests, but traffic between the reverse proxy and Tableau Server is not configured to use SSL, `X-FORWARDED-PROTO` headers are required. Some proxy solutions add the `X-FORWARDED-PROTO` headers automatically, while others do not. Finally, depending on your proxy solution, you might have to configure port forwarding to translate the request from port 443 to port 80. Related KB article: "Unable to Sign In" and "Invalid username or password" Error With SAML After Upgrading(Link opens in a new window).	Port configuration on reverse proxy (inbound connections from client and outbound connections to Tableau Server) must be specified in the corresponding parameter: `gateway.public.port`, which is the port clients use to connect to the proxy. If the proxy server is using SSL to communicate with Tableau Server, SSL must be configured and enabled on Tableau Server.

Validate reverse proxy and load balancer configuration

To validate your gateway-to-Tableau Server configuration, publish workbooks and datasources using Tableau Server web authoring or Tableau Desktop. If you are connecting with a web browser to Tableau Server from the internet, verify that you are using a recommended browser(Link opens in a new window). Publish and view workbooks that use existing datasources as well as a datasource that you've published . Use the links below to familiarise yourself with connecting with Tableau Server as an end-user.

Task	Documentation
Overview of web authoring.	Use Tableau on the Web(Link opens in a new window)
Log in to Tableau Server from Tableau Desktop or a web browser.	Sign in to Tableau Server or Online(Link opens in a new window)
Publish a workbook to Tableau Server.	Publish a Workbook(Link opens in a new window)
Publish a data source.	Publish a Data Source(Link opens in a new window)
Open workbook from Tableau Server.	Opening Workbooks from the Server(Link opens in a new window)
Log out Server (with Desktop).	Sign in to Tableau Server or Online(Link opens in a new window)
Download workbook from a web browser.	Download Workbooks(Link opens in a new window)
Check to make sure tabcmd (from a non-server client) works.	tabcmd

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau Server on Linux Help