Tableau Server Enterprise Deployment Guide

The web tier of the reference architecture should include the following components:

• A web-facing application load balancer that accepts HTTPS requests from Tableau clients and communicates with the reverse proxy servers.
• Reverse proxy: 
  • We recommend deploying the Tableau Server Independent Gateway.
  • We recommend a minimum of two proxy servers for redundancy and to handle client load.
  • Receives HTTPS traffic from load balancer.
  • Supports sticky session to Tableau host.
  • Configure proxy for round robin load balancing to each Tableau Server running the Gateway process.
  • Handles authentication requests from external IdP.
• Forward proxy: Tableau Server requires access to the internet for licensing and map functionality. You must configure forward proxy safelists for Tableau service URLs. See Communicating with the Internet (Linux(Link opens in a new window)).
• All client-related traffic may be encrypted over HTTPS:
  • Client to application load balancer
  • Application load balancer to reverse proxy servers
  • Proxy server to Tableau Server
  • Authentication handler running on reverse proxy to IdP
  • Tableau Server to IdP

Tableau Server Independent Gateway

Tableau Server version 2022.1 introduced the Tableau Server Independent Gateway. The Independent Gateway is a standalone instance of the Tableau Gateway process that serves as a Tableau-aware reverse proxy.

Independent Gateway supports simple round-robin load balancing to the backend Tableau Servers. However, Independent Gateway is not intended to serve as the enterprise application load balancer. We recommend running Independent Gateway behind an enterprise-class application load balancer.

The Independent Gateway requires an Advanced Management licence.

Authentication and authorisation

The default reference architecture specifies installing Tableau Server with local authentication configured. In this model, clients must connect to Tableau Server to be authenticated by the native Tableau Server local authentication process. We do not recommend using this authentication method in the reference architecture because the scenario requires that unauthenticated clients communicate into the application tier, which is a security risk.

Instead, we recommend configuring an enterprise grade external identity provider coupled with an AuthN module to pre-authenticate all traffic to the application tier. When configured with an external IdP, the native Tableau Server local authentication process is not used. Tableau Server authorises access to resources in the deployment after the IdP has authenticated the users.

Pre-authentication with an AuthN module

In the example documented in this Guide, SAML SSO is configured, but the pre-authentication process can be configured with most external identity providers and an AuthN module.

In the reference architecture the reverse proxy is configured to create a client authentication session with the IdP before proxying those requests to Tableau Server. We refer to this process as the pre-auth phase. The reverse proxy will only redirect authenticated client sessions to Tableau Server. Tableau Server will then create a session, verify authentication of the session with the IdP and then return the client request.

The following diagram shows the step-by-step detail of the pre-auth and authentication process with an AuthN module configured. The reverse proxy may be a generic third-party solution or the Tableau Server Independent Gateway:

Configuration overview

This is an overview of the process to configure the web tier. Verify connectivity after each step:

1. Configure two reverse proxies to provide HTTP access to Tableau Server.
2. Configure load balancing logic with sticky sessions on proxy servers to connect to each Tableau Server instance running the Gateway process.
3. Configure application load balancing with sticky sessions at the internet gateway to forward requests to the reverse proxy servers.
4. Configure authentication with an external IdP. You can configure SSO or SAML by installing an authentication handler on the reverse proxy servers. The AuthN module manages the authentication handshake between the external IdP and your Tableau deployment. Tableau will also act as an IdP service provider and authenticate users with the IdP.
5. To authenticate with Tableau Desktop in this deployment, your clients must be running Tableau Desktop 2021.2.1 or later.

Example web tier configuration with Tableau Server Independent Gateway

The remainder of this topic provides an end-to-end procedure that describes how to implement web tier in the example AWS reference architecture using Tableau Server Independent Gateway. For an example configuration using Apache as reverse proxy, see Appendix - Web Tier with Apache Example Deployment.

The example configuration is composed of the following components:

• AWS application load balancer
• Tableau Server Independent Gateway
• Mellon authentication module
• Okta IdP
• SAML authentication

