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

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

  • 透過已為 Tableau Cloud 站台設定的身分識別提供者 (IdP) 為使用者提供對內嵌在外部應用程式中的 Tableau 內容的單一登入 (SSO) 體驗
  • 使用 JSON Web 權杖 (JWT) 以程式控制方式代表使用者授權存取 Tableau REST API

在外部應用程式中載入內嵌的 Tableau 內容時,將使用標準 OAuth 流程。使用者成功登入 IdP 後,會自動登入 Tableau Cloud。按照下方描述的步驟將您的 EAS 註冊到 Tableau Cloud 站台。

重要資訊:

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

第 1 步:開始之前

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

宣告描述或所需值
"kid" (金鑰 ID)必需(在標頭中)。來自身分提供者的唯一金鑰識別碼。
iss」(簽發者)必需(在標頭或作為聲明)。唯一簽發者 HTTPS URI 會標識受信任的已連線應用程式及其簽署金鑰。
alg」(演算法)必需(在標頭中)。JWT 簽署演算法。javadoc.io 文件中 Class JWSAlgorithm(連結在新視窗開啟) 頁面中列出了支援的演算法名稱。
sub」(主題)經過驗證的 Tableau Cloud 使用者的使用者名稱(電子郵件地址)
aud」(對象)

值必須是:「tableau:<site_luid>

要獲取站台 LUID,可以使用 Tableau REST API 的登入方法或按照以下步驟複製站台 ID。注意:您必須先使用此處描述的過程註冊 EAS,然後才能複製站點 ID。

  1. 選取「設定」>已連線應用程式,然後選取「外部授權伺服器」已連線應用程式。
  2. 點一下「複製站點 ID」按鈕。

exp」(過期時間)

有效的 JWT 不得到期。JWT 的過期時間(UTC 時間)必須在最長有效期內,即 10 分鐘。

jti」(JWT ID)JWT ID 宣告為 JWT 提供唯一識別碼,並且區分大小寫。
scp」(範圍)

如果是嵌入工作流程,支援的值包括:

tableau:views:embed
tableau:views:embed_authoring
tableau:metrics:embed
tableau:ask_data:embed

附註:

  • 值必須作為清單類型傳遞。
  • 對於 tableau:views:embed,範圍尊重已在 Tableau Cloud 中設定的使用者權限,並允許使用者與內嵌檢視中的工具互動(若工具在原始檢視中可用)。
  • 建議內嵌程式碼排除工具列參數。有關更多資訊,請參閱下面的已知問題(僅限嵌入工作流程)

有關 REST API 授權工作流程,請參閱支援 JWT 授權的 REST API 方法

(使用者屬性)

僅用於內嵌工作流程

可以在 JWT 中包含使用者屬性。然後,在內嵌內容中使用使用者屬性函數時,Tableau 會檢查經過驗證的使用者的內容,並決定哪些資料可以在執行時顯示。

附註:

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

第 2 步:將 EAS 註冊到 Tableau Cloud

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

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

  1. 請作為站台管理員登入Tableau Cloud

  2. 從左窗格中,選取設定 > 已連線應用程式

  3. 按一下「新建已連線應用程式」按鈕下拉箭頭,並選取 OAuth 2.0 信任

  4. 在「建立已連線應用程式」對話方塊中,執行以下動作之一:
    1. 簽發者 URL文字方塊中,貼上 EAS 的簽發者 URL。

    2. 選取啟用已連線應用程式。出於安全考慮,預設情況下,已連線應用程式在建立時會設定為停用。

    3. 完成後,按一下建立按鈕。

  5. 建立連線的應用程式後,複製已連線應用程式的站台 ID。該站台 ID 用於上述第 1 步中描述的 JWT 的“aud”(受眾)聲明。

步驟 3:後續步驟

對於內嵌工作流程

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

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

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

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

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

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

有關詳情,請參閱以下內容(之一):

對於 REST API 授權工作流程

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

已知問題(僅限嵌入工作流程)

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

  • 工具列功能:內嵌內容定義工具列參數時,並非所有工具列功能都可以使用。要解決此問題,我們建議如下方範例一樣隱藏工具列參數。

    <tableau-viz id='tab-viz' src='https://online.tableau.com/t/<your_site>/...'
    	toolbar='hidden'>
    </tableau-viz>

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

疑難排解

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

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

錯誤程式碼彙總說明潛在的解決方案或解釋
5SYSTEM_USER_NOT_FOUND找不到 Tableau 使用者要解決此問題,請驗證 JWT 中的「sub」(主題)宣告值是經過驗證的 Tableau Cloud 使用者的使用者名稱(電子郵件地址)。此值區分大小寫。
16LOGIN_FAILED登入失敗此錯誤通常是由 JWT 中的以下宣告問題之一引起的:
  • exp」(到期時間)超過預設的最大有效期限。要解決此問題,請查看有效 JWT 所需的已註冊宣告(連結在新視窗開啟)並確保正確的值不超過 10 分鐘。
  • sub」(主題)正在呼叫未知使用者。要解決此問題,請驗證「sub」值是經過驗證的 Tableau Cloud 使用者的使用者名稱(電子郵件地址)。
