Configure Connected Apps with OAuth 2.0 Trust

Applies to: Tableau Cloud, Tableau Server

As a Tableau Cloud site admin, you can register one or more external authorisation servers (EASs) to establish a trust relationship between your Tableau Cloud site and the EAS using the OAuth 2.0 standard protocol.

Important:

Some of the procedures in this topic require configuration with third-party software and services. We’ve made a best effort to verify the procedures to enable the EAS feature on Tableau Cloud. However, third-party software and services might change or your organisation might differ. If you encounter issues, refer to your third-party documentation for authoritative configuration details and support.
In order for the session token to be valid, the clocks of the external application and the server that hosts the external application must be set to Coordinated Universal Time (UTC). If either clock uses a different standard, the connected app will not be trusted.

How Tableau-connected apps work with OAuth 2.0 trust

The trust relationship between your Tableau Cloud site and external application is established and verified through an authentication token in the JSON Web Token (JWT) standard.

When embedded Tableau content is loaded in your external application, Authorisation Code Flow, OAuth flow is used. After users successfully sign in to the IdP, they are then automatically signed in to Tableau Cloud. Follow the steps described below to register your EAS with your Tableau Cloud site.

Key components of a connected app

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

External authorisation server (EAS): The server, typically your IdP, that functions as the interface between the user and the external application. The server authenticates and authorises user access to the protected Tableau content.
Issuer URL: The URL that uniquely identifies the EAS instance.

Connected app workflow

Embedding workflows

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

User visits the web page: When a user visits the embedded content on a webpage, the webpage sends a GET request to the external application.
External application redirects request to EAS: External application responds with a webpage that redirects to the external authorisation server (EAS).
User authenticates with EAS: User authenticates and authorises with the EAS.
EAS responds to webpage with authorisation code: The EAS responds to the page with an authorisation code and redirects back to the webpage.
EAS converts authorisation code to JWT: Webpage calls the EAS to convert the authorisation code to a JWT, which the webpage puts into the embedded content’s URL.
Webpage requests content from Tableau: Webpage loads the iFrame and sends a GET request to Tableau.
Tableau validates the token: Tableau validates the JWT in the URL with the signature and responds with the content and respects the embedding scopes defined in the JWT.

Create a connected app

Step 1: Before you begin

To register an EAS with your Tableau Cloud site, you must have an EAS already configured. In addition, the EAS must send a valid JSON Web Token (JWT) that contains the registered claims and header listed in the table below.

Claim	Name	Description or required value
"`kid`"	Key ID	Required (in header). A unique key identifier from the identity provider.
"`iss`"	Issuer	Required (in header or as a claim). Unique issuer URI, in HTTPS, that identifies the trusted connect app and its signing key.
"`alg`"	Algorithm	Required (in header). JWT signing algorithm. Supported algorithm names are listed in the Class JWSAlgorithm(Link opens in a new window) page in the javadoc.io documentation.
"`sub`"	Subject	Username (email address) of the authenticated Tableau Cloud user.
"`aud`"	Audience	Value must be: "`tableau:<site_luid>`" To obtain the site LUID, you can use the Tableau REST API's Sign In method or follow the steps below to copy the site ID. Note: You must register an EAS using the procedure described here before you can copy the site ID. Select Settings > Connected Apps and then select the External Authorisation Server connected app. Click the Copy Site ID button.
"`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	The JWT ID claim provides a unique identifier for the JWT and is case sensitive.
"`scp`"	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`, 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.
`https://tableau.com/groups`	Dynamic group membership	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 attributes)	(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.

Note: The JWT claims above are documented in the Registered Claim Names(Link opens in a new window) section in the documentation distributed by the Internet Engineering Task Force (IETF) organisation.

Step 2: Register your EAS with Tableau Cloud

By registering your EAS with Tableau Cloud, you establish a trust relationship between the EAS and your Tableau Cloud site. This means when users access Tableau content embedded in your external application, they are redirected to authenticate with the IdP. The EAS generates the authentication token, which is passed to Tableau Cloud for verification. After the trust relationship is verified, access to the embedded content is granted to users.

