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

适用于： Tableau Cloud, Tableau Server

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

重要信息：

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

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

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

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

已连接应用的关键组件

已连接应用的以下组件与外部应用程序中的 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 Server ，您必须已配置 EAS。此外，EAS 必须发送包含下表中列出的已注册声明和标头的有效 JSON Web 令牌 (JWT)。

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

值必须是：“tableau”

“exp”到期时间有效的 JWT 不得过期。JWT 的过期时间 (UTC) 必须在配置的最长有效期内。可以使用vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes命令配置最长有效期。
“jti”JWT IDJWT ID 声明为 JWT 提供唯一标识符，并且区分大小写。
“scp”范围

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

“tableau:views:embed”
“tableau:views:embed_authoring”（Tableau Server 2022.3 中新增）
“tableau:metrics:embed”（在 Tableau Server 2023.3 中已停用）
“tableau:ask_data:embed ”（Tableau Server 2023.1 中新增。将在 Tableau Server 2024.2 中已停用）

注意：

  • 值必须作为列表类型传递。
  • 对于 tableau:views:embed，范围遵循已在 Tableau Server 中配置的用户权限，并允许用户与嵌入视图中的工具进行交互（如果在原始视图中可用）。
  • 我们建议嵌入代码排除工具栏参数。有关详细信息，请参见下面的已知问题（仅限嵌入工作流）。

对于 REST API 授权工作流，请参见支持 JWT 授权的 REST API 方法。

对于使用 REST API 进行身份验证的元数据 API 工作流，唯一支持的范围是 tableau:content:read。

https://tableau.com/groups动态组成员身份仅适用于嵌入工作流。

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

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

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

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

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

关于站点级 EAS

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

有两种方法可以注册服务器范围的 EAS：使用 TSM Web UI 或使用 TSM CLI。

注册 EAS 后，建立的信任关系适用于 Tableau Server 上的所有站点。

选项 1：使用 TSM Web UI

  1. 以 Tableau Server 管理员身份登录到 Tableau 服务管理器 (TSM) Web UI。有关详细信息，请参见登录到 Tableau 服务管理器 Web UI。

  2. 执行以下操作之一：

    • 在 Tableau Server 2024.2 及更高版本中，导航到“用户身份和访问”页面 >“已连接应用”选项卡。

    • 在 Tableau Server 2023.3 及更低版本中，导航到“用户身份和访问”页面 >“授权服务器”选项卡。

  3. 执行以下操作之一：

    • 在 Tableau Server 2024.2 及更高版本中：

      1. 选中“启用已连接应用”复选框。

      2. 选择第二个单选按钮，即“允许已连接应用（在站点级别配置）和服务器范围的 OAuth 2.0 信任（在下面配置）”。

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

      4. 单击“保存未完成的更改”按钮。

    • 在 Tableau Server 2023.3 及更低版本中：

      1. 选中“嵌入内容启用 OAuth 访问权限”复选框。

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

      3. 单击“保存未完成的更改”按钮。

  4. 完成后，执行以下操作：

    1. 在浏览器的右上角，单击“未完成的更改”按钮。

    2. 在页面的右下角，单击“应用更改并重新启动”按钮以停止并重新启动 Tableau Server。

选项 2：使用 TSM CLI

  1. 在群集中的初始节点（安装了 TSM 的节点）上以管理员身份打开命令提示符。

  2. 运行以下命令：

    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

从 Tableau Server 2024.2 开始，您可以为站点注册一个或多个 EAS。在站点级别注册 EAS 后，建立的信任关系仅适用于站点。

注意：配置站点级 EAS 的先决条件是在 TSM 中启用已连接应用。

步骤 1：启用已连接应用

  1. 以 Tableau Server 管理员身份登录到 Tableau 服务管理器 (TSM) Web UI。有关详细信息，请参见登录到 Tableau 服务管理器 Web UI。

  2. 导航到“用户身份和访问”页面 >“已连接应用”选项卡。

  3. 选中“启用已连接应用”复选框。

  4. 执行以下操作之一：

    • 选中第一个单选按钮“允许已连接应用（在站点级别配置）”以仅在站点级别启用注册 EAS。

    • （默认）选中第二个单选按钮“允许已连接应用（在站点级别配置）和服务器范围的 OAuth 2.0 信任（在下面配置）”，以在站点级别和服务器范围内注册 EAS。如果选择此选项，请确保在站点级别指定的颁发者 URL 与服务器范围的颁发者 URL 不同。

  5. 单击“保存未完成的更改”按钮。

  6. 完成后，执行以下操作：

    1. 在浏览器的右上角，单击“未完成的更改”按钮。

    2. 在页面的右下角，单击“应用更改并重新启动”按钮以停止并重新启动 Tableau Server。

步骤 2：注册您的 EAS

  1. 以 Tableau Server 管理员身份登录 Tableau Server。

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

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

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

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

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

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

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

  5. 创建已连接应用后，复制已连接应用的站点 ID。站点 ID 用于上面步骤 1 中描述的 JWT 的“aud”（受众）声明。

步骤 3：后续步骤

对于嵌入工作流

将Tableau Server配置为使用您的 EAS 后，您必须将嵌入代码添加到您的外部应用程序。确保在外部应用程序调用的 Web 组件中包含 EAS 生成的有效 JWT，如步骤 1 中所述。

