Manage Dashboard Extensions in Tableau Server

Dashboard extensions are web applications that run in custom dashboard zones and can interact with the rest of the dashboard using the Tableau Extensions API. Dashboard extensions give users the ability to interact with data from other applications directly in Tableau.

Note: You must be a server administrator to enable dashboard extensions on the server, or to block specific extensions from running. You must be a server administrator to add extensions to the safe list and to control the type of data the extensions can access. The server administrator can also configure whether users on the site will see prompts when they add or view extensions in a dashboard. For information about extension security and recommended deployment options, see Extension Security - Best Practices for Deployment

For information about using dashboard extensions in Tableau, see Use Dashboard Extensions.

Before you run extensions on Tableau Server

Tableau supports two types of dashboard extensions: Network-enabled extensions, which can be hosted on web servers located inside or outside of your local network and have full access to the web, and Sandboxed extensions, which run in a protected environment without access to any other resource or service on the web.

Sandboxed extensions are hosted by Tableau and employ W3C standards, such as Content Security Policy (CSP), to ensure the extension can’t make network calls outside of the hosting Tableau Server. A Sandboxed extension can query data in the dashboard, but it can’t send that data anywhere outside of the sandbox. Sandboxed Extensions are supported in Tableau 2019.4 and later. By default, Sandboxed extensions are allowed to run if extensions are enabled for the site.

Network-enabled dashboard extensions are web applications and could be running on any computer set up as a web server. This includes local computers, computers in your domain, and third-party web sites. Because Network-enabled extensions could be hosted on third-party sites and could have access to the data in the dashboard, you want to only allow the extensions you trust. See Test Network-enabled extensions for security.

