使用 OAuth 2.0 信任設定已連線應用程式

作為 Tableau Cloud 站台管理員，您可以註冊一個或多個外部授權伺服器 (EAS)，以使用 OAuth 2.0 標準通訊協定在您的 Tableau Cloud 站台和 EAS 之間建立信任關係。

重要資訊：

本主題中的某些程序需要使用協力廠商軟體和服務進行設定。我們已盡最大努力驗證在 Tableau Server 上啟用 EAS 功能的程序。但是，第三方軟體和服務可能會發生變化，或者您的組織可能會有所不同。若遇到問題，權威設定細節和支援請參考第三方文件。
為了讓工作階段權杖有效，外部應用程式和託管外部應用程式的伺服器的時鐘必須設定為國際標準時間 (UTC)。若任一時鐘使用不同的標準，則已連線應用程式將不受信任。

Tableau 已連線應用程式如何使用 OAuth 2.0 信任

您的 Tableau Cloud 站台和外部應用程式之間的信任關係透過 JSON Web 權杖 (JWT) 標準中的驗證權杖建立和進行驗證。

在外部應用程式中載入內嵌 Tableau 內容時，會使用授權碼流程、OAuth 流程。使用者成功登入 IdP 後，會自動登入 Tableau Cloud。請按照下述步驟在您的 Tableau Cloud 站台上註冊 EAS。

已連線應用程式的關鍵元件

已連線應用程式的以下元件與外部應用程式中的 JWT 共同作業，以驗證使用者並顯示內嵌的內容。

外部授權伺服器 (EAS)：伺服器（通常是您的 IdP），可作為使用者和外部應用程式之間的介面。伺服器對使用者進行驗證，並授權其存取受保護的 Tableau 內容。
簽發者 URL：唯一識別 EAS 執行個體的 URL。

已連線應用程式的工作流程

內嵌工作流程

下圖說明了外部授權伺服器 (EAS)、外部應用程式（Web 伺服器和網頁）和 Tableau 已連線應用程式之間如何進行驗證。

使用者造訪網頁：使用者造訪網頁上的內嵌內容時，網頁會向外部應用程式傳送 GET 請求。
外部應用程式將請求重新導向到 EAS：外部應用程式透過重新導向到外部授權伺服器 (EAS) 的網頁進行回應。
使用者透過 EAS 進行驗證：使用者透過 EAS 進行驗證和授權。
EAS 透過授權碼回應網頁：EAS 透過授權碼回應頁面，並重新導向回網頁。
EAS 將授權碼轉換為 JWT：網頁呼叫 EAS 將授權碼轉換為 JWT，然後網頁將其放入內嵌內容的 URL 中。
網頁從 Tableau 請求內容：網頁載入 iFrame，並向 Tableau 傳送 GET 請求。
Tableau 驗證權杖：Tableau 使用簽章驗證 URL 中的 JWT，回應內容並遵守 JWT 中定義的內嵌範圍。

建立已連線應用程式

第 1 步：開始之前

要將 EAS 註冊到 Tableau Cloud 站台，必須已設定 EAS。此外，EAS 必須傳送包含下表中列出的已註冊宣告和標頭的有效 JSON Web 權杖 (JWT)。

