使用 OAuth 2.0 信任配置已连接应用

适用于： Tableau Cloud, Tableau Server

作为 Tableau Cloud 站点管理员，您可以使用 OAuth 2.0 标准协议注册一个或多个外部授权服务器 (EAS) 以在 Tableau Cloud 站点和 EAS 之间建立信任关系。

重要信息：

  • 本主题中的某些过程需要使用第三方软件和服务进行配置。我们已尽最大努力验证用于在 Tableau Cloud 上启用 EAS 功能的过程。但是，第三方软件和服务可能会发生变化，或者您的组织可能会有所不同。如果遇到问题，请参考第三方文档以获得权威的配置详细信息和支持。
  • 为了使会话令牌有效，外部应用程序和托管外部应用程序的服务器的时钟必须设置为协调世界时 (UTC)。如果任何一个时钟使用不同的标准，连接的应用软件将不被信任。

Tableau 已连接应用如何与 OAuth 2.0 信任配合使用

Tableau Cloud 站点和外部应用程序之间的信任关系通过 JSON Web Token (JWT) 标准中的身份验证令牌建立和验证。

在外部应用程序中加载嵌入的 Tableau 内容时，将使用授权代码流程 OAuth 流程。用户成功登录到其 IdP 后，将会自动登录到 Tableau Cloud。按照下面描述的步骤将您的 EAS 注册到 Tableau Cloud 站点。

已连接应用的关键组件

已连接应用的以下组件与外部应用程序中的 JWT 一起工作，以验证用户身份并显示嵌入的内容。

  • 外部授权服务器 (EAS)：该服务器（通常是您的 IdP）充当用户和外部应用程序之间的接口。服务器对用户进行身份验证并授权其访问受保护的 Tableau 内容。

  • 颁发者 URL：唯一标识 EAS 实例的 URL。

已连接应用工作流程

嵌入工作流

下图说明了外部授权服务器 (EAS)、外部应用程序（Web 服务器及网页）和 Tableau 已连接应用之间的身份验证工作方式。

  1. 用户访问网页：当用户访问网页上的嵌入内容时，网页会向外部应用程序发送 GET 请求。

  2. 外部应用程序将请求重定向到 EAS：外部应用程序通过重定向到外部授权服务器 (EAS)的网页进行响应。

  3. 用户使用 EAS 进行身份验证：用户使用 EAS 进行身份验证和授权。

  4. EAS 使用授权代码响应网页： EAS 使用授权码响应页面并重定向回网页。

  5. EAS 将授权代码转换为 JWT：网页调用 EAS 将授权代码转换为 JWT，网页将 JWT 放入嵌入式内容的 URL 中。

  6. 网页向 Tableau 请求内容：网页加载 iFrame 并向 Tableau 发送 GET 请求。

  7. Tableau 验证令牌：Tableau 使用签名验证 URL 中的 JWT，使用内容进行响应，并尊从 JWT 中定义的嵌入范围。

创建已连接应用

步骤 1：开始之前

若要将 EAS 注册到您的 Tableau Cloud 站点，您必须已配置 EAS。此外，EAS 必须发送包含下表中列出的已注册声明和标头的有效 JSON Web 令牌 (JWT)。

声明名称描述或必需值
“kid”键 ID必需（在标题中）。来自身份提供程序的唯一密钥标识符。
“iss”颁发者必需（在标题中或作为声明）。标识受信任的已连接应用及其签名密钥的唯一颁发者 URI（在 HTTPS 中）。
“alg”算法必需（在标题中）。JWT 签名算法。javadoc.io 文档的 Class JWSAlgorithm(链接在新窗口中打开) 页面中列出了支持算法名称。
“sub”使用者经过身份验证的 Tableau Cloud 用户的用户名（电子邮件地址）。
“aud”受众

值必须是：“tableau:<site_luid>”