Note: Some EASs support the option to display a consent dialog that asks for users’ approval for the application to access Tableau content. To ensure the best experience for your users, we recommend you configure your EAS to automatically consent to the external application’s request on users’ behalf.

About site-level EAS

Beginning in Tableau Server 2024.2, you can configure site-level EAS. To register an EAS at the site-level, connected apps must be enabled in Tableau Server Manager (TSM).

As a site admin, sign in to Tableau Cloud.
From the left pane, select Settings > Connected Apps.
Click the New Connected App button drop-down arrow and select OAuth 2.0 Trust.
In the Create Connected App dialog box, do the following:
1. In the Name text box, enter a name for the connected app.
2. In the Issuer URL text box, paste the issuer URL of the EAS.
3. Select the Enable connected app. For security purposes, a connected app is set to disabled by default when created.
4. When finished, click the Create button.
After the connected app is created, copy the connected app’s site ID. The site ID is used for the JWT's ‘aud’ (Audience) claim described in Step 1 above.

Step 3: Next steps

For embedding workflows

After configuring your Tableau Cloud site to use your EAS, you must add embed code to your external application. Ensure that you include the valid JWT generated by your EAS, as described in Step 1, in the web component that your external application calls.

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

Embed metrics, see Embed Metrics into Webpages(Link opens in a new window) topic in the Tableau Help. (In October 2023 (Tableau 2023.3), Tableau retired the ability to embed metrics.)
Embed Tableau views and metrics using the Tableau Embedding API v3(Link opens in a new window).

Note: For users to successfully authenticate when they access embedded content, browsers must be configured to allow third-party cookies.

Control where content can be embedded using domain allowlist for embedding

Starting in June 2023 (Tableau 2023.2), you and your users can control whether Tableau content can be embedded without restriction or restricted to certain domains using the Update Embedding Settings for Site method in Tableau REST API.

By default, the unrestrictedEmbedding site setting for embedding is set to true to allow unrestricted embedding. Alternatively, you and your users can set the setting to false and specify the domains where Tableau content in external applications can be embedded using the allowList parameter.

For more information, see one or both of the following:

Update Embedding Settings for Site(Link opens in a new window) in the Tableau REST API Help
Tableau Site Setting for Embedding(Link opens in a new window) in the Tableau Embedding API v3 Help.

For REST API authorisation workflows

After the JWT has been configured, you must add the valid JWT to the REST API Sign In request for authorised access. For more information, see Access Scopes for Connected Apps.

For Metadata API workflows

After the JWT has been configured, you must add the valid JWT to the REST API Sign In request. For more information, see Access Scopes for Connected Apps.

Manage a connected app

On-demand access (embedding workflows only)

Beginning in October 2023, if your site is licensed with the Embedded Analytics(Link opens in a new window) usage-based model, you can extend access to your embedded Tableau content to more users using on-demand access. With on-demand access, you allow your users to interact with embedded Tableau content authenticated through your connected app without needing to provision those users in your Tableau Cloud site. On-demand access removes the requirement for you to add and manage users in Tableau Cloud to support access to embedded content.

How on-demand access works

Access to embedded Tableau content using on-demand access is determined by group-level permissions either inherited by (for example, at the project-level) or directly applied to the content. Users like site admins, project owners or leaders, and content owners can assign group-level permissions to content. When users access the embedded content enabled through the on-demand access capability, Tableau validates the JWT contains the correct group membership claims before displaying the content.

Prerequisites

The following criteria must be true to enable on-demand access for embedded content:

Site is licensed with the Embedded Analytics(Link opens in a new window) usage-based model
On-demand access capability is enabled for the group
Group permissions are specified for the Tableau content
Tableau connected app is created
JWT used by the connected app includes the https://tableau.com/oda and https://tableau.com/groups claims
Tableau content is embedded in an external application

When these criteria are met, your users can interact with embedded Tableau content enabled through on-demand access capability.

Enable on-demand access capability

To enable the on-demand access capability for a group, when creating or editing a group, you must select the Allow on-demand access check box. 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(Link opens in a new window) and Update Group(Link opens in a new window) methods in the Tableau REST API Help.