Note: The example web tier configuration presented in this section includes detailed procedures for deploying third-party software and services. We've made a best effort to verify and document the procedures to enable the web tier scenario. However, the third-party software may change or your scenario may differ from the reference architecture described here. Please refer to third-party documentation for authoritative configuration details and support.

The Linux examples throughout this section show commands for RHEL-like distributions. Specifically, the commands here have been developed with the Amazon Linux 2 distribution. If you are running the Ubuntu distribution, edit the commands accordingly.

Deploying the web tier in this example follows a stepwise configuration and verification procedure. The core web tier configuration consists of the following steps to enable HTTP between Tableau and the internet. Independent Gateway is run and configured for reverse proxy/load balancing behind the AWS application load balancer:

1. Prepare environment
2. Install Independent Gateway
3. Configure Independent Gateway Server
4. Configure AWS application load balancer

After the web tier is set up and connectivity with Tableau is verified, configure authentication with an external provider.

Prepare Environment

Complete the following tasks before you deploy Independent Gateway.

1. AWS Security group changes. Configure the Public security group to allow inbound Independent Gateway housekeeping traffic (TCP 21319) from the Private security group.

2. Install version 22.1.1 (or later) on four-node Tableau Server cluster as documented at Part 4 - Installing and Configuring Tableau Server.

3. Configure the two proxy EC2 instances in the Public security group as documented at Configure host computers.

Install Independent Gateway

Tableau Server Independent Gateway requires an Advanced Management licence.

Deploying Tableau Server Independent Gateway consists of installing and running the .rpm package and then configuring initial state. The procedure included with this Guide provides prescriptive guidance for deploying into the reference architecture.

If your deployment differs from the reference architecture, consult the core Tableau Server documentation, Install Tableau Server with Independent Gateway (Linux(Link opens in a new window)).

Important: Configuring Independent Gateway can be an error-prone process. It is very difficult to troubleshoot configuration issues across two instances of Independent Gateway servers. For this reason, we recommend configuring one Independent Gateway server at a time. After you configure the first server and verify functionality, you should then configure the second Independent Gateway server.

Although you will configure each Independent Gateway server separately, run this installation procedure on both EC2 instances that you installed into the Public security group: 

1. Run update to apply latest fixes to the Linux OS:

   sudo yum update

2. If Apache is installed, remove it:

    sudo yum remove httpd

3. Copy the version 2022.1.1 (or later) Independent Gateway installation package from Tableau Downloads page(Link opens in a new window) to the host computer that will be running Tableau Server.

   For example, on a computer running Linux RHEL-like operating system, run

   wget https://downloads.tableau.com/esdalt/2022<version>/tableau-server-tsig-<version>.x86_64.rpm

4. Run the installation program. For example, on a Linux RHEL-like operating system, run:

   sudo yum install <tableau-tsig-version>.x86_64.rpm

5. Change to the /opt/tableau/tableau_tsig/packages/scripts.<version_code>/ directory and run the initialize-tsig script located there. In addition to the --accepteula flag, you must include the IP range of the subnets where the Tableau Server deployment is running. Use the -c option to specify the IP range. The example below shows the command with the example AWS subnets specified:

   sudo ./initialize-tsig --accepteula -c "ip 10.0.30.0/24 10.0.31.0/24"

6. After initialisation is complete, open the tsighk-auth.conf file and copy the authentication secret in the file. You will need to submit this code for each Independent Gateway instance as part of the backend Tableau Server configuration:

   sudo less /var/opt/tableau/tableau_tsig/config/tsighk-auth.conf