若要获得站点 LUID，您可以使用 Tableau REST API 的登录方法或按照下面的步骤复制站点 ID。注意：在复制站点 ID 之前，您必须使用此处描述的过程注册一个 EAS。

  1. 选择“设置”>“已连接应用”，然后选择“外部授权服务器”已连接应用。

  2. 单击“复制站点 ID”按钮。

“exp”到期时间

有效的 JWT 不得过期。JWT 的过期时间 (UTC) 必须在最长有效期（即 10 分钟）内。

“jti”JWT IDJWT ID 声明为 JWT 提供唯一标识符，并且区分大小写。
“scp”范围

对于嵌入工作流，支持的值包括：

“tableau:views:embed”
“tableau:views:embed_authoring”
“tableau:metrics:embed”（于 2023 年 10 月已停用 (Tableau 2023.3)）
“tableau:ask_data:embed ”（于 2024 年 2 月已停用 (Tableau 2024.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 中的一个或多个组的名称匹配。有关详细信息，请参见下面的按需访问（仅限嵌入工作流程）部分。

动态组成员身份仅适用于嵌入工作流。

值必须与 Tableau Cloud 中的一个或多个组的名称匹配。有关详细信息，请参见下面的动态组成员身份（仅限嵌入工作流）部分。

（用户属性）（用户属性值）

仅适用于嵌入工作流。

您可以在 JWT 中包含用户属性。然后，当在嵌入内容中使用用户属性函数时，Tableau 会检查经过身份验证的用户的上下文并确定哪些数据可以在运行时显示。

注意：

注意：上述 JWT 声明记录在 Internet 工程任务组 (IETF) 组织分发的文档中的注册声明名称(链接在新窗口中打开)部分。

步骤 2：向 Tableau Cloud 注册您的 EAS

通过向 Tableau Cloud 注册您的 EAS，您可以在 EAS 和 您的Tableau Cloud站点之间建立信任关系。这意味着当用户访问嵌入在您的外部应用程序中的 Tableau 内容时，他们将被重定向以使用 IdP 进行身份验证。EAS 生成身份验证令牌，该令牌会传递给 Tableau Cloud 进行验证。在验证信任关系后，授予用户对嵌入内容的访问权限。

注意：某些 EAS 支持显示同意对话框的选项，该对话框要求用户批准应用程序访问 Tableau 内容。为确保您的用户获得最佳体验，我们建议您将 EAS 配置为代表用户自动同意外部应用程序的请求。

关于站点级 EAS

从 Tableau Server 2024.2 开始，您可以配置站点级 EAS。若要在站点级别注册 EAS，必须在 Tableau Server Manager (TSM) 中启用已连接应用。

  1. 以站点管理员身份登录 Tableau Cloud。

  2. 从左侧窗格中，选择“设置”>“已连接应用”。

  3. 单击“新建已连接应用”按钮下拉箭头，并选择“OAuth 2.0 信任”。

  4. 在“创建已连接应用”对话框中，执行以下操作：

    1. 在“名称”文本框中，输入已连接应用的名称。

    2. 在“颁发者 URL”文本框中，粘贴 EAS 的颁发者 URL。

    3. 选择“启用已连接应用”。出于安全考虑，已连接应用在创建时默认设置为禁用。

    4. 完成后，单击“创建”按钮。

  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，并使用 allowList 参数指定可以嵌入外部应用程序中的 Tableau 内容的域。

有关详细信息，请参阅以下一项或两项：

对于 REST API 授权工作流

配置 JWT 后，您必须将有效的 JWT 添加到 REST API 登录请求以进行授权访问。有关详细信息，请参见已连接应用的访问范围。

对于元数据 API 工作流

配置 JWT 后，您必须将有效的 JWT 添加到 REST API 登录请求。有关详细信息，请参见已连接应用的访问范围。

管理已连接应用

按需访问（仅限嵌入工作流程）

从 2023 年 10 月开始，如果您的站点获得基于嵌入式分析(链接在新窗口中打开)使用模式的许可，您可以使用按需访问将对嵌入式 Tableau 内容的访问扩展到更多用户。通过按需访问，您允许用户与通过已连接应用进行身份验证的嵌入式 Tableau 内容进行交互，而无需在 Tableau Cloud 站点中配置这些用户。按需访问使您无需在 Tableau Cloud 中添加和管理用户即可支持对嵌入式内容的访问。

按需访问的工作原理

使用按需访问对嵌入式 Tableau 内容的访问由组级权限决定，组级权限要么由内容继承（例如，在项目级别），要么直接应用于内容。站点管理员、项目所有者或主管以及内容所有者等用户可以为内容分配组级权限。当用户访问通过按需访问功能启用的嵌入式内容时，Tableau 会在显示内容之前验证 JWT 是否包含正确的组成员身份声明。

先决条件

必须满足以下条件才能启用嵌入式内容的按需访问：

  1. 站点已获得基于嵌入式分析(链接在新窗口中打开)使用模型的许可
  2. 为组启用按需访问能力
  3. 为 Tableau 内容指定组权限
  4. Tableau 已连接应用已创建
  5. 已连接应用使用的 JWT 包括 https://tableau.com/oda 和 https://tableau.com/groups 声明
  6. Tableau 内容嵌入在外部应用程序中

当满足这些条件时，您的用户可以与通过按需访问功能实现的嵌入式 Tableau 内容进行交互。

启用按需访问能力

若要为组启用按需访问能力，在创建或编辑组时，必须选中“允许按需访问”复选框。有关创建组的详细信息，请参见创建组并向其中添加用户。

可以使用 Tableau REST API 执行启用此能力。有关详细信息，请参见 Tableau REST API 帮助中的 Create Group（创建组）(链接在新窗口中打开)和 Update Group（更新组）(链接在新窗口中打开)方法。

启用按需访问时的能力

访问嵌入式 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 功能相关联的错误代码。

请参阅下表以查看错误代码和潜在解决方案的描述。

错误代码摘要描述潜在的解决方案或解释
5SYSTEM_USER_NOT_FOUND找不到 Tableau 用户若要解决此问题，请验证 JWT 中的“sub”（使用者）声明值是否为经过身份验证的 Tableau Cloud 用户的用户名（电子邮件地址）。此值区分大小写。
16LOGIN_FAILED登录失败此错误通常是由 JWT 中的以下声明问题之一引起的：
  • “exp”（过期时间）超过了默认的最长有效期。若要解决此问题，请查看有效 JWT 所需的已注册声明(链接在新窗口中打开)并确保正确的值不超过 10 分钟。
  • “sub”（使用者）正在调用未知用户。若要解决此问题，请验证“sub”值是否为经过身份验证的 Tableau Cloud 用户的用户名（电子邮件地址）。
67FEATURE_NOT_ENABLED不支持按需访问仅可通过获得许可的 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”（密文 IDd）或“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范围声明的问题当“scp”（范围）声明在 JWT 中缺失或未作为列表类型传递时，可能会发生此错误。若要解决此问题，请验证“scp”包含在 JWT 中并作为列表类型传递。有关 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。
10101EPHEMERAL_USER_LOGIN_FAILED_SITE_NOT_UBP_ENABLED不支持按需访问该站点未获得启用按需访问所需的基于嵌入式分析使用情况的模型。有关详细信息，请参见了解许可证模式。
10102EPHEMERAL_USER_NOT_SUPPORTED启用 iframe-auth 属性时不支持按需访问启用 iframe-auth 属性时可能会出现此错误。为了解决此问题，请验证是否正在使用 Tableau Embedding API 版本 3.6 或更高版本。
10103JWT_MAX_SIZE_EXCEEDEDJWT 超出最大大小当 JWT 大小超过 8000 字节时，可能会发生此错误。为了解决此问题，请确保仅将必要的声明传递给 Tableau Cloud。
回到顶部
感谢您的反馈!您的反馈已成功提交。谢谢!