When you embed a Tableau content into your web application, you must consider whether users have permission to see that content. This is because when someone accesses the Tableau content 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 Tableau Cloud or a hosted instance of Tableau Server, 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 connected apps for authenticating and authorizing users of embedded content: direct trust and OAuth 2.0 trust. These options make use of JSON Web Tokens (JWTs) and control permissions and access to projects and control where content can be embedded.
Tableau 2025.3 introduced an additional option for authenticating users of embedded content: unified access tokens (UATs). UATs facilitate authentication to embedded content and control access to content using JSON Web Tokens (JWTs).
This topic discusses connected apps and UATs and how they can be used for authentication. For information about the other ways of authentication, see the Tableau Cloud and Tableau Server documentation.
For information about the authentication options, see the following:
For Tableau Cloud - Site Authentication in the Tableau Cloud Help.
For Tableau Server - Authentication (Windows) or Authentication (Linux) in the Tableau Server Help.
(Tableau Cloud only)
Starting in Tableau 2025.3, you can use unified access tokens (UATs), configured through Tableau Cloud Manager (TCM), to enable and authorize access to embedded views using JSON Web Token (JWT). When users visit the embedded content in your web application, the embedded content is scoped to the privileges defined in the JWT. UATs, like connected apps, enable you to control the views and projects that users of your embedded application have access to.
For more information about UATs, see Unified Access Tokens in the Tableau Cloud Manager REST API Help.
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 options:
Connected apps provide a way to create and manage explicit trust relationships between your Tableau Cloud site or Tableau Server, and custom applications where Tableau content is embedded. You can control the views and projects that users of your embedded application have access to.
Note: For users to successfully authenticate when they access embedded content, browsers must be configured to allow third-party cookies
Connected apps have a trust relationship with Tableau. You can use Tableau Cloud, Tableau Server, or the Tableau REST API to configure a connected app for your embedded web application. 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.
There are five parts to enabling a connected app.
As a Tableau Cloud site administrator or Tableau Server administrator, sign in to Tableau and create a new connected app. Alternatively, you can use the Tableau REST API’s connected apps methods to create a new connected app. Make note of the client ID, as you will need this to create the JWT.
Generate the secret for the connected app. Make note of this secret ID and secret value as you will need these when you generate the JWT.
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 must 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.
<tableau-viz>, <tableau-authoring-viz>, or <tableau-pulse> web component.For more information about configuring a connected app using direct trust, see the following:
As a Tableau Cloud site administrator or 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 a connected app with OAuth 2.0 trust, your Tableau Cloud site or 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 must configure the JWT so that it includes 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.
For more information about configuring a connected app using OAuth 2.0 trust, see the following:
Whether you’re configuring your embedded web application to use a unified access token (UAT) or connected app, you must 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 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>
For sample code showing how you can construct the JWT, see the connected-apps-jwt-samples repository on GitHub. This repository contains samples in popular programming languages for generating a JWT.
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.
The Tableau Cloud or Tableau Server 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).
To enable this setting, do the following:
Sign in to Tableau Cloud as a site administrator or Tableau Server as an administrator, 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.
(Tableau Cloud only)
On-demand access is not enabled through a Tableau Cloud site setting. Instead, to enable the on-demand access capability for a group, when creating or editing a group, you must select the Allow on-demand access checkbox.
For more information about creating groups, see Create a Group and Add Users to It.
You can also enable this capability using the Tableau REST API. For more information, see the Create Group and Update Group methods in the Tableau REST API Help.
The Tableau Cloud site or Tableau Server setting, Assertions for Group Membership, enables you to dynamically control group members through assertions. Two custom group membership claims must be included in the JWT assertion to specify group membership.
To enable this setting, do the following:
Sign in to Tableau Cloud as a site administrator or Tableau Server as an administrator, go to the Settings page (for a multi-site Tableau Server, navigate to the Settings page for all sites). Under the Assertions for Group Membership heading, select the Allow group assertions to enable group membership through SAML or JWT assertions checkbox.
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 views (authoring and viewing) and Ask Data web components. The errors include authentication errors, connectivity errors, etc.
If you’re embedding multiple views or Ask Data lenses in a web application using connected apps 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.
This 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). Generally, 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 versions of Tableau and the Embedding API, the 3.6 version of the library provides an attribute that enables that behavior.
Note: 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.
You can set up an event listener for a view 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 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
}
});
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), 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 view or Ask Data object, or the iframe-auth attribute on the component.
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 information about setting up a connected app on Tableau Cloud or Tableau using the Tableau REST API, see Connected App Methods.
For information about configuring a unified access token (using the Tableau Cloud Manager REST API), see Unified Access Tokens.
For sample code showing how you can construct the JWT, see the connected-apps-jwt-samples repository on GitHub.