宣告	名稱	描述或所需值
「`kid`」	主要識別碼	必需（在標頭中）。來自身分提供者的唯一金鑰識別碼。
「`iss`」	簽發者	必需（在標頭或作為聲明）。唯一簽發者 HTTPS URI 會標識受信任的已連線應用程式及其簽署金鑰。
「`alg`」	演算法	必需（在標頭中）。JWT 簽署演算法。javadoc.io 文件中 Class JWSAlgorithm(連結在新視窗開啟) 頁面中列出了支援的演算法名稱。
「`sub`」	主體	經過驗證的 Tableau Cloud 使用者的使用者名稱（電子郵件地址）。
「`aud`」	受眾	值必須是：「`tableau:<site_luid>`」要獲取站台 LUID，可以使用 Tableau REST API 的登入方法或按照以下步驟複製站台 ID。注意：您必須先使用此處描述的過程註冊 EAS，然後才能複製站點 ID。選取「設定」>已連線應用程式，然後選取「外部授權伺服器」已連線應用程式。點一下「複製站點 ID」按鈕。
「`exp`」	到期時間	有效的 JWT 不得到期。JWT 的過期時間（UTC 時間）必須在最長有效期內，即 10 分鐘。
「`jti`」	JWT ID	JWT ID 宣告為 JWT 提供唯一識別碼，並且區分大小寫。
「`scp`」	範圍	如果是嵌入工作流程，支援的值包括：「`tableau:views:embed`」「`tableau:views:embed_authoring`」「`tableau:metrics:embed`」（於 2023 年 10 月已淘汰（Tableau 2023.3））「`tableau:ask_data:embed`」在 Tableau Server 2023.1 中已新增將在附註：值必須作為清單類型傳遞。對於 `tableau:views:embed`，範圍尊重已在 Tableau Cloud 中設定的使用者權限，並允許使用者與內嵌檢視中的工具互動（若工具在原始檢視中可用）。建議內嵌程式碼排除工具列參數。有關更多資訊，請參閱下面的已知問題（僅限嵌入工作流程）。有關 REST API 授權工作流程，請參閱支援 JWT 授權的 REST API 方法。如果是使用 REST API 進行驗證的中繼資料 API 工作流程，唯一支援的範圍是 `tableau:content:read`。
`https://tableau.com/oda`	隨需存取 - 宣告（啟用功能）	僅用於內嵌工作流程。值必須是「`true`」並且必須指定一或多個 Tableau Cloud 群組（請參見下一列）。有關詳情，請參閱以下按需存取（僅限嵌入工作流程）區段。
`https://tableau.com/groups`	隨需存取 - 宣告（指定群組名稱）	僅用於內嵌工作流程。值必須與 Tableau Cloud 中的一或多個群組的名稱相符。有關詳情，請參閱以下按需存取（僅限嵌入工作流程）區段。
`https://tableau.com/groups`	動態群組成員身分	僅用於內嵌工作流程。值必須與 Tableau Cloud 中的一或多個群組的名稱相符。欲深入了解，請參閱以下動態群組成員資格（僅限內嵌工作流程）一節。
（使用者屬性）	（使用者屬性值）	僅用於內嵌工作流程。可以在 JWT 中包含使用者屬性。然後，在內嵌內容中使用使用者屬性函數時，Tableau 會檢查經過驗證的使用者的內容，並決定哪些資料可以在執行時顯示。附註：請查看內嵌 API v3(連結在新視窗開啟) 說明，以瞭解可能影響工作流程的已知問題。要讓使用者屬性可用，1) 必須啟用在驗證工作流程中控制使用者存取設定，並且 2) 內容作者必須建立使用者屬性函數(連結在新視窗開啟)。使用者屬性區分大小寫。

附註：上述 JWT 宣告記錄在網際網路工程任務推動小組 (IETF) 組織發佈的文件中已註冊宣告名稱(連結在新視窗開啟)區段。

第 2 步：將 EAS 註冊到 Tableau Cloud

透過將 EAS 註冊到 Tableau Cloud，可以在 EAS 和 Tableau Cloud 站台之間建立信任關係。這代表使用者存取內嵌在外部應用程式中的 Tableau 內容時，他們將被重新導向至使用 IdP 進行身份驗證。EAS 產生身份驗證權杖，該權杖會傳遞給 Tableau Cloud 進行驗證。在驗證信任關係後，授予使用者對內嵌內容的存取權限。

附註：某些 EAS 支援顯示同意對話方塊的選項，該對話方塊要求使用者核准應用程式存取 Tableau 內容。為確保使用者獲得最佳體驗，我們建議將 EAS 配置為代表使用者自動同意外部應用程式的請求。

關於站台層級 EAS

從 Tableau Server 2024.2 開始，可以設定站台層級 EAS。若要在站台層級註冊 EAS，必須在 Tableau Server 管理員 (TSM) 中啟用已連線應用程式。

作為站台管理員，登入 Tableau Cloud。
從左窗格中，選取設定 > 已連線應用程式。
按一下「新建已連線應用程式」按鈕下拉箭頭，並選取 OAuth 2.0 信任。
在「建立已連線應用程式」對話方塊中，執行以下動作：
1. 在「名稱」文字方塊中，輸入已連線應用程式的名稱。
2. 在簽發者 URL文字方塊中，貼上 EAS 的簽發者 URL。
3. 選取啟用已連線應用程式。出於安全考慮，預設情況下，已連線應用程式在建立時會設定為停用。
4. 完成後，按一下建立按鈕。
建立連線的應用程式後，複製已連線應用程式的站台 ID。該站台 ID 用於上述第 1 步中描述的 JWT 的“aud”（受眾）聲明。

步驟 3：後續步驟

對於內嵌工作流程

將 Tableau Cloud 站點設定為使用 EAS 後，必須將內嵌程式碼新增到外部應用程式中。確保在外部應用程式呼叫的 Web 元件中包含 EAS 產生的有效 JWT，如步驟 1 中所述。

