Authentication and Embedded Views


When you embed a Tableau view into your web application, you need to consider whether users will 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 are 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 Configure Tableau Connected Apps to Enable SSO for Embedded Content. 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 four 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. 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.

  3. Configure the web server that hosts your embedded application to generate the JWT. The JWT is generated dynamically for each user. 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.

  4. After you have the JWT, you need to pass this value to the <tableau-viz> or <tableau-authoring-viz> web component.

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. 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 are 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 embedded views, set the value as tableau:views:embed. For embedded web authoring, set this value as tableau:views:embed_authoring. For embedding metrics, set this value to tableau:metrics:embed. For embedding Ask Data, set this value to tableau:ask_data:embed. You can specify more than one value for the scope. For example, for embedded web authoring you would want to also include the scope for viewing. 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-ask-data> 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 are 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.

For more information