7. After you have run the previous steps on both instances of the Independent Gateway, prepare the tsig.json configuration file. The configuration file consists of an "independentGateways" array. The array holds configuration objects that each define connection details for an Independent Gateway instance.

   Copy the following the JSON and customise it according to your deployment environment. The example here shows a file for a sample AWS reference architecture.

   The example JSON file below only includes connection information for one Independent Gateway. Later in the process, you will include the connection information for the second Independent Gateway server.

   Save the file as tsig.json for the procedures that follow.

   {
   "independentGateways": [
    {
    	"id": "ip-10-0-1-169.ec2.internal",
    	"host": "ip-10-0-1-169.ec2.internal",
    	"port": "21319",
    	"protocol" : "http",
    	"authsecret": "13660-27118-29070-25482-9518-22453"
    	}]
    }

   • "id" - The private DNS name of the AWS EC2 instance running Independent Gateway.
   • "host" - same as "id".
   • "port" - The housekeeping port, by default, "21319".
   • "protocol" - The protocol for client traffic. Leave this as http for the initial configuration.
   • "authsecret" - The secret that you copied in the previous step.

Independent Gateway: direct vs relay connection

Before proceeding, you must decide which connection scheme to configure in your deployment: direct or relay connection. Each option is briefly described here, along with relevant decision data points.

Relay connection: You can configure Independent Gateway to relay client communication over a single port to the gateway process on Tableau Server. We refer to this as a relay connection:

• The relay process results in an extra hop from Independent Gateway to the backend Tableau Server Gateway process. The extra hop degrades performance as compared to the direct connection configuration.
• TLS is supported for relay mode. All communication in relay mode is restricted to a single protocol (HTTP or HTTPS) and can therefore be encrypted and authenticated with TLS.

Direct connection: The Independent Gateway can communicate directly with the backend Tableau Server processes over multiple ports. We refer to this communication as direct connection:

• Because connection is direct to backend Tableau Server, client performance is markedly improved as compared to relay connection option.
• Requires opening 16+ ports from Public to Private subnets for direct process communication from Independent Gateway to Tableau Server computers.
• TLS is not yet supported on the processes from Independent Gateway to Tableau Server.

Verification: Base topology configuration

You should be able to access the Tableau Server admin page by browsing to http://<gateway-public-IP-address>.

If the Tableau Server sign-in page does not load, or if Tableau Server doesn't start then follow these troubleshooting steps:

Network: 

• Verify connectivity between Tableau deployment and Independent Gateway instance by running the following wget command from Tableau Server Node1: wget http://<internal IP address of Independent Gateway>:21319, for example:

   wget http://ip-10-0-1-38:21319

  If connection is refused or fails, then verify that the Public security group is configured to allow Independent Gateway housekeeping traffic (TCP 21319) from the Private security group.

  If security group is configured correctly, then verify you specified the correct IP addresses or IP ranges during the initialisation of Independent Gateway. You can view and change this configuration in the environment.bash file located at /etc/opt/tableau/tableau_tsig/environment.bash. If you make a change to this file then restart the tsig-http service as described below.

On the Proxy 1 host:

1. Overwrite the httpd.conf file with the Independent Gateway stub file:

   cp /var/opt/tableau/tableau_tsig/config/httpd.conf.stub /var/opt/tableau/tableau_tsig/config/httpd.conf

2. Restart tsig-httpd as a first troubleshooting step:

   sudo su - tableau-tsig
   systemctl --user restart tsig-httpd
   exit

On Tableau Node 1

• Double-check the tsig.json file. If you find errors, fix them and then run tsm topology external-services gateway update -c tsig.json.
• If running direct connection, verify the TCP ports listed in proxy_targets.csv are configured as ingress ports from Public to Private security groups.

Configure AWS application load balancer

Update DNS with public Tableau URL

Use your domain DNS zone name from the AWS Load Balancer description to create a CNAME value in your DNS. Traffic to your URL (tableau.example.com) should be sent to the AWS public DNS name.

Verify connectivity

After your DNS updates are finished, you should be able to navigate to the Tableau Server sign-in page by entering your public URL, for example, https://tableau.example.com.

Example authentication configuration: SAML with external IdP

The following example describes how to set up and configure SAML with Okta IdP and Mellon authentication module for a Tableau deployment running in the AWS reference architecture.

This example picks up from the previous section and assumes that you are configuring one Independent Gateway at a time.

