Configure Connected Apps with OAuth 2.0 Trust

Applies to: Tableau Cloud, Tableau Server

As a Tableau Cloud site admin, you can register an external authorization server (EAS) to establish a trust relationship between your Tableau Cloud site and the EAS using the OAuth 2.0 standard protocol. By establishing a trust relationship, you’re able to:

  • Provide your users a single sign-on (SSO) experience to Tableau content embedded in your external applications through the identity provider (IdP) you’ve already configured for your Tableau Cloud site
  • Programmatically authorize access to the Tableau REST API on users' behalf using a JSON Web Token (JWT)

When embedded Tableau content is loaded in your external application, a standard 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.

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

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 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) User name (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.

  1. Select Settings > Connected Apps and then select the External Authorization Server connected app.

  2. Click the Copy Site ID button.
"exp" (Expiration Time)

A valid JWT must not be expired. The expiration 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"
"tableau:ask_data:embed"

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 the embed code exclude the toolbar parameter. For more information see Known issues (embedding workflows only) below.

For REST API authorization workflows, see REST API methods that support JWT authorization.
(User attributes)

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:

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) organization.

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

Note: Some EAS 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.

  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 OAuth 2.0 Trust.

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

    1. In the Issuer URL text box, paste the issuer URL of the EAS.

    2. Select the Enable connected app. For security purposes, a connected app is set to disabled by default when created.

    3. When finished, click the Create button.

  5. 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:

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 version 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:

For REST API authorization workflows

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

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 Tableau REST API authorization fails, you can use a browser’s developer tools to inspect and identify error codes that might be associated with the EAS feature enabled 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 user name (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' (Expiration 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 user name (email address) of the authenticated Tableau Cloud user.
142 EXTERNAL_AUTHORIZATION_SERVER_NOT_FOUND EAS not found To resolve this issue, verify 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 authorization 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 AUTHORIZATION_SERVER_ISSUER_NOT_SPECIFIED Missing issuer To resolve this issue, verify 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 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 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' (Expiration 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 a unexpected error with the 'jti' (JWT ID). To resolve this issue, a new JWT with a new 'jti' must be generated.
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.
Back to top
Thanks for your feedback!