--- schema_version: "1" id: 5b50dcb0023dad51d3e7c7b3050a889fc4bc20be1356112dc5a5b5ae3f076037 title: Configure Connected Apps with OAuth 2.0 Trust collection: tableau version: next locale: en-gb portal_url: https://docs.salesforce.com/tableau/next/en-gb/server-linux/connected_apps_eas.md canonical_url: https://help.tableau.com/v0.0/server-linux/en-gb/connected_apps_eas.htm source_site: help.tableau.com content_type: documentation content_hash: fb8d2f084f7a21a0f1604b253724fbdb93fac95df406ceb5e9b7afe2fb0144b5 description: Configure connected apps with OAuth 2.0 trust by registering an external authorization server. --- [Skip to main content](#main-content) # Configure Connected Apps with OAuth 2.0 Trust As a Tableau Server admin, you can register one or more external authorisation servers (EASs) to establish a trust relationship between your Tableau Server 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 Server. 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. - To enable embedding through EAS, Tableau Server must be configured to use SSL for HTTP traffic. - 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 Server 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 Server. Follow the steps described below to register your EAS with Tableau Server . ### 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. ![](/tableau/next/en-gb/server-linux/en-gb/Img/connectedapp_how_EAS.png) 1. **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. 2. **External application redirects request to EAS:** External application responds with a webpage that redirects to the external authorisation server (EAS). 3. **User authenticates with EAS:** User authenticates and authorises with the EAS. 4. **EAS responds to webpage with authorisation code:** The EAS responds to the page with an authorisation code and redirects back to the webpage. 5. **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. 6. **Webpage requests content from Tableau:** Webpage loads the iFrame and sends a GET request to Tableau. 7. **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 Tableau Server , 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.
ClaimNameDescription or required value
"kid"Key IDRequired (in header). A unique key identifier from the identity provider.
"iss"IssuerRequired (in header or as a claim). Unique issuer URIthat identifies the trusted connect app and its signing key.
"alg"AlgorithmRequired (in header). JWT signing algorithm. Supported algorithm names are listed in the Class JWSAlgorithm page in the javadoc.io documentation. The signing algorithm can be configured using the vizportal.oauth.external_authorization_server.blocklisted_jws_algorithms command.
"sub"SubjectUsername of the authenticated Tableau Server user.
"aud"Audience

Value must be: "tableau"

"exp"Expiry TimeA valid JWT must not have expired. The expiry time (in UTC) of the JWT must be within the configured maximum validity period. Maximum validity period can be configured using vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes command.
"jti"JWT IDThe 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" (Added in Tableau Server 2022.3)
"tableau:metrics:embed" (Retired in Tableau Server 2023.3)
"tableau:ask_data:embed"(Added in Tableau Server 2023.1. Retired in Tableau Server 2024.2)

Notes:

  • Values must be passed as a list type.
  • For tableau:views:embed, the scope respects users’ permissions already configured in Tableau Server 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.

For VizQL Data Service workflows that use the REST API for authentication, the only supported scope is tableau:viz_data_service:read.

https://tableau.com/groupsDynamic group membershipFor embedding workflows only.

Value must match the name of one or more groups in Tableau Server. For more information, see Dynamic group membership using assertions.

(User attributes)(User attribute values)

For embedding workflows only.