Capabilities when on-demand access is enabled

Users accessing embedded Tableau content have View capabilities(Link opens in a new window) on the content. Users have View capabilities regardless of the selected template or customised capabilities that might be configured for the group (for example, a user with a role of Viewer will never be able to download a data source even if that capability is explicitly granted to them on a specific data source).

Monitor on-demand access

If you have Tableau Cloud with Advanced Management(Link opens in a new window), you can use Activity Log to monitor on-demand access usage. Events in the Activity Log that capture on-demand access include, but are not limited to, access view and login. For more information about these events, see Activity Log Event Type Reference.

Limitations

Because on-demand access workflows enable certain users who access embedded Tableau Content to be anonymous and ephemeral to Tableau Cloud, the following capabilities are not available to users who access embedded content enabled through the on-demand access capability:

Create custom views
Share content using the content's share button
Subscribe to content for email snapshots of information

Note: Beginning in February 2024 (Tableau 2024.1), Tableau REST API requests can be made as a user with on-demand access.

Dynamic group membership (embedding workflows only)

Beginning in June 2024 (Tableau 2024.2), if connected apps are configured and the capability’s setting is enabled, you can dynamically control group membership through custom claims included in the JWT sent by the external application.

When configured, during user authentication, the external application sends the JWT that contains two custom claims for group membership: group (https://tableau.com/groups) and group names (for example, "Group1" and "Group2") to assert the user into. Tableau validates the JWT and then enables access to the groups and the content whose permissions are dependent on those groups.

For more information, see Dynamic group membership using assertions.

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.

Troubleshoot

When embedded content fails to display in your external application or the Tableau REST API authorisation fails, you can use a browser’s developer tools to inspect and identify error codes that might be associated with the EAS feature enabled on your Tableau Cloud site.

Refer to the table below to review the description of the error code and potential resolution.

Error code	Summary	Description	Potential resolution or explanation
5	SYSTEM_USER_NOT_FOUND	Tableau user could not be found	To resolve this issue, verify the '`sub`' (Subject) claim value in the JWT is the username (email address) of the authenticated Tableau Cloud user. This value is case sensitive.
16	LOGIN_FAILED	Login failed	This error is typically caused by one of the following claim issues in the JWT: The '`exp`' (Expiry Time) exceeds the default maximum validity period. To resolve this issue, review registered claims(Link opens in a new window) required for a valid JWT and ensure the correct value does not exceed 10 minutes. The '`sub`' (Subject) is calling an unknown user. To resolve this issue, verify the '`sub`' value is the username (email address) of the authenticated Tableau Cloud user.
67	FEATURE_NOT_ENABLED	On-demand access is not supported	On-demand access is available through licensed Tableau Cloud sites only.
142	EXTERNAL_AUTHORIZATION_SERVER_NOT_FOUND	EAS not found	To resolve this issue, verify that the correct issuer is being called.
143	EXTERNAL_AUTHORIZATION_SERVER_LIMIT_EXCEEDED	EAS limit exceeded	The site has reached the maximum allowable number (1) of registered external authorisation servers (EAS).
144	INVALID_ISSUER_URL	Invalid issuer URL	The issuer URL is not valid or the '`iss`' (Issuer) attribute is missing from the JWT.
149	EAS_INVALID_JWKS_URI	Missing JWKS URI	JWKS URI does not exist in the IdP metadata or the JWKS URI is not configured in Tableau. To resolve this issue, configure a valid JWKS URI.
150	EAS_RETRIEVE_JWK_SOURCE_FAILED	Failure in retrieving keysource	To resolve this issue, verify the JWKS URI is configured correctly.
151	EAS_RETRIEVE_METADATA_FAILED	Failure in retrieving metadata from issuerUrl	To resolve this issue, verify the JWKS URI is configured correctly.
10081	COULD_NOT_RETRIEVE_IDP_METADATA	Missing EAS metadata endpoint	To resolve this issue, verify the EAS is configured correctly and the correct issuer is being called.
10082	AUTHORISATION_SERVER_ISSUER_NOT_SPECIFIED	Missing issuer	To resolve this issue, verify that the correct issuer is being called.
10083	BAD_JWT	JWT header contains issues	The '`kid`' (Secret ID) or '`clientId`' (Issuer) claims are missing from the JWT header. To resolve this issue, ensure this information is included.
10084	JWT_PARSE_ERROR	JWT contains issues	To resolve this issue, verify the following: The '`aud`' (Audience) value referenced in the JWT uses the ‘tableau’ value. This value is case sensitive. The '`aud`' (Audience) and '`sub`' (Subject) are included in the JWT.
10085	COULD_NOT_FETCH_JWT_KEYS	JWT could not find keys	Could not find the secret. To resolve this issue, verify that the correct issuer is being called.
10087	BLOCKLISTED_JWS_ALGORITHM_USED_TO_SIGN	Issue with the JWT signing algorithm	To resolve the issue, you can remove the signing algorithm.
10088	RSA_KEY_SIZE_INVALID	Issue with JWT signing requirements	To resolve this issue, verify with the EAS or IdP that the JWT is being signed with an RSA key size of 2048.
10091	JTI_ALREADY_USED	Unique JWT required	The JWT has already been used in the authentication process. To resolve this issue, the EAS or IdP must generate a new JWT.
10092	NOT_IN_DOMAIN_ALLOW_LIST	Domain of the embedded content is not specified	To resolve this issue, ensure the `unrestrictedEmbedding` setting is set to `true` or `domainAllowlist` parameter includes the domains where Tableau content is embedded using the Update Embedding Settings for Site(Link opens in a new window) method in the Tableau REST API.
10094	MISSING_REQUIRED_JTI	Missing JWT ID	To resolve this issue, verify the '`jti`' (JWT ID) is included in the JWT.
10095	EXTERNAL_AUTHZ_SERVER_DISABLED	EAS disabled	The connected app for the EAS registered to the site is disabled.
10096	JWT_EXPIRATION_EXCEEDS_CONFIGURED_EXPIRATION_PERIOD		The '`exp`' (Expiry Time) exceeds the default maximum validity period. To resolve this issue, review registered claims(Link opens in a new window) required for a valid JWT and ensure the correct value does not exceed 10 minutes.
10097	SCOPES_MALFORMED	Issues with scopes claim	This error can occur when the '`scp`' (Scope) claim is either missing from the JWT or not passed as a list type. To resolve this issue, verify '`scp`' is included in the JWT and passed as a list type. For troubleshooting help with a JWT, see Debugger(Link opens in a new window) on the auth0 site.
10098	JWT_UNSIGNED_OR_ENCRYPTED	JWT is unsigned or encrypted	Tableau does not support an unsigned or encrypted JWT.
10099	SCOPES_MISSING_IN_JWT	Missing scopes claim	The JWT is missing the required '`scp`' (Scope) claim. To resolve this issue, verify '`scp`' is included in the JWT. For troubleshooting help with a JWT, see Debugger(Link opens in a new window) on the auth0 site.
10100	JTI_PERSISTENCE_FAILED	Unexpected JWT ID error	There was an unexpected error with the '`jti`' (JWT ID). To resolve this issue, a new JWT with a new '`jti`' must be generated.
10101	EPHEMERAL_USER_LOGIN_FAILED_SITE_NOT_UBP_ENABLED	On-demand access is not supported	The site is not licensed with the Embedded Analytics usage-based model that is required to enable on-demand access. For more information, see Understanding Licence Models.
10102	EPHEMERAL_USER_NOT_SUPPORTED	On-demand access is not supported when iframe-auth attribute is enabled	This error can occur when the iframe-auth attribute is enabled. To resolve this issue, verify that the Tableau Embedding API version 3.6 or later is being used.
10103	JWT_MAX_SIZE_EXCEEDED	JWT exceeds maximum size	This error can occur when JWT size exceeds 8000 bytes. To resolve this issue, make sure that only the necessary claims are being passed to Tableau Cloud.

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau Cloud Help