有關內嵌 Tableau 內容的詳細資訊，請參閱以下一項或兩項：

內嵌指標，請參閱 Tableau 說明中的主題將指標內嵌到網頁中(連結在新視窗開啟)。（在 2023 年 10 月（Tableau 2023.3），Tableau 已淘汰內嵌指標功能。）
使用內嵌 API 第三版的 Tableau(連結在新視窗開啟) 內嵌 Tableau 檢視和指標。

附註：為了讓使用者在存取內嵌內容時成功進行驗證，必須將瀏覽器設定為允許協力廠商 Cookie。

使用內嵌網域允許清單控制內容的內嵌位置

從 2023 年 6 月 (Tableau 2023.2) 開始，您和您的使用者可以使用 Tableau REST API 中的「更新站台內嵌設定」方法來控制是否可以不受限制地內嵌 Tableau 內容或限制為某些網域。

預設情況下，unrestrictedEmbedding 內嵌的站台設定設定為 true 以允許不受限制的內嵌。或者，您和您的使用者可以將設定設定為 false 並使用以下命令指定可以內嵌外部應用程式中的 Tableau 內容網域 allowList 範圍。

有關詳情，請參閱以下內容（之一）：

在 Tableau REST API 說明中更新站台的內嵌設定(連結在新視窗開啟)
在 Tableau Embedding API v3 說明中用於內嵌的 Tableau 站台設定(連結在新視窗開啟)。

對於 REST API 授權工作流程

設定 JWT 後，必須將有效的 JWT 新增到 REST API 登入請求以進行授權存取。有關詳細資訊，請參閱已連線應用程式的存取範圍。

對於中繼資料 API 工作流程

設定 JWT 後，必須將有效的 JWT 新增至 REST API 登入請求。有關詳細資訊，請參閱已連線應用程式的存取範圍。

管理已連線應用程式

按需存取（僅限嵌入工作流程）

從 2023 年 10 月開始，如果您的站台獲得了內嵌分析(連結在新視窗開啟)基於使用模型的授權，可以使用隨需存取將對內嵌 Tableau 內容的存取權限擴展到更多使用者。透過隨需存取，您允許使用者與透過已連線應用程式進行驗證的內嵌 Tableau 內容進行互動，而無需在 Tableau Cloud 站台中設定這些使用者。按需存取使您無需在 Tableau Cloud 中新增與管理使用者即可支援存取嵌入內容。

隨需存取的工作原理

使用按需存取對嵌入式 Tableau 內容的存取由組級權限決定，組級權限要么繼承內容（例如，在專案級別），要么直接套用於內容。站台管理員、專案擁有者或領導者以及內容擁有者等使用者可以為內容分配組級權限。使用者存取隨需存取功能啟用的內嵌內容時，Tableau 會在顯示內容之前驗證 JWT 包含正確的群組成員資格聲明。

必要條件

除上述還必須滿足以下條件才能啟用內嵌內容的隨需存取：

站台已獲得內嵌分析(連結在新視窗開啟) 基於使用的模型授權
為群組啟用按需存取功能
為 Tableau 內容指定組權限
已建立 Tableau 連線的應用程式
連線的應用程式使用的 JWT 包括 https://tableau.com/oda 和 https://tableau.com/groups 宣告
將 Tableau 內容嵌入外部應用程式

滿足這些條件後，您的使用者就可以與隨需存取功能啟用的內嵌 Tableau 內容進行互動。

啟用按需存取功能

為了使群組具有按需存取能力，建立或編輯群組時必須勾選「允許按需存取」核取方塊。有關建立群組的更多資訊，請參閱建立群組並向其中新增使用者。

您也可以使用 Tableau REST API 啟用此功能。欲了解更多資訊，請參閱 Tableau REST API 說明中的建立群組(連結在新視窗開啟)與更新群組(連結在新視窗開啟)方法。

啟用按需存取後的功能

存取嵌入式 Tableau 內容的使用者可以在內容中檢視功能(連結在新視窗開啟)。無論選取的範本或可能為群組設定的自訂功能如何，使用者均有「檢視」功能（例如，具有「Viewer」角色的使用者將永遠無法下載資料來源，即使在具體資料來源中已明確說明授予該使用者此權限）。

監控按需存取

如果使用含有 Advanced Management(連結在新視窗開啟) 的 Tableau Cloud，可以使用活動記錄檔來監視隨需存取的使用情況。活動記錄檔中擷取隨需存取的事件包括但不限於存取檢視和登入。有關事件詳情，請參閱活動記錄檔站台事件類型參考。