Starting in Tableau Server 2025.1, 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](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1) section in the documentation distributed by the Internet Engineering Task Force (IETF) organisation. ### Step 2: Register your EAS with Tableau Server By registering your EAS with Tableau Server, you establish a trust relationship between the EAS and Tableau Server. 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 Server 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). There are two ways you can register server-wide EAS: using the TSM web UI or using TSM CLI. After registering the EAS, the established trust relationship applies to all sites on Tableau Server. ### Option 1: Using TSM web UI 1. As a Tableau Server admin, sign in to the Tableau Services Manager (TSM) web UI. For more information, see [Sign in to Tableau Services Manager Web UI](https://help.tableau.com/v0.0/server-linux/en-gb/sign_in_tsm.htm#sign-in-to-the-tsm-web-ui). 2. Do _one_ of the following: - In Tableau Server 2024.2 and later, navigate to the User Identity & Access page > Connected Apps tab. - In Tableau Server 2023.3 and earlier, navigate to the User Identity & Access page > Authorisation Server tab. 3. Do _one_ of the following: - In Tableau Server 2024.2 and later: 1. Select the Enable connected apps tick box. 2. Select the second radio button, Allow connected apps (configure at site level) and server-wide OAuth 2.0 trust (configure below). 3. In the Issuer URL text box, paste the issuer URL of the EAS. 4. Click the Save Pending Changes button. ![](/tableau/next/en-gb/server-linux/en-gb/Img/connectedapp_eas_register_new.png) - In Tableau Server 2023.3 and earlier: 1. Select the Enable OAuth access for embedded content tick box. 2. In the Issuer URL text box, paste the issuer URL of the EAS. 3. Click the Save Pending Changes button. ![Register an External Authorisation Server Form.](/tableau/next/en-gb/server-linux/en-gb/Img/connectedapp_eas_register.png) 4. When finished, do the following: 1. In the upper-right corner of the page, click the Pending Changes button. 2. In the bottom-right corner of the page, click the Apply Changes and Restart button to stop and restart Tableau Server. ![A list of pending external configuration changes for authorisation with option to Apply or Discard changes.](/tableau/next/en-gb/server-linux/en-gb/Img/connectedapp_eas_save.png) ### Option 2: Using TSM CLI 1. Open a command prompt as an admin on the initial node (where TSM is installed) in the cluster. 2. Run the following commands: tsm configuration set -k vizportal.oauth.external\_authorization.enabled -v true tsm configuration set -k vizportal.oauth.external\_authorization\_server.issuer -v "" tsm restart Beginning in Tableau Server 2024.2, you can register one or more EAS’s for a site. After registering the EAS at the site level, the established trust relationship applies to the site only. **Note:** A prerequisite to configuring a site-level EAS is that connected apps are enabled in TSM. ### Step 1: Enable connected apps 1. As a Tableau Server admin, sign in to the Tableau Services Manager (TSM) web UI. For more information, see [Sign in to Tableau Services Manager Web UI](https://help.tableau.com/v0.0/server-linux/en-gb/sign_in_tsm.htm#sign-in-to-the-tsm-web-ui). 2. Navigate to the User Identity & Access page > Connected Apps tab. 3. Select the Enable connected apps tick box. 4. Do _one_ of the following: - Select the first radio button, Allow connected apps (configure at site level) to enable registering EAS’s at the site-level only. ![](/tableau/next/en-gb/server-linux/en-gb/Img/connectedapp_eas_register_radio.png) - (Default) Select the second radio button, Allow connected apps (configure at site level) and server-wide OAuth 2.0 trust (configure below) to enable registering EAS’s at both the site-level and server-wide. If you choose this option, ensure the issuer URL specified at the site-level is different from the server-wide issuer URL. ![](/tableau/next/en-gb/server-linux/en-gb/Img/connectedapp_eas_register_radio_default.png) 5. Click the Save Pending Changes button. 6. When finished, do the following: 1. In the upper-right corner of the page, click the Pending Changes button. 2. In the bottom-right corner of the page, click the Apply Changes and Restart button to stop and restart Tableau Server. ### Step 2: Register the EAS 1. As a Tableau Server admin, sign in to Tableau Server. 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 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. ![](/tableau/next/en-gb/server-linux/en-gb/Img/connectedapp_create_eas.png) 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. ![Details of the external authorisation server, with a button to copy the site ID.](/tableau/next/en-gb/server-linux/en-gb/Img/connectedapp_eas_button_luid.png) ### Step 3: Next steps #### For embedding workflows After configuring Tableau Server 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 the following: - Embed Tableau content using the [Tableau Embedding API v3](https://help.tableau.com/current/api/embedding_api/en-gb/index.html). - User attributes for attribute-based access control (ABAC), on-demand access, and dynamic group membership, see [Customise and Control Data Access](https://help.tableau.com/current/api/embedding_api/en-gb/docs/embedding_api_user_attributes.html) in the Tableau Embedding API v3. - Embed metrics, see [Embed Metrics into Webpages](Https://help.tableau.com/current/pro/desktop/en-gb/embed_metrics.htm) topic in the Tableau Help. (In Tableau Server 2023.3, Tableau retired the ability to embed metrics.) **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 Tableau Server 2023.3, 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](https://help.tableau.com/current/api/rest_api/en-gb/REST/rest_api_ref_site.htm#update_embedding_settings_for_site) in the Tableau REST API Help - [Tableau Site Setting for Embedding](https://help.tableau.com/current/api/embedding_api/en-gb/docs/embedding_api_site.html#about-tableau-site-settings-for-embedding) 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](https://help.tableau.com/v0.0/server-linux/en-gb/connected_apps_scopes.htm). #### 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](https://help.tableau.com/v0.0/server-linux/en-gb/connected_apps_scopes.htm). #### For external tokens for SCIM workflows After the JWT has been configured, you must have the SCIM capability enabled. For more information, see [Configure Connected Apps with OAuth 2.0 Trust](#scim). ### 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. - **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. - **Embedded views on multiple sites:** In Tableau Server 2023.1 and earlier, switching between views on different sites in the same browser causes error 1008: Could not fetch secret for connect app. To work around this issue, upgrade to Tableau Server 2023.3 or later. ### 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 Tableau Server . Refer to the table below to review the description of the error code and potential resolution.
Error codeSummaryDescriptionPotential resolution or explanation
5SYSTEM_USER_NOT_FOUNDTableau user could not be found
To resolve this issue, verify the 'sub' (Subject) claim value in the JWT is the ‘username’ for the authenticated Tableau Server. This value is case sensitive.
16LOGIN_FAILEDLogin failedThis error is typically caused by one of the following claim issues in the JWT:
67FEATURE_NOT_ENABLEDOn-demand access is not supportedOn-demand access is available through licensed Tableau Cloud sites only.
10081COULD_NOT_RETRIEVE_IDP_METADATAMissing EAS metadata endpointTo resolve this issue, verify the EAS is configured correctly and the correct issuer is being called.
10082AUTHORISATION_SERVER_ISSUER_NOT_SPECIFIEDMissing issuerTo resolve this issue, verify that the correct issuer is being called. To change the issuer URL, you can use the vizportal.oauth.external_authorization_server.issuer command.
10083BAD_JWTJWT header contains issuesThe 'kid' (Secret ID) or 'clientId' (Issuer) claims are missing from the JWT header. To resolve this issue, ensure this information is included.
10084JWT_PARSE_ERRORJWT contains issuesTo 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.
10085COULD_NOT_FETCH_JWT_KEYSJWT could not find keysCould not find the secret.

