Authentication and Embedded Views


When you embed a Tableau view into your web application, you must consider whether users have permission to see that view. This is because when someone accesses the Tableau view in your web application, the same authentication protocols apply as if they were accessing the view on Tableau directly. For example, if you’re writing code to embed a view from Tableau Public, no authentication is required. However, if your code is getting a view from a hosted instance of Tableau Server, or Tableau Cloud, authentication is typically required. If the user is not already signed in to the server, Tableau redirects the request for a view to the Tableau sign in page, and the user must provide a username and password. After the user has signed in, the browser caches session information, and the user doesn’t have to sign in again unless they have explicitly signed out of Tableau, or until the session token expires.

Tableau 2021.4 introduced two new options for authenticating and authorizing users of embedded views: external authorization servers (EAS) and connected apps. These options make use of JSON web tokens (JWT) and control permissions and access to projects and control where a view can be embedded.

This topic discusses EAS and Tableau connected apps and how they can be used for authentication. For information about the other ways of authentication, see the Tableau Cloud and Tableau Server documentation.

In this section

External authorization servers (EAS) and connected apps

While having users sign in to Tableau generally works, assuming your browser allows 3rd-party cookies, it’s not necessarily the best experience for users of your embedded application. Starting in Tableau 2021.4, when you embed views using the Embedding API v3, you have two new options:

EAS and Tableau connected apps provide a way to create and manage explicit trust relationships between your Tableau Server instance, or Tableau Cloud site, and custom applications where Tableau content is embedded. You can control the views and projects that users of your embedded application have access to.

This topic describes how you can use EAS and Tableau connected apps to authenticate and manage the embedded Tableau views in your web applications.

Configure your web application to use a Tableau connected app

Connected apps have a trust relationship with Tableau. You can use Tableau Cloud or Tableau Server (using the REST API) to configure your embedded web application to use a connected app. After you set up the connected app, your users are able to authenticate through a JSON web token (JWT) generated by your web server using a shared secret signed by Tableau. When a user visits the embedded content in your web application, the embedded content is scoped to the privileges defined in the JWT.

For information about how to configure your web application to work with Tableau Cloud, see Use Tableau Connected Apps for Application Integration. For information about setting up a connected app on Tableau Server or Tableau Cloud using the Tableau REST API, see the Connected App Methods.

There are five parts to enabling your embedded view as a connected app.

  1. As a Tableau site administrator, sign in to Tableau Cloud and create a new connected app (or use the REST API connected apps methods to create a new connected app). Make note of the client ID, as you will need this to create the JWT.

  2. As a security best practice, use the domain allowlist to ensure Tableau content is only embedded in locations that you allow. See Domain allowlist rules (embedding workflows only).

  3. Generate the secret(s) for the connected app. Make note of this secret ID and secret value as you will need these when you create the JWT.

  4. Configure the web server that hosts your embedded application to generate the JWT. The JWT is generated dynamically for each user. If you’re not using usage-based licensing, you need to provide an appropriate user name in the JWT. For embedding, the JWT must include a registered claim for the scope ("scp"). See Pass the JWT to the Tableau web component for more information. There are JWT libraries and packages in various languages that you can use to build the JWT.

  5. After you have the JWT, you need to pass the JWT to the <tableau-viz>, <tableau-authoring-viz>, or <tableau-pulse> web component.

Important: When you embed a Tableau view in your application, your application must conform with your Tableau licensing, which means you need to generate a JWT dynamically for each enabled user. Never embed the credentials for one user in your connected app and then use that as authorization for others. For information about usage-based licensing and special licensing for embedded analytics, see Understanding License Models.

Configure your web application to use EAS

As a Tableau Server administrator, you can register an external authorization server (EAS) to establish a trust relationship between Tableau and the EAS. By establishing a trust relationship, you’re able to provide your users a single sign-on (SSO) experience to Tableau content embedded in your custom applications through the identity provider (IdP) you’ve already configured for Tableau. When embedded Tableau content is loaded in your custom application, a standard OAuth flow is used. After users successfully sign in to the IdP, they are then automatically signed in to Tableau.

To use EAS, your Tableau Server instance must be using an identity provider (IdP) for authentication. The EAS must be set up to provide a JSON web token (JWT). You use the JWT when you embed the Tableau view as a web component in your application. You need to configure the JWT so that it includes a registered claim for the scope ("scp"). For embedded views, set the value as tableau:views:embed. For embedded web authoring, set this value as tableau:views:embed_authoring. For embedded Tableau Pulse, set this value as tableau:insights:embed. You can specify more than one value for the scope. The scope respects the permissions a user already has configured in Tableau, which allows the user to interact with the the view the way they can on Tableau directly.

Pass the JWT to the Tableau web component

Whether you’re configuring your embedded web application to use EAS for Tableau Server, or as a connected app on Tableau Cloud, you need to configure the JWT so that it includes a registered claim for the scope ("scp"). For example, for embedded views, you set the value as tableau:views:embed.

Embedding Element Scope (scp)
TableauViz tableau:views:embed
TableauAuthoringViz tableau:views:embed_authoring, tableau:views:embed
TableauPulse tableau:insights:embed
AskData tableau:ask_data:embed *
Metrics tableau:metrics:embed *

* Note: In October 2023, Tableau retired the ability to embed metrics in Tableau Cloud and Tableau Server version 2023.3. Ask Data will be retired in Tableau Cloud in February 2024 and in Tableau Server version 2024.2.

You can specify more than one value for the scope. For example, for embedded web authoring you also need to include the scope for viewing (tableau:views:embed_authoring and tableau:views:embed). The scope respects the permissions a user already has configured in Tableau, which allows the user to interact with the the view the way they can on Tableau directly. You then explicitly pass the JWT that is generated by the EAS or by your web server to the <tableau-viz>, <tableau-authoring-viz>, or <tableau-pulse> web component. You do this by using the token attribute.