The example describes how to configure Tableau Server and Independent Gateway over HTTP. Okta will send requests to the AWS load balancer over HTTPS, but all internal traffic will travel over HTTP. As you configure for this scenario, be aware of the HTTP vs HTTPS protocols when setting URL strings.

This example uses Mellon as a pre-authentication service provider module on the Independent Gateway servers. This configuration ensures that only authenticated traffic connects to Tableau Server, which also acts as a service provider with the Okta IdP. Therefore, you must configure two IdP applications: one for the Mellon service provider and one for the Tableau service provider.

Install Mellon for pre-auth

This example uses mod_auth_mellon, a popular open-source module. Some Linux distributions package obsolete mod_auth_mellon versions from an older repository. Those obsolete versions may contain unknown security vulnerabilities or functional problems. If you choose to use mod_auth_mellon, check that you are using a current version.

The mod_auth_mellon module is third-party software. We've made a best effort to verify and document the procedures to enable this scenario. However, third-party software may change or your scenario may differ from the reference architecture described here. Please refer to third-party documentation for authoritative configuration details and support.

1. On the active EC2 instance that is running Independent Gateway, install a current version of the Mellon authentication module.

2. Create the /etc/mellon directory:

   sudo mkdir /etc/mellon

Configure Mellon as pre-auth module

Run this procedure on the first instance of Independent Gateway.

You must have a copy of pre-auth_idp_metadata.xml file that you created from the Okta configuration.

1. Change directory:

   cd /etc/mellon

2. Create the service provider metadata. Run the mellon_create_metadata.sh script. You must include the entity ID and the return URL for your organisation in the command.

   The return URL is referred to as the single sign on URL in Okta. The final element of the path in the return URL is referred to as the MellonEndpointPath in the mellon.conf configuration file that follows later in this procedure. In this example, we specify sso as the endpoint path.

   For example:

   sudo /usr/libexec/mod_auth_mellon/mellon_create_metadata.sh https://tableau.example.com "https://tableau.example.com/sso"

   The script returns the service provider certificate, key, and metadata files.

3. Rename the service provider files in the mellon directory for easier readability. We will refer to these files by the following names in the documentation:

   sudo mv *.key mellon.key
   sudo mv *.cert mellon.cert
   sudo mv *.xml sp_metadata.xml
   

4. Copy the pre-auth_idp_metadata.xml file to the same directory.

5. Change ownership and permissions on all files in the /etc/mellon directory:

   sudo chown tableau-tsig mellon.key
   sudo chown tableau-tsig mellon.cert
   sudo chown tableau-tsig sp_metadata.xml
   sudo chown tableau-tsig pre-auth_idp_metadata.xml 
   sudo chmod +r * mellon.key
   sudo chmod +r * mellon.cert
   sudo chmod +r * sp_metadata.xml
   sudo chmod +r * pre-auth_idp_metadata.xml 

6. Create the /etc/mellon/conf.d directory:

   sudo mkdir /etc/mellon/conf.d

7. Create the global.conf file in the /etc/mellon/conf.d directory.

   Copy the file contents as shown below, but update MellonCookieDomain with your root domain name. For example, if domain name for Tableau is tableau.example.com, enter example.com for the root domain.

   <Location "/">
   AuthType Mellon
   MellonEnable auth
   Require valid-user
   MellonCookieDomain <root domain>
   MellonSPPrivateKeyFile /etc/mellon/mellon.key
   MellonSPCertFile /etc/mellon/mellon.cert
   MellonSPMetadataFile /etc/mellon/sp_metadata.xml
   MellonIdPMetadataFile /etc/mellon/pre-auth_idp_metadata.xml
   MellonEndpointPath /sso
   </Location>
   
   <Location "/tsighk">
   MellonEnable Off
   </Location>

8. Create the mellonmod.conf file in the /etc/mellon/conf.d directory.

   This file holds a single directive that specifies the location of the mod_auth_mellon.so file. The location in the example here is the default location of the file. Verify that the file is in this location, or change the path in this directive to match the actual location of mod_auth_mellon.so:

   LoadModule auth_mellon_module /usr/lib64/httpd/modules/mod_auth_mellon.so

