Beginning in early January 2022, Tableau connected apps enable a seamless and secure authentication experience by facilitating an explicit trust relationship between your Tableau Online site and custom applications where Tableau content is embedded.

Connected apps offer the following benefits:

  • Restrict access to which content can be embedded and where that content can be embedded
  • Provide users the ability to access embedded content using single sign-on (SSO) without having to integrate with an identity provider (IdP)
  • Provide users the ability to authenticate directly from your custom application

Notes:

  • Though connected apps UI for Tableau Server will be available in a future release, Tableau Server admins can create and manage connected apps using the Connected App methods(Link opens in a new window) using the Tableau REST API.
  • Tableau connected apps and Salesforce connected apps are different and offer different functionality. Today, Tableau connected apps are optimized for embedding Tableau views and metrics in custom applications.

How connected apps work

The trust relationship between your Tableau Online site and custom application is established and verified through an authentication token in the JSON Web Token (JWT) standard, which uses a shared secret provided by the Tableau connected app and signed by your custom application.

Key components of a connected app

The following components of the connected work together with the JWT in your custom application to authenticate users and display embedded content.

  • Secrets: Secrets are keys shared by Tableau and your custom application. They are used in signatures that form the JWT. A secret is required when using connected apps for embedding authentication. Secrets can be created in a connected app, do not expire, and remain valid until deleted.
  • Domain allowlist: You can specify a list of allowed domains in each connected app. Tableau content embedded through a connected app is only allowed under the specified domains. This helps ensure that content is exposed under the domains that are secured and approved by your business.
  • Access level: You can specify what content can be embedded through a connected app by associating a connected app with one project or all projects. If you specify one project, only the content in the selected project can be embedded through the connected app.

Connected app workflow

The diagram below illustrates how authentication works between your custom application (web server and webpage) and connected app.

  1. User visits the webpage: When a user visits the embedded content on a webpage, webpage sends a GET request to your custom application to retrieve the HTML on that webpage.
  2. Custom application constructs an authentication token: The custom application constructs a JWT, which contains a secret from the connected app (see Step 3 below for additional JWT requirements) and the scope of user access for the embedded content. The secret is signed by custom application and is used for verification of the trust relationship in a later step.
  3. Custom application responds with authentication token: The custom application responds to the page with the JWT in the embedded content’s URL called by the webpage.
  4. Webpage requests content from Tableau: With the attempt to load the embedded content, the webpage calls the embedded content’s URL, which sends a GET request to Tableau.
  5. Tableau validates the token: Tableau receives the JWT and verifies the trust relationship with the custom application by identifying the connected app and shared secret used in the JWT. Then Tableau creates a session for the user. The session not only respects the embedding scopes defined in the JWT, but also the restrictions specified in the connected app, including the allowed domains and allowed projects.
  6. Tableau returns the content based on the restricted embedding context: The embedded content only loads when the page is under an allowed domain and the content is published to an allowed project (if applicable). The authenticated user can only interact with the embedded content by the scope defined in the JWT.

Create a connected app

Step 1: Create a connected app

Create a connected app from Tableau Online’s Settings page.

  1. As a site admin, sign in to Tableau Online.

  2. From the left pane, select Settings > Connected Apps, and then click the New Connected App button.

  3. In the Create Connected App dialog box, do the following:
    1. In the Connected app name text box, enter a name for the connected app.

    2. From the Applies to drop-down menu, select All project or Only one project to control which views or metrics can be embedded. If you select the "Only one project" option, select the specific project to scope to.

    3. In the Domain allowlist, specify the domains using the rules described in Domain formatting below to control where views or metrics can be embedded.

    4. When finished, click the Create button.

  4. Next to the connected Apps name, click the actions menu and select Enable. For security purposes, a connected app is set to disabled by default when created.

  5. Make note of the connected app’s ID, also known as the client ID, to use in Step 3 below.

Step 2: Generate a secret

You can generate a total of two secrets for each connected app. The second secret can be used for secret rotation purposes to help protect against issues if a secret is compromised.

  1. On the detail page of the connected app you created in Step 1, click the Generate New Secret button.

  2. Make note of the secret ID and secret value to use in Step 3 below.

Step 3: Configure the JWT

After you’ve generated a secret, you want to enable your custom application to send a valid JWT. JWT is a standard used to securely transfer information between two parties. The JWT is signed by your custom application to securely send information to Tableau Online. The JWT references the connected app, the user that the session is being generated for, and the level of access the user should have.

A valid JWT includes the following information:

  • Connected app ID, also known as the client ID, from Step 1
  • Secret ID and secret value generated in Step 2

  • Registered claims and header:

    Claim Description or required value
    "iss" (Issuer) Unique issuer URI that identifies the trusted connect app and its signing key. The issuer must be included in the header.
    "alg" (Algorithm) JWT signing algorithm. Only HS256 is supported. The algorithm must be included in the header.
    "sub" (Subject) User name (email address) of the authenticated Tableau Online user.
    "aud" (Audience) Value must be: "tableau"
    "exp" (ExpirationTime) A valid JWT must not be expired. The expiration time of the JWT must be within the configured maximum validity period, which is 10 minutes.
    "scp" (Scope)

    Supported values include:

    "tableau:views:embed"
    "tableau:metrics:embed"

    Notes:

    • Values must be passed as a list type.
    • For tableau:views:embed, the scope respects users’ permissions already configured in Tableau Online and allows users to interact with the tools in the embedded view if available in the original view.
    • We recommend the embed code exclude the toolbar parameter. For more information see Known issues below.

Example JWTs