For example, you could programmatically build the JWT based on the connected app secrets and then add it to the <tableau-viz> web component as the token attribute, or if you’re using JavaScript assign the JWT to the TableauViz.token property.


<tableau-viz id="tableauViz"
  src='https://your-tableau-server/views/my-workbook/my-view'
  token="JWT generated from connected app secrets">
</tableau-viz>

Information about configuring the JWT for embedding is covered in the Tableau connected app documentation.

About Tableau Site settings for embedding

When you embed a view that has been configured to use a Tableau connected app for authentication, the domain allowlist of the connected app is not affected by the Tableau Site settings for embedding. For more information about how the site settings relate to connected apps, see the Tableau Site settings for embedding and connected apps.

About Tableau Site setting for user attributes

The Tableau Cloud site setting, Control User Access in Authentication Workflows enables user attribute functions used in embedded content to accept the passing of user attributes from a JSON Web Token (JWT). The use attributes are passed to Tableau to control and customize the data that can be shown to the user at runtime. Fore more information about user attributes, see Customize and Control Data Access Using User Attributes.

To enable this setting, sign in to Tableau Cloud as a site admin, select Settings > Authentication, and then select the Enable capture of user attributes in authentication workflows checkbox. Alternatively, you can use the Update Site endpoint using the Tableau REST API to programmatically enable the attribute-capture-enabled setting.

Error handling for connected apps

Starting with Tableau 2023.2 and the Embedding API v3 library version 3.6, there is a new authentication flow and an event type you can use to help catch and identify errors that might occur when you’re using a connected app or an external authorization server (EAS) for authentication. This event is triggered when an error happens during the initialization of the web component, which includes vizzes (authoring and viewing) and Ask Data web components. The errors include authentication errors, connectivity errors, etc..

Embedding multiple vizzes or Ask Data lenses

If you’re embedding multiple vizzes or Ask Data lenses in a web application using connected apps or EAS for authentication, be sure to use the same JWT for all embedded components. Using different tokens for each embedded component could lead to unexpected behavior, sometimes loading correctly and sometimes prompting users to sign in.

Note: Ask Data will be retired in Tableau Cloud in February 2024 and in Tableau Server version 2024.2.

Compatibility

This new authentication flow for connected apps, including the new error handling capability and related bug fixes, is only available if you’re using version 3.6 (or later) of the Embedding API library and Tableau 2023.2 (or later). As a general rule, you should always use the latest version of the library from the Tableau instance that hosts the view you’re embedding. If for some reason you need to use the authentication flow for connected apps that was available in previous version of Tableau and the Embedding API, the 3.6 version of the library provides an attribute that enables that behavior. Note that using the older flow does not provide the error handling capability available with the 3.6 library and Tableau 2023.2. For more information, see Use iframe-auth attribute to enable previous authorization flow.

Add an event listener for load and initialization errors

You can now set up an event listener for a viz loading error using this new event type, TableauEventType.VizLoadError or the web component attribute, onVizLoadError. In your callback function for the event handler, you can now take action depending upon the connected app error codes. For the list of error codes, see Troubleshoot Connected Apps.

For example, in a <tableau-viz> web component, you could add the event listener for the onVizLoadError and specify the callback function to handle the event (in this case, handleLoadError). You define your handleLoadError() function in your JavaScript code.


<tableau-viz id="tableauViz"
    src="https://my-server/views/my-workbook/my-view"
    token="JWT generated from connected app secrets"
    onVizLoadError="handleLoadError">
</tableau-viz>

To add the same event listener in JavaScript, you would first access the TableauViz object from the DOM, and then call addEventListener with the event type (TableauEventType.VizLoadError).


  const tableauViz = document.getElementById('tableauViz');
  tableauViz.addEventListener(TableauEventType.VizLoadError, handleLoadError);

In your event handler, you can capture the error code from the event payload and then use the status and error codes for debugging, or take some action based on the error code returned.

  function handleLoadError (e) {
    const message = JSON.parse(e.detail.message);
    console.log(message);
    // do something based on the error code in e.detail

  }

Another option is to use information about the error to determine whether to use the previous authentication flow, or whether to bypass the connected app authentication path completely and revert to the Tableau login prompt. The following example shows how you could create an event handler that switches to the previous flow when an unknown-auth-error occurs by setting the iframeAuth property. If a different load error occurs, the event handler removes the token attribute, so that the user sees the Tableau login prompt.


// Error handling logic
tableauViz.addEventListener(TableauEventType.VizLoadError, (e) => {
  if (e.detail.errorCode == "unknown-auth-error") {
    e.target.iframeAuth = true;
  } else {
    e.target.removeAttribute("token"); // prompt user to login
  }
});

Use iframe-auth attribute to enable previous authorization flow

Starting with the 3.6 library and Tableau 2023.2, the authentication flow for connected apps is handled through the Embedding API. With previous versions of the library and with prior versions of Tableau (that supported connected apps and EAS), the authentication flow was performed inside the iframe. If you can’t use the new authentication flow, you can revert to the previous flow by setting the iframeAuth property on the viz or Ask Data object, or the iframe-auth attribute on the component. Note that using the older flow does not provide the error handling capability available with the 3.6 library and Tableau 2023.2, so you will not be able to use the new VizLoadError event.

To use the older authentication flow with the 3.6 library and Tableau 2023.2, add the iframe-auth attribute in the web component (or set the iframeAuth property on the Viz object).


<tableau-viz id="tableauViz"
    src="https://my-server/views/my-workbook/my-view"
    token="JWT generated from connected app secrets"
    iframe-auth>
</tableau-viz>

For more information