限制

由於隨需存取工作流程使存取內嵌 Tableau 內容的某些使用者能夠匿名且對 Tableau Cloud 具有暫時性，因此透過隨需存取功能存取內嵌內容的使用者無法使用下列功能：

建立自訂檢視
使用內容的共用按鈕共用內容
訂閱資訊電子郵件快照的內容

附註： 從 2024 年 2 月 (Tableau 2024.1) 開始，Tableau REST API 請求可以以具有隨需存取權限的使用者身分傳出。

動態群組成員資格（僅限內嵌工作流程）

開始於 2024 年 6 月（Tableau 2024.2），如果設定已連線應用程式並啟用該功能的設置，可以透過外部應用程式傳送的 JWT 中包含的自訂宣告動態控制組成員資格。

設定後，在使用者驗證期間，外部應用程式會傳送包含兩個群組成員資格自訂宣告的 JWT： (https://tableau.com/groups）和群組名稱（例如，「Group1」和「Group2」）以將使用者斷言到其中。Tableau 驗證 JWT，然後允許存取群組及其權限依賴這些群組的內容。

有關詳情，請參閱使用聲明的動態群組成員資格。

已知問題（僅限嵌入工作流程）

使用已連線應用程式時存在一些已知問題，這些問題將在未來版本中解決。

工具列功能：內嵌內容定義工具列參數時，並非所有工具列功能都可以使用。要解決此問題，我們建議如下方範例一樣隱藏工具列參數。
```
<tableau-viz id='tab-viz' src='https://online.tableau.com/t/<your_site>/...'
	toolbar='hidden'>
</tableau-viz>
```

已發佈資料來源：將不會顯示設定為提示使用者提供資料庫認證的已發佈資料來源。要盡可能解決此問題，我們建議資料來源所有者改為內嵌齊資料庫認證。

疑難排解

內嵌內容無法在外部應用程式中顯示或 Tableau REST API 授權失敗時，可以使用瀏覽器的開發人員工具來檢查和識別可能與您的 Tableau Cloud 站台上啟用的 EAS 功能相關的錯誤代碼。

請參閱下表，查看錯誤代碼和潛在解決方案的說明。

錯誤程式碼	彙總	說明	潛在的解決方案或解釋
5	SYSTEM_USER_NOT_FOUND	找不到 Tableau 使用者	要解決此問題，請驗證 JWT 中的「`sub`」（主題）宣告值是經過驗證的 Tableau Cloud 使用者的使用者名稱（電子郵件地址）。此值區分大小寫。
16	LOGIN_FAILED	登入失敗	此錯誤通常是由 JWT 中的以下宣告問題之一引起的：「`exp`」（到期時間）超過預設的最大有效期限。要解決此問題，請查看有效 JWT 所需的已註冊宣告(連結在新視窗開啟)並確保正確的值不超過 10 分鐘。「`sub`」（主題）正在呼叫未知使用者。要解決此問題，請驗證「`sub`」值是經過驗證的 Tableau Cloud 使用者的使用者名稱（電子郵件地址）。
67	FEATURE_NOT_ENABLED	不支援隨需存取	僅可透過獲得授權的 Tableau Cloud 站台進行隨需存取。
142	EXTERNAL_AUTHORIZATION_SERVER_NOT_FOUND	未找到 EAS	要解決此問題，請驗證呼叫的是正確的簽發者。
143	EXTERNAL_AUTHORIZATION_SERVER_LIMIT_EXCEEDED	超過 EAS 限制	該站台已達到註冊的外部授權伺服器 (EAS) 的最大允許數量 (1)。
144	INVALID_ISSUER_URL	無效的簽發者 URL	簽發者 URL 無效或 JWT 中缺少「`iss`」（簽發者）屬性。
149	EAS_INVALID_JWKS_URI	缺少 JWKS URI	IdP 中繼資料中不存在 JWKS URI，或者 Tableau 中未設定 JWKS URI。要解決此問題，請設定有效的 JWKS URI。
150	EAS_RETRIEVE_JWK_SOURCE_FAILED	檢索密鑰源失敗	要解決此問題，請驗證是否正確設定了 JWKS URI。
151	EAS_RETRIEVE_METADATA_FAILED	從 issuerUrl 檢索中繼資料失敗	要解決此問題，請驗證是否正確設定了 JWKS URI。
10081	COULD_NOT_RETRIEVE_IDP_METADATA	缺少 EAS 元中繼資料端點	要解決此問題，請驗證 EAS 配置正確並且呼叫正確的簽發者。
10082	AUTHORIZATION_SERVER_ISSUER_NOT_SPECIFIED	缺少簽發者	要解決此問題，請驗證呼叫的是正確的簽發者。
10083	BAD_JWT	JWT 標頭含有問題	JWT 標頭中缺少「`kid`」（密碼 ID）或「`clientId`」（簽發者）宣告。要解決此問題，請確保包含此資訊。
10084	JWT_PARSE_ERROR	JWT 含有問題	要解決此問題，請驗證以下內容： JWT 中引用的「`aud`」（受眾）值使用「tableau」值。此值區分大小寫。 JWT 中包含「`aud`」（受眾）和「`sub`」（主題）。
10085	COULD_NOT_FETCH_JWT_KEYS	JWT 找不到金鑰	找不到密碼。要解決此問題，請驗證呼叫的是正確的簽發者。
10087	BLOCKLISTED_JWS_ALGORITHM_USED_TO_SIGN	JWT 簽章演算法的問題	要解決此問題，可以移除簽章演算法。
10088	RSA_KEY_SIZE_INVALID	JWT 簽章要求問題	要解決此問題，請使用 EAS 或 IdP 驗證 JWT 是否使用大小為 2048 的 RSA 金鑰進行簽章。
10091	JTI_ALREADY_USED	需要唯一的 JWT	JWT 已經用於身份驗證過程。要解決此問題，EAS 或 IdP 必須產生新的 JWT。
10092	NOT_IN_DOMAIN_ALLOW_LIST	未指定內嵌內容的網域	要解決此問題，請確保將 `unrestrictedEmbedding` 設定設定為 `true`，或者讓 `domainAllowlist` 參數包括使用 Tableau REST API 中更新站台的內嵌設定(連結在新視窗開啟)的方法內嵌 Tableau 內容的網域。
10094	MISSING_REQUIRED_JTI	缺少 JWT ID	要解決此問題，請驗證 JWT 中包含「`jti`」（JWT ID）。
10095	EXTERNAL_AUTHZ_SERVER_DISABLED	EAS 已停用	註冊到站台的 EAS 的已連線應用程式已停用。
10096	JWT_EXPIRATION_EXCEEDS_CONFIGURED_EXPIRATION_PERIOD		「`exp`」（到期時間）超過預設的最大有效期限。要解決此問題，請查看有效 JWT 所需的已註冊宣告(連結在新視窗開啟)並確保正確的值不超過 10 分鐘。
10097	SCOPES_MALFORMED	範圍宣告問題	如果 JWT 中缺少「`scp`」(Scope) 宣告，或未作為清單類型傳遞，則會出現此錯誤。要解決此問題，請驗證 JWT 中包含「`scp`」，並作為清單類型傳遞。有關 JWT 的疑難排解說明，請參閱 auth0 站台上的偵錯工具(連結在新視窗開啟)。
10098	JWT_UNSIGNED_OR_ENCRYPTED	JWT 未簽章或加密	Tableau 不支援未簽章或加密的 JWT。
10099	SCOPES_MISSING_IN_JWT	缺少範圍宣告	JWT 缺少所需的「`scp`」（範圍）宣告。要解決此問題，請驗證 JWT 中包含「`scp`」。有關 JWT 的疑難排解說明，請參閱 auth0 站台上的偵錯工具(連結在新視窗開啟)。
10100	JTI_PERSISTENCE_FAILED	意外的 JWT ID 錯誤	出現「`jti`」（JWT 識別碼）意外錯誤。要解決此問題，必須產生具有新的「`jti`」的新 JWT。
10101	EPHEMERAL_USER_LOGIN_FAILED_SITE_NOT_UBP_ENABLED	不支援隨需存取	該站台未獲得啟用隨需存取所需的「內嵌分析」基於使用模型的授權。有關詳情，請參閱暸解授權模式。
10102	EPHEMERAL_USER_NOT_SUPPORTED	啟用 iframe-auth 屬性時不支援隨需存取	啟用 iframe-auth 屬性時可能會出現此錯誤。要解決此問題，請驗證是否使用 Tableau 內嵌 API 版本 3.6 或更高版本。
10103	JWT_MAX_SIZE_EXCEEDED	JWT 超出最大大小	當 JWT 大小超過 8000 位元時，可能會發生此錯誤。要解決此問題，請確保僅將必要的宣告傳遞給 Tableau Cloud。

返回頂端

Tableau Cloud 說明