Here are example JWTs in both Java and Python languages.

Java

String secret = "secretvalue";
	String kid = "connectedAppSecretId";
	String clientId = "connectedAppClientId";
	List<String> scopes = new
ArrayList<>(Arrays.asList("tableau:views:embed"));
	String username = "user@domain.com";
	JWSSigner signer = new MACSigner(secret);
	JWSHeader header = new
JWSHeader.Builder(JWSAlgorithm.HS256).keyID(kid).customParam("iss", clientId).build();
	JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
		.issuer(clientId)
		.expirationTime(new Date(new Date().getTime() + 60 * 1000)) //expires in 1 minute
		.jwtID(UUID.randomUUID().toString())
		.audience("tableau")
		.subject("username")
		.claim("scp", scopes)
		.build();
	SignedJWT signedJWT = new SignedJWT(header, claimsSet);
	signedJWT.sign(signer);
	model.addAttribute("token", signedJWT.serialize());

Python

token = jwt.encode(
	{
		"iss": connectedAppClientId,
		"exp": datetime.datetime.utcnow() + datetime.timedelta(minutes=5),
		"jti": str(uuid.uuid4()),
		"aud": "tableau",
		"sub": user,
		"scp": ["tableau:workbooks:read", "tableau:views:read"]
	},
		connectedAppSecretKey,
		algorithm = "HS256",
		headers = {
		'kid': connectedAppSecretId,
		'iss': connectedAppClientId
        }
  )

After you’ve configured the JWT, when the code is run by your custom application, it will generate a token.

Step 4: Embedding next steps

After JWT has been configured, you must add embed code to your custom application. Ensure that you include the valid JWT you configured in Step 3 above in the web component that your custom application calls.

For more information about embedding Tableau content, see one or both of the following:

Note: For users to successfully authenticate when they access embedded content, browsers must be configured to allow third-party cookies or use partitioned storage. Partitioned storage is on by default for Mozilla Firefox and can be enabled on Google Chrome browsers.

Manage a connected app

The Connected Apps page is where you can manage all the connected apps for your site. You can perform tasks such creating, deleting, and disabling connected apps; and revoking or generating new secrets if existing secrets have been compromised.

  1. As a site admin, sign in to Tableau Online.

  2. From the left pane, select Settings > Connected Apps.

  3. Select the check box next to the connected app you want to manage and do one or more of the following:

    • Generate a new secret according to the rotation time line specified by your organization’s security policies. To generate an additional secret, click on the name of the connected app and then click the Generate New Secret button. A connected app can have a maximum of two secrets. Both secrets can be active at the same time, do not expire, and remain valid until deleted.

    • Review the connected app details by clicking the name of the connected app to see when the connected app was created, its ID, project and domain scopes, and its secrets.

    • Change the project scope or domain, in the Actions menu, select Edit. Make your changes and click Update.

      Note: If you change the project or domain scopes and the embedded content doesn’t exist in either the new project or new domain, the embedded view or metric is unable to display and users will see an error when accessing the embedded content.

    • Delete a secret by clicking the connected app's name. On the connected app’s page, click Actions next to the secret and select Delete. In the confirmation dialog box, select Delete again.

      Note: If the connected app’s secret is being used by a custom application, the embedded view or metric is unable to display after the secret is deleted. For more information, see Effects of disabling or deleting a connected app, or deleting a secret below.

    • Disable a connected app, in the Actions menu, select Disable. If the connected app is being used by a custom application, the embedded view or metric is unable to display after the connected app is disabled. For more information, see Effects of disabling or deleting a connected app, or deleting a secret below.

Effects of disabling or deleting a connected app, or deleting a secret

To display an embedded view to your user through a connected app requires the connected app to be enabled and secret generated. If the connect app is being used in your custom application and is either disabled or deleted, or its secret deleted or replaced, users will get an error when accessing the embedded content.

To avoid this issue, ensure the connect app is enabled and the JWT is using the correct secret ID and value.

Domain allowlist rules

The connected app’s domain allowlist enables you to restrict access to embedded Tableau content to all domains or some domains; or exclude some domains or block all domains.

Domain options

You can select one of two options when configuring a connected app’s domain allowlist:

  • All domains: As the default option, this option enables unrestricted access to embedded content.
  • Only specific domains: This option gives you the ability to scope down access to embedded content. If you use this option, follow the formatting rules specified in the following section, Domain formatting.

Domain formatting

In the domain allowlist text box, you can enter one domain, multiple domains, or no domains at all. The domain allowlist respects any formatting allowed by the CSP (Content Security Policy) framework’s frame-ancestors header(Link opens in a new window).

Note: Domain formatting rules also apply when using the Connect App methods(Link opens in a new window) in the Tableau REST API.

Here are some formatting examples based on common scenarios:

To specify... Example Embedding access
Range of domains *.myco.com Embedded content is accessible from all subdomains under myco.com.
Multiple discrete domains myco.com
events.myco.com
ops.myco.com
Embedded content is accessible from all three domains.
No domains [no domains] Access to embedded content is blocked.

Known issues

There are a couple of known issues when using connected apps that will be addressed in a future release.

  • Toolbar features: When embedded content has the toolbar parameter defined, not all toolbar features will work. To work around this issue, we recommend you hide the toolbar parameter like in the example below.

    <tableau-viz id='tab-viz' src='https://online.tableau.com/t/<your_site>/...'
    	toolbar='hidden'>
    </tableau-viz>

  • Published data sources: Published data sources set to Prompt User for database credentials will not display. To work around this issue, if possible, we recommend data source owners embed their database credentials instead.
Thanks for your feedback!