Tableau Cloud Help

Connected app workflow

Embedding workflows

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

1. User visits the web page: When a user visits the embedded content on a web page, the web page sends a GET request to your external application to retrieve the HTML on that web page.
2. External application constructs an authentication token: The external 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 the external application and is used for verification of the trust relationship in a later step.
3. External application responds with authentication token: The external application responds to the page with the JWT in the embedded content’s URL called by the web page.
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 external 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 Cloud’s Settings page.

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

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

3. Click the New Connected App button drop-down arrow and select Direct Trust.

4. In the Create Connected App dialog box, do one of following:

   • For REST API authorisation workflows (including Metadata API workflows that use the REST API for authentication), in the Connected app name text box, enter a name for the connected app and click the Create button.

     Note: You can ignore Access level and Domain allowlist when configuring a connected app for REST API and Metadata API authorisation.

   • For embedding workflows, 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. For more information about these two options, see Access level (embedding workflows only).

        Notes: 

        • In October 2023 (Tableau 2023.3), Tableau retired the ability to embed metrics.
        • In February 2024 (Tableau 2024.1), you can specify multiple projects using the Tableau REST API. For more information, see Create Connected App(Link opens in a new window) and Update Connected App(Link opens in a new window) methods in the REST API Help.

     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.

        Important: We recommend using the domain allowlist as a security best practice to ensure Tableau content is only embedded in locations that you allow.

     4. When finished, click the Create button.

        

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

   

6. 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 external application to send a valid JWT. JWT is a standard used to securely transfer information between two parties. The JWT is signed by your external application to securely send information to Tableau Cloud. 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	Name	Description or required value
  "kid"	Secret ID	Required (in header). The connected app's secret key identifier.
  "iss"	Issuer	Required (in header). Unique issuer URI that identifies the trusted connect app and its signing key.
  "alg"	Algorithm	Required (in header). JWT signing algorithm. Only HS256 is supported.
  "sub"	Subject	Username (email address) of the authenticated Tableau Cloud user.
  "aud"	Audience	Value must be: 'tableau'.
  "exp"	Expiry Time	A valid JWT must not have expired. The expiry time (in UTC) of the JWT must be within the maximum validity period, which is 10 minutes.
  "jti"	JWT ID	Required as a claim. The JWT ID claim provides a unique identifier for the JWT and is case sensitive.
  "scp" Important: Do not use "scope".	Scope	For embedding workflows, supported values include: "tableau:views:embed" “tableau:views:embed_authoring” "tableau:metrics:embed" (Retired in October 2023 (Tableau 2023.3)) “tableau:ask_data:embed” (Retired in February 2024 (Tableau 2024.1)) Notes: Values must be passed as a list type. For tableau:views:embed and tableau:views:embed_authoring, the scope respects users’ permissions already configured in Tableau Cloud and allows users to interact with the tools in the embedded view if available in the original view. We recommend that the embed code excludes the toolbar parameter. For more information see Known issues (embedding workflows only) below. For REST API authorisation workflows, see REST API methods that support JWT authorisation. For Metadata API workflows that use the REST API for authentication, the only supported scope is tableau:content:read.
  https://tableau.com/oda	On-demand access – claim (enable capability)	For embedding workflows only. Value must be "true" and one or more Tableau Cloud groups must be specified (see next row). For more information, see the On-demand access (embedding workflows only) section below.
  https://tableau.com/groups	On-demand access – claim (specify group name)	For embedding workflows only. Value must match the name of one or more groups in Tableau Cloud. For more information, see the On-demand access (embedding workflows only) section below.
  		For embedding workflows only. Value must match the name of one or more groups in Tableau Cloud. For more information, see the Dynamic group membership (embedding workflows only) section below.
  (User attribute)	(User attribute values)	For embedding workflows only. You can include user attributes in the JWT. Then when user attribute functions are used in embedded content, Tableau checks the authenticated user’s context and determines what data can display at runtime. Notes: Check the Embedding API v3(Link opens in a new window) Help for known issues that might affect your workflow. For the user attribute to work, 1) you must enable the Control User Access in Authentication Workflows setting and 2) the content author must create a user attribute function(Link opens in a new window). User attributes are case sensitive.

Example JWTs

Here are example JWTs in both Java and Python languages. The Java and Python examples use the nimbus-jose-jwt library and the PyJWT library, respectively.

Java

import com.nimbusds.jose.*;
import com.nimbusds.jose.crypto.*;
import com.nimbusds.jwt.*;

import java.util.*;

...

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)
		.claim("https://tableau.com/oda", "true")
		.claim("https://tableau.com/groups", "Contractors", "Team C", "Group1", "Group2")
		.claim("Region", "East")
		.build();
	SignedJWT signedJWT = new SignedJWT(header, claimsSet);
	signedJWT.sign(signer);
	model.addAttribute("token", signedJWT.serialize());

Python

import jwt

token = jwt.encode(
	{
		"iss": connectedAppClientId,
		"exp": datetime.datetime.utcnow() + datetime.timedelta(minutes=5),
		"jti": str(uuid.uuid4()),
		"aud": "tableau",
		"sub": user,
		"scp": ["tableau:views:embed", "tableau:metrics:embed"],
		"https://tableau.com/oda":"true",
		"https://tableau.com/groups": ["Contractors", "Team C", "Group1", "Group2"],
		"Region": "East"
	},
		connectedAppSecretKey,
		algorithm = "HS256",
		headers = {
		'kid': connectedAppSecretId,
		'iss': connectedAppClientId
        }
  )

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

Step 4: Next steps

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 Cloud.

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

3. Tick the 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 timeline specified by your organisation’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 by selecting Edit in the Actions menu. 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 an external 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 by selecting Disable in the Actions menu. If the connected app is being used by an external 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 embedded content to your user or enable REST API access through a connected app, the connected app must be enabled and its secret generated. If the connect app is being used in your external application and is either disabled or deleted, or its secret deleted or replaced, users will get a 403 error.

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

Domain allowlist rules (embedding workflows only)

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

Important: We recommend using the domain allowlist as a security best practice to ensure Tableau content is only embedded in locations that you allow.

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 or more domains using the formatting examples below.

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:

Known issues (embedding workflows only)

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.

• Ask Data objects in embedded dashboards: Ask Data objects in embedded dashboards will not load. (In February 2024 (Tableau 2024.1), Tableau retired Ask Data.)

• Metrics and domain allowlists: Embedded metrics views will be displayed despite access restrictions that might be specified in the connected apps' domain allowlists. Note: Metrics data accessed from toolbars of embedded views will work as expected. (In October 2023 (Tableau 2023.3), Tableau retired the ability to embed metrics.)

Troubleshoot

You can refer to Troubleshoot Connected Apps - Direct Trust for errors that might be associated with the connected app and suggested troubleshooting steps.