Create Tableau Server application in Okta

Set authentication module configuration on Tableau Server

Run the following commands on Tableau Server Node 1. These commands specify the file locations for the Mellon configuration files on the remote Independent Gateway computer. Double-check that the file paths specified in these commands map to the paths and file location on the remote Independent Gateway computer.

tsm configuration set -k gateway.tsig.authn_module_block -v "/etc/mellon/conf.d/mellonmod.conf" --force-keys
tsm configuration set -k gateway.tsig.authn_global_block -v "/etc/mellon/conf.d/global.conf" --force-keys

To reduce downtime, do not apply changes until you have enabled SAML as described in the next section.

Enable SAML on Tableau Server for IdP

Restart tsig-httpd service

As your Tableau Server deployment applies changes, sign back into the Tableau Server Independent Gateway computer and run the following commands to restart the tsig-httpd service:

sudo su - tableau-tsig
systemctl --user restart tsig-httpd
exit

Validate SAML functionality

To validate end-to-end SAML functionality, sign-in to Tableau Server with the public URL (e.g. https://tableau.example.com) with the Tableau admin account that you created at the beginning of this procedure.

If TSM doesn't start ("gateway error") or if you get browser errors when you attempt to connect, see Troubleshooting Tableau Server Independent Gateway.

Configure authentication module on second instance of Independent Gateway

After you have successfully configured the first instance of Independent Gateway, deploy the second instance. The example here is the final process for installing the AWS/Mellon/Okta scenario described in this topic. The procedure assumes that you have already installed Independent Gateway on the second instance as described in this topic previously (Install Independent Gateway).

The process for deploying the second Independent Gateway requires the following steps:

1. On the second instance of Independent Gateway: Install the Mellon auth module.

   Do not configure the Mellon auth module as described earlier in this topic. Instead, you must clone the configuration as described in the subsequent steps.

2. On the configured (first) instance of Independent Gateway:

   Take a tar copy of the existing Mellon configuration. The tar backup will preserve all directory hierarchy and permissions. Run the following commands:

   cd /etc

   sudo tar -cvf mellon.tar mellon

   Copy mellon.tar to the second instance of Independent Gateway.

3. On the second instance of Independent Gateway:

   Extract ("unzip") the tar file to the second instance in the /etc directory. Run the following commands:

   cd /etc

   sudo tar -xvf mellon.tar

4. On Node 1 of the Tableau Server deployment: Update the connection file (tsig.json) with the connection information from the second Independent Gateway. You will need to retrieve the authentication key as described in this topic previously (Install Independent Gateway).

   An example connection file (tsig.json) is shown here:

   {
   "independentGateways": [
    {
      "id": "ip-10-0-1-169.ec2.internal",
      "host": "ip-10-0-1-169.ec2.internal",
      "port": "21319",
      "protocol" : "http",
      "authsecret": "13660-27118-29070-25482-9518-22453"
    },
    {
      "id": "ip-10-0-2-230.ec2.internal",
      "host": "ip-10-0-2-230.ec2.internal",
      "port": "21319",
      "protocol" : "http",
      "authsecret": "9055-27834-16487-27455-30409-7292"
    }]
    }

5. On Node 1 of the Tableau Server deployment: Run the following commands to update the configuration:

   tsm stop

   tsm topology external-services gateway update -c tsig.json
   

   tsm start

6. On both instances of Independent Gateway: As Tableau Server is starting, restart the tsig-httpd process:

   sudo su - tableau-tsig

   systemctl --user restart tsig-httpd

   exit

7. In AWS EC2>Target groups: Update target group to include the EC2 instance running the second Independent Gateway instance.

   Select the target group that you just created and then click on the Targets tab: 

   • Click Edit.
   • Select the EC2 instance of the second Independent Gateway computer and then click Add to registered. Click Save.