> ## Documentation Index
> Fetch the complete documentation index at: https://docs.curator.interworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed Authentication

> Configure secure authentication methods for embedding Tableau dashboards in Curator with single sign-on options.

Embedded Authentication is how we securely connect users on the frontend to their Tableau Dashboards. Depending
on your selected method it automatically establishes a single sign-on experience or requires additional configuration
outside of Curator to avoid a second login screen to authenticate to Tableau.

Different authentication methods are available, including:

* [Connected Apps (Recommended)](#connected-apps-recommended)
* [Tableau Default Authentication](#tableau-default-authentication)
* [Trusted Tickets (Deprecated - End of Life in October 2025)](#trusted-tickets-deprecated---end-of-life-in-october-2025)

This article will guide you through setting up Embed Authentication using these methods.

## Connected Apps (Recommended)

Connected Apps establish a trusted relationship between Curator and Tableau, enabling secure authentication for
embedded Tableau content and REST API access. Unlike Trusted Tickets and Tableau Default Authentication, Connected
Apps do not depend on third-party cookies, which are increasingly being blocked by modern web browsers.

### Requirements

* Connected Apps are supported on
  * **Tableau Cloud**
  * **Tableau Server version 2022.4 and higher**.
* The Service Account User must be a
  * **Site Admin** on Tableau Cloud and
  * **Server Admin** on Tableau Server (Site Admin cannot manage Connected Apps on Tableau Server!)
* Both **Tableau Server and Curator must use SSL** to establish a trusted relationship.

*Note:* You can set up Connected Apps with either Service Username and Password or Personal Access Token.

### Service Account Best Practices

The service account used for Connected Apps is the identity Curator uses to create and manage Connected Apps and to
generate embed tokens for your users. Choosing the right account and credential type helps prevent integration
failures caused by staff turnover, credential revocations, or accidental role changes.

#### Use a Dedicated, Non-Personal Service Account

Create a dedicated service account (e.g., `curator-service@yourorg.com`) rather than using an individual employee's
Tableau account. A personal account is tied to a specific person; if that person leaves the organization, changes
roles, or has their account suspended, Curator loses access to the Connected App and all embedded dashboards stop
loading. A dedicated service account remains stable through staffing changes and makes it clear that the account
exists solely for Curator's integration.

#### Personal Access Token Considerations

Personal Access Tokens (PATs) expire on a fixed schedule and are revoked automatically when the issuing user's
password changes or their account is deactivated. If a PAT expires or is revoked without being replaced, Curator
cannot authenticate and embedded dashboards will fail to load. Tableau Cloud connections require a PAT for
authentication, so set a calendar reminder well before the expiration date to rotate the token. For Tableau Server
connections, username and password credentials are also available and do not carry an automatic expiration date.

#### Retain the Required Tableau Role

The service account must keep the required role at all times:

* **Tableau Cloud**: Site Admin
* **Tableau Server**: Server Admin

If the role is downgraded, Curator will no longer be able to manage Connected Apps or generate embed tokens.
Dashboards will fail to load for all users until the role is restored.

#### Recovery Steps After a Role Change or Credential Failure

If the service account's role is changed or its credentials become invalid, follow these steps to restore the integration:

1. Restore the service account to the required role (Site Admin on Tableau Cloud or Server Admin on Tableau Server).
2. If using a PAT, generate a new token and update it in the Curator connection settings.
3. Navigate to Integrations > Connections in the Curator backend and open the affected Tableau connection.
4. Verify the Connected App details are displayed and save the connection.
5. Clear the Curator backend cache to remove any stale session data.
6. Test by loading an embedded Dashboard in the frontend to confirm the connection is working.

### Setup

To set up Embed Authentication using Connected Apps you need to have an existing Connection to either Tableau Cloud or
Tableau Server. If not, follow our
[Tableau Connection setup guide](/creating_integrations/tableau_connection/creating_a_connection).

1. Navigate to the backend of the system (e.g. `http://curatorexample.com/backend`).
2. Navigate to Integrations > Connections and select your Tableau connection that you want to set up Connected Apps for.
3. Scroll down to the ***Embed Authentication*** section and expand it.
4. Select **Connected Apps**.
5. Save the Connection.

After saving, Curator will create the Connected App and display following details:

* Primary Site Connected App
* Client ID & Secret - the secret is obfuscated, but a placeholder represents successful retrieval
* Creation Timestamps

If multiple Connected Apps are detected, you can select in the Primary Site Connected App dropdown which one to
use. All other fields are automatically populated and show information for troubleshooting purposes only.
If you are embedding Dashboards from multiple sites add each additional site you'd like to
connect Curator to under *Secondary Sites* ensuring each has its own Connected App.

### Troubleshooting

The following scenarios have been encountered during the process of updating an existing connection to use Connected
Apps. We have added the steps to resolve here.

> * Trying to save my connection, I get an error message that contains:
>   `Missing Site <your site> from the list of secondary site.`

Curator detected that you are embedding Dashboards from multiple sites but not all the sites have been added to your
connection so far. Use the **Secondary Sites** section to add an item for each individual site. Curator requires
a separate Connected App for each individual site!

> * The details of the Connected App show blank.

If you are updating a Trusted Ticket connection, cached data may cause display issues. Clear the backend cache and
reload the Connection page.  If this issue persists, please reach out to Curator support.

> * Trying to save my connection, I get an error saying
>   `A syntax error was detected in <some fields.yaml> .. No such file or directory`

Clear the cache from the backend and apply the changes again. Hit save and the connection should be updated.

> * My Dashboards load indefinitely when trying to access them in the frontend.

The browser may be storing outdated settings or old Tableau session data. If you can log in and access the Dashboard
using an Incognito Window, then your users will need to hard-refresh their browsers, or clear
site site cookies.
If not, this issue generally resolves itself after 24 hours, so it's helpful to consider upgrading to connected apps
just prior to the weekend.

> * When accessing the Dashboard in the frontend, I get a 401.

Follow the steps in the *My Dashboards load indefinitely* section to resolve.

> * After updating my dev environment, my prod environment stopped working

If both Curator environments (test/dev and production) connect to the same Tableau Server, switching between Trusted
Tickets and Connected Apps can cause cookie conflicts when migrating one instance after the other. To prevent issues:

* Test each environment in a separate browser or incognito window.
* Ensure users testing Connected Apps clear their cookies before switching to the production environment again.

If further issues persist, reach out to your friendly Curator support team.

> * A Dashboard from a secondary site fails with a 401002 Unauthorized Access error that references the secondary
>   site's credentials.

If a secondary site's Content URL is missing or does not match the site exactly, or if either of its PAT fields
(PAT name or PAT secret) is left blank, Curator silently falls back to the primary site's credentials when
generating the embed token. Tableau then rejects the request with a 401002 Unauthorized Access error because the
primary site's credentials are not valid for the secondary site. To resolve:

1. Confirm the secondary site's Content URL matches the value shown in Tableau exactly (case-sensitive, no trailing
   slashes).
2. Populate both the PAT name and PAT secret fields for the secondary site.
3. Save the connection.
4. Clear the Curator backend cache and reload the Connection page.

### Allowed Domains - additional configuration option on Tableau Server/Cloud

Connected Apps can be configured to allow embedding from a specified domain only. You can find more details on
Tableau's Connected Apps in their
[Knowledge Base](https://help.tableau.com/current/online/en-us/connected_apps_direct.htm).

## Tableau Default Authentication

Using Tableau Default Authentication for your Embed Authentication mechanism means that your users will either be
prompted with a Tableau login screen when accessing a Dashboard, or you need to configure your own SSO mechanism
(e.g. SAML, OAuth, Active Directory etc.) to enable seamless authentication.

For organizations that require an integrated authentication experience, we **strongly recommend** using
**Connected Apps** instead of relying on Tableau Default Authentication.

### Browser Security Behavior: OAuth Data Sources in Embedded Contexts

When a Tableau workbook uses an OAuth-authenticated data source (such as Databricks, Snowflake, or Google BigQuery),
some users may find the Dashboard stalls in an incomplete state, or in Safari may receive a downloaded file, rather
than loading data transparently. **This is not a defect in Curator or Tableau.** It is a consequence of how modern
browsers enforce cross-site security restrictions inside embedded iframes.

#### What happens

Curator loads Tableau inside an HTML `<iframe>`. When the workbook needs data from an OAuth-authenticated source,
Tableau contacts its internal `/auth/request_oauth` endpoint to exchange credentials. If the OAuth refresh token is
expired or has never been authorized, Tableau's session bootstrap returns a `BadOAuthCredentials` error and
responds with a redirect URL pointing to its re-authorization page, `embeddedVizAuthentication.html`.

This re-authorization page is loaded as a **nested cross-site iframe** served from Tableau's own backend cluster
hostname (e.g. `prod-useast-b.online.tableau.com`). This hostname is a third-party origin and the browser therefore applies
its cross-site restrictions to the nested iframe:

* **Firefox** with Enhanced Tracking Protection marks the nested iframe `Sec-Fetch-Storage-Access: none`,
  preventing it from reading or writing cookies or any other storage
* **Safari** with Intelligent Tracking Prevention applies the same restriction and may additionally trigger a file
  download of the OAuth token payload rather than passing it to the embed
* **Chrome and Edge** apply equivalent restrictions when third-party cookies are disabled

The result is that the OAuth re-authorization UI loads inside the nested iframe but cannot complete — it has no
storage access and cannot drive the user through the OAuth consent flow. The Dashboard remains stuck or shows a
sign-in prompt that cannot be resolved without leaving the embedded context. Tableau has confirmed this is expected
behavior in embedded contexts; the browser is the enforcing party, and there is no work-around implemented as of now.

#### Two distinct authentication layers are involved

Understanding which layer is affected helps avoid a common false fix:

* **Layer 1 — Curator to Tableau:** How Curator authenticates the end user to Tableau itself (Connected Apps,
  Tableau Default Authentication, or Trusted Tickets). Upgrading to Connected Apps addresses third-party cookie
  issues at this layer because Connected Apps use signed JWT embed tokens rather than cookie-dependent flows.
  Configuring a custom domain so that Curator and Tableau share the same registered domain also helps at this
  layer.
* **Layer 2 — Tableau to the OAuth data source:** Once Tableau loads, the workbook independently authenticates
  to its data source via the `embeddedVizAuthentication.html` flow described above. **Neither Connected Apps nor
  custom domain alignment address this layer** — the re-authorization page is always served from an internal
  Tableau hostname that cannot be made same-site with the Curator or Tableau embed domain.

#### Workarounds

Because the restriction is enforced by the browser's security model, no Curator configuration can eliminate it
entirely. The following options address the root cause at different levels:

* **Avoid OAuth for database authentication.** Where the data source supports it, use an alternative credential
  type (e.g. username and password, a service account, or Kerberos) for the Tableau data connection. This
  prevents the `/auth/request_oauth` flow from being triggered entirely, removing the condition that causes the
  browser restriction.
* **Pre-authorize OAuth credentials in Tableau Cloud directly.** Users must authorize their OAuth data source
  credentials in Tableau Cloud outside of any embedded context before loading the Dashboard in Curator. In
  Tableau Cloud, navigate to the workbook, open the data source connection, and complete the OAuth authorization
  flow. Once valid, non-expired OAuth refresh tokens are stored in Tableau Cloud for that user, the embedded
  Dashboard can load without triggering the re-authorization flow.

For background on third-party cookie restrictions and how to configure a user-facing notification, see
[Third Party Cookies](/site_administration/user_notifications/third_party_cookies).

## Trusted Tickets (Deprecated - End of Life in October 2025)

**IMPORTANT:** Trusted Tickets are deprecated and will be removed from Curator in October 2025. From that point,
Curator will no longer support issuing Trusted Tickets or using the associated JavaScript API.

For more information about Trusted Ticket authentication, please refer to our documentation article
[Creating Integrations: Tableau Connection - Trusted Authentication](/creating_integrations/tableau_connection/trusted_authentication).