For security, you can use the settings for dashboard extensions on Tableau Server to control and limit the dashboard extensions that are allowed to run.

  • By default, Sandboxed extensions are allowed to run if extensions are enabled for the site.

  • By default, no Network-enabled extensions are allowed unless they have been explicitly added to the safe list.

  • By default, only extensions that use the HTTPS protocol are allowed, which guarantees an encrypted channel for sending and receiving data (the only exception is for http://localhost).

  • If the Network-enabled extension requires full data (access to the underlying data) the extension will not be able to run on Tableau Server unless you explicitly add the extension to the safe list and grant the extension access to full data.

Control dashboard extensions and access to data

Server administrators can control a global setting to allow extensions for all sites on the server. Server administrators can also put extensions, including Sandboxed extensions, on a global block list to prevent them from running (see Block specific extensions). By default, all Sandboxed extensions are enabled on the server, but site administrators can choose to override the default and prohibit Sandboxed extensions for the site.

Change the global setting enabling extensions on the server

  1. To change this setting for the server, go to Manage All Sites > Settings > Extensions. If the server just has a single site, the global controls appear on the settings page for the site.

  2. Under Dashboard Extensions, select or clear the Let users run extensions on this server checkbox. If this option is not selected, extensions are not allowed to run. This global setting overrides the Let users run extensions on this site settings for each site.

Change the default settings for a site

Server administrators can control whether to enable extensions for the site and whether to allow Sandboxed extensions on the site. That is, if extensions are enabled on the server, the default site settings allow Sandboxed extensions to run on the site, provided the extension is not specifically blocked on the server. The default site settings allow Network-enabled extensions to run that appear on the safe list for the site.

  1. To change these settings for the site, go to Settings > Extensions.

  2. Under Dashboard Extensions, configure these options:

    • Let users run extensions on this site
    • Let Sandboxed extensions run unless they are specifically blocked by a server administrator

Server administrators can add or remove Network-enabled extensions from the safe list for a site. When you add an extension to the safe list, you can control whether to allow the extension to have access to full data. See Add extensions to the safe list and configure user prompts.

Identifying an extension

As a web application, an extension is associated with a URL. You use this URL to test and verify the extension. You also use the URL to add the extension to the safe list to allow full data access, or to the block list to prohibit any access.

If you have the extension manifest file (.trex), an XML file that defines properties for the extension, you can find the URL from the <source-location> element.


<source-location>
    <url>https://www.example.com/myExtension.html</url>
</source-location>

				

If you have added the extension to the dashboard, you can find the URL from the extension properties. From the More Options menu, click About.

The About dialog box lists the name of the extension, the author of the extension, the web site of the author, along with the URL of the extension.

Add extensions to the safe list and configure user prompts

To ensure that users can use Network-enabled extensions that are trusted, you can add them to the safe list for the site.

On the safe list, you can control whether to grant the extension full data access. You can also control whether users will see a prompt asking them to allow the extension access to data. If the extension does not require full data access, you don’t need to add it to the safe list. However, you might want to add an extension to the safe list so that you can configure whether or not users see the prompts. When you hide the prompt from users, the extension can run immediately.

  1. Go to Settings > Extensions.

  2. Under Enable Specific Extensions, add the URL of the extension. See Identifying an extension.

  3. Choose to Allow or Deny the extension Full Data Access.

    Full data access is access to the underlying data in the view, not just the summary or aggregated data. Full data access also includes information about the data sources, such as the names of the connection, fields, and tables. In most cases, if you are adding an extension to the safe list so that it can run, you will also want to allow the extension to have access to full data, if the extension requires it. Before adding extensions to the safe list, be sure to Test Network-enabled extensions for security.

  4. Choose to Show or Hide the User Prompts.

    Users see the prompts by default when they are adding an extension to a dashboard, or when they are interacting with a view that has an extension. The prompt tells users details about the extension and whether the extension has access to full data. The prompt gives users the ability to allow or deny the extension from running. You can hide this prompt from users, allowing the extension to run immediately.

Block specific extensions

The default global policy allows all Sandboxed extensions and those Network-enabled extensions that appear on the safe list for a site. Server administrators can keep specific extensions from running by adding them to the block list for the server. If an extension is on the global block list it overrides any settings for the extension on the safe list for a site.

  1. To add an extension to the blocked list for the server, go to Manage All Sites > Settings > Extensions. On single-site installations, the block list is on the site Extensions settings page.

  2. Under Block Specific Extensions, add the URL of the extension. See Identifying an extension.

Test Network-enabled extensions for security

Dashboard extensions are web applications that interact with data in Tableau using the Extensions API. Network-enabled dashboard extensions could be hosted on web servers inside or outside of your domain, and can make network calls and have access to resources on the Internet. Because of this and the potential vulnerabilities, such as cross-site scripting, you should test and vet Network-enabled dashboard extensions before users use them in dashboards on Tableau Desktop, and before you allow the extensions on Tableau Server.

Examine the source files

Dashboard extensions are web applications and include various HTML, CSS, and JavaScript files, and an XML manifest file (*.trex) that defines the properties in the extension. In many cases, the code for a dashboard extension is publicly available on GitHub and can be examined there or downloaded. In the manifest file (*.trex), you can find the source location, or URL indicated where the extension is hosted, the name of the author, and the web site of the author or company to contact for support. The <source-location> element specifies in the URL, the <author> element, specifies the name of the organization and the web site to contact for support (website="SUPPORT_URL"). The web site is the Get Support link user see in the About dialog box for the extension.

Many dashboard extensions reference external JavaScript libraries, such as the jQuery library or API libraries for third parties. Validate that the URL for external libraries points to a trusted location for the library. For example, if the connector references the jQuery library, make sure that the library is on a site that is considered standard and safe.

All extensions are required to use HTTPS protocol (https://) for hosting their extensions. You should examine the source files for the extension to ensure that any reference to external libraries is also using HTTPS or is hosted on the same web site as the extension. The one exception to the requirement of HTTPS is if the extension is hosted on the same computer as Tableau (http://localhost).

To the extent possible, make sure you understand what the code is doing. In particular, try to understand how the code is constructing requests to external sites, and what information is being sent in the request. In particular, check if any user-supplied data is validated to prevent cross-site scripting.

Understand data access

The Tableau Extensions API provides methods that can access the names of the active tables and fields in the data source, the summary descriptions of the data source connections, and the underlying data in a dashboard. If an extension uses any of these methods in a view, the extension developer must declare that the extension requires full data permission in the manifest file (.trex). The declaration looks like the following.


<permissions>
   <permission>full data</permission>
</permissions>

Tableau uses this declaration to provide a prompt to users at run time that gives them the option of allowing this access or not. If the extension uses any one of these four methods, without declaring full-data permission in the manifest file, the extension will load but the method calls will fail.

For information about how an extension accesses data from the dashboard, and the JavaScript methods used, see Accessing Underlying Data in the Tableau Extensions API. To get a better understanding about what the extension can find out about the data, you can use the DataSources sample dashboard extension (available from the Tableau Extensions API GitHub repository) to see what data is exposed when the getDataSourcesAsync() method is called.

Test the extension in an isolated environment

If possible, test the dashboard extension in an environment that is isolated from your production environment and from user computers. For example, add a dashboard extensions to a safe list on a test computer or virtual machine that's running a version of Tableau Server that is not used for production.

Monitor traffic created by the dashboard extension

When you test a Network-enabled dashboard extension, use a tool like Fiddler, Charles HTTP proxy, or Wireshark to examine the requests and responses that the extension makes. Make sure that you understand what content the extension is requesting. Examine the traffic to be sure that the extension is not reading data or code that is not directly related to the purpose of the extension.

Thanks for your feedback! There was an error submitting your feedback. Try again or send us a message.