有关嵌入 Tableau 内容的详细信息，请参见以下一项或两项：

注意：为了让用户在访问嵌入式内容时成功进行身份验证，浏览器必须配置为允许第三方 Cookie。

使用嵌入域白名单控制内容的嵌入位置

从 Tableau Server 2023.3 开始，您和您的用户可以使用 Tableau REST API 中的“更新站点嵌入设置”方法来控制是否可以不受限制地嵌入 Tableau 内容或限制为某些域。

默认情况下，unrestrictedEmbedding 站点嵌入设置设为 true 以允许不受限制的嵌入。或者，您和您的用户可以将廖设置设为 false，并使用 allowList 参数指定可以嵌入外部应用程序中的 Tableau 内容的域。

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

对于 REST API 授权工作流

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

对于元数据 API 工作流

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

管理已连接应用

动态组成员身份（仅限嵌入工作流）

从 Tableau Server 2024.2 开始，如果配置了已连接应用并且启用了功能的设置，则您可以通过外部应用程序发送的 JWT 中包含的自定义声明动态控制组成员身份。

配置完成后，在用户身份验证期间，外部应用程序会发送包含两个自定义组成员身份声明的 JWT：组 (https://tableau.com/groups) 和组名（例如，“Group1”和“Group2”）来将用户声明到其中。Tableau 验证 JWT，然后启用对组以及权限依赖于这些组的内容的访问。

有关详细信息，请参见使用断言的动态组成员身份。

已知问题（仅限嵌入工作流）

使用已连接应用时存在一些已知问题，这些问题将在未来版本中解决。

  • 工具栏功能：当嵌入式内容定义了工具栏参数时，并非所有工具栏功能都可以使用。为了解决此问题，我们建议您像下面的示例一样隐藏工具栏参数。

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

  • 已发布数据源：将不会显示设置为提示用户提供数据库凭据的已发布数据源。为了解决此问题，如果可能，我们建议数据源所有者改为嵌入他们的数据库凭据。

  • 多个站点上的嵌入视图：在 Tableau Server 2023.1 及更低版本中，在同一浏览器中切换不同站点上的视图会导致错误“1008：无法获取已连接应用的密文”。为了解决此问题，请升级到 Tableau Server 2023.3 或更高版本。

疑难解答

当嵌入内容无法在您的外部应用程序中显示或 Tableau REST API 授权失败时，您可以使用浏览器的开发人员工具来检查和识别可能与Tableau Server上启用的 EAS 功能相关联的错误代码。

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

错误代码摘要描述潜在的解决方案或解释
5SYSTEM_USER_NOT_FOUND找不到 Tableau 用户
若要解决此问题，请验证 JWT 中的“sub”（使用者）声明值为经过身份验证的 Tableau Server 的“用户名”。此值区分大小写。
16LOGIN_FAILED登录失败此错误通常是由 JWT 中的以下声明问题之一引起的：
67FEATURE_NOT_ENABLED不支持按需访问仅可通过获得许可的 Tableau Cloud 站点进行按需访问。
10081COULD_NOT_RETRIEVE_IDP_METADATA缺少 EAS 元数据端点若要解决此问题，请验证 EAS 是否配置正确并且调用了正确的颁发者。
10082AUTHORIZATION_SERVER_ISSUER_NOT_SPECIFIED缺少颁发者若要解决此问题，请验证是否调用了正确的颁发者。若要更改颁发者 URL，您可以使用vizportal.oauth.external_authorization_server.issuer命令。
10083BAD_JWTJWT 标头包含问题JWT 标头中缺少“kid”（密文 IDd）或“clientId”（颁发者）声明。若要解决此问题，请确保包含此信息。
10084JWT_PARSE_ERRORJWT 包含问题若要解决此问题，请验证以下各项：
  • JWT 中引用的“aud”（受众群体）值是否使用“tableau”值。此值区分大小写。
  • JWT 中包含“aud”（受众群体）和“sub”（使用者）。
10085COULD_NOT_FETCH_JWT_KEYSJWT 找不到密钥找不到密文。

若要解决此问题，请验证是否调用了正确的颁发者。若要更改颁发者 URL，您可以使用vizportal.oauth.external_authorization_server.issuer命令。

10087BLOCKLISTED_JWS_ALGORITHM_USED_TO_SIGNJWT 签名算法存在问题若要解决此问题，您可以移除签名算法。有关详细信息，请参见vizportal.oauth.external_authorization_server.blocklisted_jws_algorithms。
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）。
10096JWT_EXPIRATION_EXCEEDS_CONFIGURED_EXPIRATION_PERIOD “exp”（过期时间）超过了默认的最长有效期。若要解决此问题，请查看有效 JWT 所需的已注册声明(链接在新窗口中打开)并确保使用正确的值。若要更改最长有效期，可以使用vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes命令。
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。
10103JWT_MAX_SIZE_EXCEEDEDJWT 超出最大大小当 JWT 大小超过 8000 字节时，可能会发生此错误。为了解决此问题，请确保仅将必要的声明传递给 Tableau Server。
回到顶部
感谢您的反馈!您的反馈已成功提交。谢谢!