Register EAS to Enable SSO for Embedded Content

Applies to: Tableau Cloud, Tableau Server

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

Provide your users with a single sign-on (SSO) experience to Tableau content embedded in your external applications through the identity provider (IdP) you’ve already configured for Tableau Server
Programmatically authorise access to the Tableau REST API (and the Metadata API starting in Tableau Server October 2023) 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 Server. Follow the steps described below to register your EAS with Tableau Server.

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.

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.

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 URIthat 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. The signing algorithm can be configured using the vizportal.oauth.external_authorization_server.blocklisted_jws_algorithms command.
"`sub`"	Subject	Username of the authenticated Tableau Server 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 configured maximum validity period. Maximum validity period can be configured using vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes command.
"`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`" (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. Will be 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`.

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

After registering the EAS, the established trust relationship applies to all sites on Tableau Server.

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.

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.
Navigate to User Identity & Access > Authorisation Server, and do the following:
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.
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.

Open a command prompt as an admin on the initial node (where TSM is installed) in the cluster.

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 "<issuer_url_of_EAS>"
tsm restart

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 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 Tableau Server 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 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(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.

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://<your_server>/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 be displayed in your external application or 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 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’ for the authenticated Tableau Server. 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 is used. To change the maximum validity period, you can use the vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes command. The '`sub`' (Subject) is calling an unknown user. To resolve this issue, verify the '`sub`' claim is "username". This value is case sensitive.
67	FEATURE_NOT_ENABLED	On-demand access is not supported	On-demand access is available through licensed Tableau Cloud sites only.
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. To change the issuer URL, you can use the vizportal.oauth.external_authorization_server.issuer command.
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. To change the issuer URL, you can use the vizportal.oauth.external_authorization_server.issuer command.
10087	BLOCKLISTED_JWS_ALGORITHM_USED_TO_SIGN	Issue with the JWT signing algorithm	To resolve the issue, you can remove the signing algorithm. For more information, see vizportal.oauth.external_authorization_server.blocklisted_jws_algorithms.
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.
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 is used. To change the maximum validity period, you can use the vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes command.
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.
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 Server.

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau Server on Linux Help