Configure Authentication Module with Independent Gateway

Applies to: Tableau Advanced Management

A common security practice is to allow only authenticated requests to pass through the inner firewall of the DMZ servers. The Independent Gateway supports the traditional Tableau Server authentication methods, but it also includes configuration properties that allow integrating an Apache HTTPD loadable module for custom authentication.

For example, by configuring SAML on Tableau Server and configuring a custom authentication module, you can require all users to authenticate with your IdP at the Independent Gateway. Only those users who are authenticated will then be able to access Tableau Server, which can then authenticate and authorise user access.

For a more detailed explanation of this authentication scheme, see Pre-authentication with an AuthN module(Link opens in a new window) in the Enterprise Deployment Guide.

To configure the authentication module, you must complete the following steps:

Generate authentication module configuration files. When setup is complete, each module and its configuration directives will be treated as Include options, making the included files logically part of the overall HTTPD configuration.
Copy the configuration files to each computer running Independent Gateway. All files must be copied to the same locations on each Independent Gateway computer. Each file maps to a configuration property that is managed by Tableau Server.
Set the configuration properties with the tsm configuration set command on Tableau Server.

Do not edit the HTTPD configuration file (httpd.conf) on the Independent Gateway, since Independent Gateway includes logic to update HTTPD configuration based on changes made with TSM commands on Tableau Server.

Example authentication module configuration

For an end-to-end authentication module configuration example, see Example authentication configuration: SAML with external IdP(Link opens in a new window) in the Enterprise Deployment Guide. The example describes how to set up and configure SAML with Okta IdP and Mellon authentication module for a Tableau Server on Linux deployment running in AWS. Although the example describes the process for Linux, the configuration example is also useful for Tableau Server on Windows.

Configuration properties

The following table describes the various configuration files that you may reference. Each file maps to a configuration property that is set on Tableau Server. Use forward slashes in the path, even on Windows (Apache HTTPD convention.) You only need to define the properties necessary to formulate your custom authentication configuration. Skip any configuration properties that are not needed.

Configuration property	Description
gateway.tsig.authn_module_block	Appears at the end of the set of normally loaded Apache HTTPD modules. The intent is that the file includes one or more `LoadModule` directives. The modules themselves should be identified with full paths.
gateway.tsig.authn_global_block	Appears after all of the `LoadModule` references and before most other Apache HTTPD directives. The intent is to provide a place for any configuration directives needed by the custom module.
gateway.tsig.authn_globalbottom_block	Appears at the very bottom of the configuration file, again at the global level. The intent is to provide a place for any configuration directives needed by the custom module that must specifically come after various other directives. (You are unlikely to need this.)
gateway.tsig.authn_location_block	Appears inside a `<Location "/">` block, covering all URL paths.
gateway.tsig.authn_directory_block	This appears inside a `<Directory "/">` block, covering all paths to files served by the Independent Gateway. (You are unlikely to need this. Most files served by Independent Gateway are non-sensitive static assets, like images and JavaScript files.)
gateway.tsig.authn_virtualhost_block	Appears inside one or two `<VirtualHost>` blocks: one for TLS (if enabled) and one for non-TLS. If configured, the same file is included in both places. If you need to distinguish the two cases, you can use the standard Apache httpd HTTPS environment variable.

The `<Location "/tsighk">` block

In addition to the expected <Location "/"> block for normal request traffic, there is also a <Location "/tsighk"> block used to service internal Independent Gateway housekeeping (HK) requests. These HK requests have their own authentication guards and will not work with typical custom SSO solutions.

You may need to explicitly exclude your custom module from attempting authentication for the HK URL path.

To determine whether you need to exclude your module, first configure the module. Then look for HK requests in the Independent Gateway access log. You should see at least a status check once or twice a minute. If those requests are receiving a 200 response code, things are probably OK. On the other hand, if those requests receive a 3xx response code (redirecting to your custom authentication provider), you need to do something about it.

Possible solutions include:

The <Location "/tsighk"> block contains the directive AuthType None, and that may be sufficient.
The Independent Gateway httpd.conf has the standard Apache HTTPD directive ProxyPreserveHost(Link opens in a new window) On. If there is an unusual circumstance that requires it to be Off or some other value, that value can be set with the TSM configuration item gateway.tsig.proxypreservehost.
You might need some module-specific directives to disable your authentication module for <Location "/tsighk">. You can't directly modify that block in the httpd.conf file. Instead, you can make another <Location "/tsighk"> block in your gateway.tsig.authn_global_block file and let Apache HTTPD logically merge them. For example, some versions of mod_auth_mellon, a popular open source authentication module, requires MellonEnable Off for sections where it doesn't apply, even if AuthType None is set in those sections.
When creating an additional <Location "/tsighk"> section, as described in the previous bullet, you may find that the order of appearance of the various sections in the httpd.conf file makes a difference in how they affect each other. The standard <Location "/tsighk"> section appears before the standard <Location "/"> section. If your experimentation shows that some different order is needed, you might have to define another <Location "/"> section in your gateway.tsig.authn_global_block block in addition to another <Location "/tsighk"> section, in which case, you might not need anything in a gateway.tsig.authn_location_block block.

Troubleshoot custom authentication module configuration

A handy way to understand how the Independent Gateway will compose the httpd.conf file is to set the TSM configuration items with values that point to empty files on your Independent Gateway computers. (The files must exist, but they can be empty.) You can then look at the Independent Gateway's httpd.conf file to get a concrete understanding of where the Include directives for the various configuration files will actually appear.

Configuration problems in the Independent Gateway httpd.conf can result in the tsig-httpd service being unable to start. Other configuration problems may interfere with receiving configuration updates from the Independent Gateway companion service on the Tableau Server cluster. One way to recover, after you've fixed whatever caused the problem, is to copy TSIG_DATA/config/httpd.conf.stub to TSIG_DATA/config/httpd.conf, and then restart the tsig-httpd service.

For more troubleshooting tips, see Troubleshooting Tableau Server Independent Gateway(Link opens in a new window) in the Enterprise Deployment Guide (EDG). The EDG provides an example deployment of Tableau Server on Linux. The troubleshooting steps are useful for Windows or Linux versions of Tableau Server.

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau Server on Windows Help