To resolve this issue, verify that the correct issuer is being called. To change the issuer URL, you can use the vizportal.oauth.external_authorization_server.issuer command.

10087BLOCKLISTED_JWS_ALGORITHM_USED_TO_SIGNIssue with the JWT signing algorithmTo resolve the issue, you can remove the signing algorithm. For more information, see vizportal.oauth.external_authorization_server.blocklisted_jws_algorithms.
10088RSA_KEY_SIZE_INVALIDIssue with JWT signing requirementsTo resolve this issue, verify with the EAS or IdP that the JWT is being signed with an RSA key size of 2048.
10091JTI_ALREADY_USEDUnique JWT requiredThe JWT has already been used in the authentication process. To resolve this issue, the EAS or IdP must generate a new JWT.
10092NOT_IN_DOMAIN_ALLOW_LISTDomain of the embedded content is not specifiedTo 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 method in the Tableau REST API.
10094MISSING_REQUIRED_JTIMissing JWT IDTo resolve this issue, verify the 'jti' (JWT ID) is included in the JWT.
10096JWT_EXPIRATION_EXCEEDS_CONFIGURED_EXPIRATION_PERIOD The 'exp' (Expiry Time) exceeds the default maximum validity period. To resolve this issue, review registered claims required for a valid JWT and ensure the correct value is used. To change the maximum validity period, you can use the vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes command.
10097SCOPES_MALFORMEDIssues with scopes claimThis 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 on the auth0 site.
10098JWT_UNSIGNED_OR_ENCRYPTEDJWT is unsigned or encryptedTableau does not support an unsigned or encrypted JWT.
10099SCOPES_MISSING_IN_JWTMissing scopes claimThe 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 on the auth0 site.
10100JTI_PERSISTENCE_FAILEDUnexpected JWT ID errorThere was an unexpected error with the 'jti' (JWT ID). To resolve this issue, a new JWT with a new 'jti' must be generated.
10103JWT_MAX_SIZE_EXCEEDEDJWT exceeds maximum sizeThis 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 Server.