142EXTERNAL_AUTHORIZATION_SERVER_NOT_FOUND未找到 EAS要解決此問題,請驗證呼叫的是正確的簽發者。
143EXTERNAL_AUTHORIZATION_SERVER_LIMIT_EXCEEDED超過 EAS 限制該站台已達到註冊的外部授權伺服器 (EAS) 的最大允許數量 (1)。
144INVALID_ISSUER_URL無效的簽發者 URL簽發者 URL 無效或 JWT 中缺少「iss」(簽發者)屬性。
149EAS_INVALID_JWKS_URI缺少 JWKS URIIdP 中繼資料中不存在 JWKS URI,或者 Tableau 中未設定 JWKS URI。要解決此問題,請設定有效的 JWKS URI。
150EAS_RETRIEVE_JWK_SOURCE_FAILED檢索密鑰源失敗要解決此問題,請驗證是否正確設定了 JWKS URI。
151EAS_RETRIEVE_METADATA_FAILED從 issuerUrl 檢索中繼資料失敗要解決此問題,請驗證是否正確設定了 JWKS URI。
10081COULD_NOT_RETRIEVE_IDP_METADATA缺少 EAS 元中繼資料端點要解決此問題,請驗證 EAS 配置正確並且呼叫正確的簽發者。
10082AUTHORIZATION_SERVER_ISSUER_NOT_SPECIFIED缺少簽發者要解決此問題,請驗證呼叫的是正確的簽發者。
10083BAD_JWTJWT 標頭含有問題JWT 標頭中缺少「kid」(密碼 ID)或「clientId」(簽發者)宣告。要解決此問題,請確保包含此資訊。
10084JWT_PARSE_ERRORJWT 含有問題要解決此問題,請驗證以下內容:
  • JWT 中引用的「aud」(受眾)值使用「tableau」值。此值區分大小寫。
  • JWT 中包含「aud」(受眾)和「sub」(主題)。
10085COULD_NOT_FETCH_JWT_KEYSJWT 找不到金鑰找不到密碼。

要解決此問題,請驗證呼叫的是正確的簽發者。

10087BLOCKLISTED_JWS_ALGORITHM_USED_TO_SIGNJWT 簽章演算法的問題要解決此問題,可以移除簽章演算法。
10088RSA_KEY_SIZE_INVALIDJWT 簽章要求問題要解決此問題,請使用 EAS 或 IdP 驗證 JWT 是否使用大小為 2048 的 RSA 金鑰進行簽章。
10091JTI_ALREADY_USED需要唯一的 JWTJWT 已經用於身份驗證過程。要解決此問題,EAS 或 IdP 必須產生新的 JWT。
10092NOT_IN_DOMAIN_ALLOW_LIST未指定內嵌內容的網域要解決此問題,請確保將 unrestrictedEmbedding 設定設定為 true,或者讓 domainAllowlist 參數包括使用 Tableau REST API 中更新站台的內嵌設定(連結在新視窗開啟)的方法內嵌 Tableau 內容的網域。
10094MISSING_REQUIRED_JTI缺少 JWT ID要解決此問題,請驗證 JWT 中包含「jti」(JWT ID)。
10095EXTERNAL_AUTHZ_SERVER_DISABLEDEAS 已停用註冊到站台的 EAS 的已連線應用程式已停用。
10096JWT_EXPIRATION_EXCEEDS_CONFIGURED_EXPIRATION_PERIOD exp」(到期時間)超過預設的最大有效期限。要解決此問題,請查看有效 JWT 所需的已註冊宣告(連結在新視窗開啟)並確保正確的值不超過 10 分鐘。
10097SCOPES_MALFORMED範圍宣告問題如果 JWT 中缺少「scp」(Scope) 宣告,或未作為清單類型傳遞,則會出現此錯誤。要解決此問題,請驗證 JWT 中 包含「scp」,並作為清單類型傳遞。有關 JWT 的疑難排解說明,請參閱 auth0 站台上的偵錯工具(連結在新視窗開啟)
10098JWT_UNSIGNED_OR_ENCRYPTEDJWT 未簽章或加密Tableau 不支援未簽章或加密的 JWT。
10099SCOPES_MISSING_IN_JWT缺少範圍宣告JWT 缺少所需的「scp」(範圍)宣告。要解決此問題,請驗證 JWT 中包含「scp」。有關 JWT 的疑難排解說明,請參閱 auth0 站台上的偵錯工具(連結在新視窗開啟)
10100JTI_PERSISTENCE_FAILED意外的 JWT ID 錯誤出現「jti」(JWT ID)意外錯誤。要解決此問題,必須產生具有新的「jti」的新 JWT。
感謝您的意見回饋!