Tableau Cloud 帮助

从 2022 年 1 月初始开始， Tableau 已连接应用通过促进您的 Tableau Cloud 站点与外部应用程序之间建立明确的信任关系，实现无缝且安全的身份验证体验：

• 限制对可以嵌入的内容以及该内容可以嵌入的位置的访问
• 为用户提供使用单点登录 (SSO) 访问嵌入内容的能力，而不必与身份提供程序 (IdP) 集成
• 为用户提供直接从外部应用程序进行身份验证的能力
• 使用 JSON Web 令牌 (JWT) 以编程方式代表用户授权访问 Tableau REST API（从 Tableau Cloud 开始为元数据 API）

已连接应用的工作方式

您的 Tableau Cloud 站点和外部应用程序之间的信任关系是通过 JSON 网络令牌 (JWT) 标准中的身份验证令牌建立和验证的，该令牌使用由 Tableau 已连接应用提供并由您的自定义应用程序签名的共享密文。

已连接应用的关键组件

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

• 密文：密文是 Tableau 和您的外部应用程序共享的密钥。它们在形成 JWT 的签名中使用。使用已连接应用进行嵌入身份验证或 REST API 授权时需要密文。密文可以在已连接应用中创建，不会过期，并且在删除之前一直有效。
• 域允许列表（仅限嵌入工作流）：您可以在每个已连接应用中指定允许的域的列表。通过已连接应用嵌入的 Tableau 内容仅允许在指定的域下使用。这有助于确保内容在您的企业保护和批准的域下公开。
• 访问级别（仅限嵌入工作流）：您可以通过将已连接应用与一个项目或所有项目相关联来指定可通过已连接应用嵌入哪些内容。如果指定一个项目，则只能通过已连接应用嵌入所选项目中的内容。如果要指定多个项目，则必须使用 Tableau REST API。

注意：为了使会话令牌有效，外部应用程序和托管外部应用程序的服务器的时钟必须设置为协调世界时 (UTC)。如果任何一个时钟使用不同的标准，连接的应用软件将不被信任。

已连接应用工作流程

嵌入工作流

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

1. 用户访问网页：当用户访问网页上的嵌入内容时，网页会向您的外部应用程序发送 GET 请求以检索该网页上的 HTML。
2. 外部应用程序构建身份验证令牌：外部应用程序构建 JWT，其中包含来自已连接应用的密文（有关其他 JWT 要求，请参见下面的“步骤 3”）以及用户对嵌入内容的访问范围。该密文由外部应用程序签名，用于后续步骤中的信任关系验证。
3. 外部应用程序使用身份验证令牌响应：外部应用程序使用网页调用的嵌入内容 URL 中的 JWT 响应页面。
4. 网页从 Tableau 请求内容：尝试加载嵌入内容时，网页调用嵌入内容的 URL，后者向 Tableau 发送 GET 请求。
5. Tableau 验证令牌： Tableau 接收 JWT 并通过识别 JWT 中使用的已连接应用和共享密文来验证与外部应用程序的信任关系。然后 Tableau 为用户创建一个会话。会话不仅遵守 JWT 中定义的嵌入范围，还遵守已连接应用中指定的限制，包括允许的域和允许的项目。
6. Tableau 根据受限制的嵌入上下文返回内容：嵌入的内容仅在页面位于允许的域下并且内容发布到允许的项目（如果适用）时加载。经过身份验证的用户只能通过 JWT 中定义的范围与嵌入的内容进行交互。

创建已连接应用

步骤 1：创建已连接应用

从 Tableau Cloud 的“设置”页面创建已连接应用。

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

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

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

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

   1. 对于REST API 授权工作流（包括使用 REST API 进行身份验证的元数据 API 工作流），在“已连接应用名称”文本框中，输入已连接应用的名称，然后单击“创建”按钮。

      注意：在为 REST API 和元数据 API 授权配置已连接应用时，您可以忽略“访问级别”和“域允许列表”。

   2. 对于嵌入工作流，请执行以下操作：

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

      2. 从“应用于”下拉菜单中，选择“所有项目”或“仅一个项目”来控制可以嵌入哪些视图或指标。如果您选择“仅一个项目”选项，请选择要确定范围的特定项目。有关这两个选项的详细信息，请参见访问级别（仅限嵌入工作流）。

         注意： 

         • 在 2023 年 10 月版 (Tableau 2023.3) 中，Tableau 停用了嵌入指标的功能。
         • 在 2024 年 2 月 (Tableau 2024.1) 中，您可以使用 Tableau REST API 指定多个项目。有关详细信息，请参见 REST API 帮助中的 Create Connected App（创建已连接应用）(链接在新窗口中打开)和 Update Connected App（更新已连接应用）(链接在新窗口中打开)方法。

      3. 在“域允许列表”中，使用下面的域格式设置中描述的规则指定域，以控制可以嵌入视图或指标的位置。

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

         

5. 在已连接应用的名称旁边，单击操作菜单并选择“启用”。出于安全考虑，已连接应用在创建时默认设置为禁用。

   

6. 记下已连接应用的 ID（也称为客户端 Id），以在下面的“步骤 3”中使用。

   

步骤 2：生成密文

您可以为每个已连接应用生成总共两个密文。第二个密文可用于密文轮换目的，以帮助防止密文泄露时出现问题。

1. 在您在“步骤 1”中创建的已连接应用的详细信息页面上，单击“生成新密文”按钮。

2. 记下要在下面的“步骤 3”中使用的密文 ID 和密文值。

   

步骤 3：配置 JWT

生成密文后，您希望使外部应用程序能够发送有效的 JWT。JWT 是用于在两方之间安全传输信息的标准。JWT 由您的外部应用程序签名，以安全地将信息发送到 Tableau Cloud。JWT 引用已连接应用、为其生成会话的用户以及用户应具有的访问级别。

有效的 JWT 包括以下信息：

• 来自“步骤 1”的已连接应用 ID（也称为客户端 ID）

• “步骤 2”中生成的密文 ID 和密文值

• 注册的声明和标题：

  声明	名称	描述或必需值
  “kid”	密文 ID	必需（在标题中）。已连接应用的密文密钥标识符。
  “iss”	颁发者	必需（在标题中）。标识受信任的已连接应用及其签名密钥的唯一颁发者 URI。
  “alg”	算法	必需（在标题中）。JWT 签名算法。仅支持 HS256。
  “sub”	使用者	经过身份验证的 Tableau Cloud 用户的用户名（电子邮件地址）。
  “aud”	受众	值必须是：“tableau”。
  “exp”	到期时间	有效的 JWT 不得过期。JWT 的过期时间 (UTC) 必须在最长有效期（即 10 分钟）内。
  “jti”	JWT ID	要求采用声明形式。JWT ID 声明为 JWT 提供唯一标识符，并且区分大小写。
  “scp” 重要：不要使用“scope”。	范围	对于嵌入工作流，支持的值包括： “tableau:views:embed” “tableau:views:embed_authoring” “tableau:metrics:embed”（于 2023 年 10 月停用 (Tableau 2023.3)） “tableau:ask_data:embed”（于 2024 年 3 月停用 (Tableau 2024.1) 中停用） 注意： 值必须作为列表类型传递。 对于 tableau:views:embed 和 tableau:views:embed_authoring，范围遵循已在 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 中的一个或多个组的名称匹配。有关详细信息，请参见下面的按需访问（仅限嵌入工作流程）部分。
  （用户属性）	（用户属性值）	仅适用于嵌入工作流。 您可以在 JWT 中包含用户属性。然后，当在嵌入内容中使用用户属性函数时，Tableau 会检查经过身份验证的用户的上下文并确定哪些数据可以在运行时显示。 注意： 查看嵌入 API v3(链接在新窗口中打开) 帮助以了解可能影响您的工作流程的已知问题。 为了使用户属性起作用，1) 您必须启用“在身份验证工作流程中控制用户访问”设置，并且 2) 内容作者必须创建一个用户属性函数(链接在新窗口中打开)。 用户属性区分大小写。

示例 JWT

以下是 Java 和 Python 语言的示例 JWT。Java 和 Python 示例分别使用 nimbus-jose-jwt 库和 PyJWT 库。

Java

import com.nimbusds.jose.*;
import com.nimbusds.jose.crypto.*;
import com.nimbusds.jwt.*;

import java.util.*;

...

String secret = "secretvalue";
	String kid = "connectedAppSecretId";
	String clientId = "connectedAppClientId";
	List<String> scopes = new
ArrayList<>(Arrays.asList("tableau:views:embed"));
	String username = "user@domain.com";
	JWSSigner signer = new MACSigner(secret);
	JWSHeader header = new
JWSHeader.Builder(JWSAlgorithm.HS256).keyID(kid).customParam("iss", clientId).build();
	JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
		.issuer(clientId)
		.expirationTime(new Date(new Date().getTime() + 60 * 1000)) //expires in 1 minute
		.jwtID(UUID.randomUUID().toString())
		.audience("tableau")
		.subject("username")
		.claim("scp", scopes)
		.claim("https://tableau.com/oda", "true")
		.claim("https://tableau.com/groups", "Contractors", "Team C")
		.claim("Region", "East")
		.build();
	SignedJWT signedJWT = new SignedJWT(header, claimsSet);
	signedJWT.sign(signer);
	model.addAttribute("token", signedJWT.serialize());

Python

import jwt

token = jwt.encode(
	{
		"iss": connectedAppClientId,
		"exp": datetime.datetime.utcnow() + datetime.timedelta(minutes=5),
		"jti": str(uuid.uuid4()),
		"aud": "tableau",
		"sub": user,
		"scp": ["tableau:views:embed", "tableau:metrics:embed"],
		"https://tableau.com/oda":"true",
		"https://tableau.com/groups": ["Contractors", "Team C"],
		"Region": "East"
	},
		connectedAppSecretKey,
		algorithm = "HS256",
		headers = {
		'kid': connectedAppSecretId,
		'iss': connectedAppClientId
        }
  )

配置 JWT 后，当代码由您的外部应用程序运行时，它将生成一个令牌。

步骤 4：后续步骤

管理已连接应用

您可以在“已连接应用”页面上管理站点的所有已连接应用。您可以执行诸如以下任务：创建、删除和禁用已连接应用；以及在现有密文已泄露的情况下撤销或生成新密文。

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

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

3. 选中您要管理的已连接应用旁边的复选框，然后执行以下一项或多项操作：

   • 根据您组织的安全策略指定的轮换时间线生成新密文。若要生成额外的密文，请单击已连接应用的名称，然后单击“生成新密文”按钮。一个已连接应用最多可以有两个密文。这两个密文可以同时处于活动状态，不会过期，并且在被删除之前一直有效。

   • 通过单击已连接应用的名称查看已连接应用的创建时间、其 ID、项目和域范围及其密文，查看已连接应用详细信息。

   • 更改项目范围或域，在“操作”菜单中，选择“编辑”。进行更改并单击“更新”。

     注意：如果您更改项目或域范围，并且新项目或新域中不存在嵌入的内容，则嵌入的视图或指标无法显示，用户在访问嵌入的内容时会看到错误。

   • 通过单击已连接应用的名称来删除密文。在已连接应用页面上，单击密文旁边的“操作”并选择“删除”。在确认对话框中，再次选择“删除”。

     注意：如果外部应用程序正在使用已连接应用的密文，则删除密文后无法显示嵌入的视图或指标。有关详细信息，请参见下面的禁用或删除已连接应用或删除密文的影响。

   • 禁用已连接应用，在“操作”菜单中，选择“禁用”。如果外部应用程序正在使用已连接应用，则在禁用已连接应用后无法显示嵌入的视图或指标。有关详细信息，请参见下面的禁用或删除已连接应用或删除密文的影响。

   

禁用或删除已连接应用或删除密文的影响

若要通过已连接应用向您的用户显示嵌入式内容或启用 REST API 访问权限，必须启用已连接应用并生成其密文。如果已连接应用正在您的外部应用程序中使用并且被禁用或删除，或者其密文被删除或替换，则用户将收到 403 错误。

为了避免此问题，请确保启用已连接应用并且 JWT 使用正确的密文 ID 和值。

域允许列表规则（仅限嵌入工作流）

已连接应用的域允许列表使您能够将对嵌入式 Tableau 内容的访问限制为所有域或某些域；或者排除某些域或阻止所有域。

域选项

在配置已连接应用的域允许列表时，您可以选择以下两个选项之一：

• 所有域：作为默认选项，此选项启用对嵌入内容的无限制访问。
• 仅特定域：此选项使您能够缩小对嵌入内容的访问范围。如果使用此选项，请遵循下面的域格式设置部分指定的格式设置规则。

域格式设置

在域允许列表文本框中，您可以使用下面的格式示例输入一个或多个域。

注意：在 Tableau REST API 中使用已连接应用方法(链接在新窗口中打开)时，域格式设置规则也适用。

以下是一些基于常见场景的格式设置示例：

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

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

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

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

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

• 嵌入式仪表板中的“数据问答”(Ask Data) 功能对象：不会加载嵌入式仪表板中的“数据问答”(Ask Data) 功能对象。（在 2024 年 2 月 (Tableau 2024.1) 中，Tableau 停用了“数据问答”(Ask Data) 功能。）

• 指标和域允许列表：尽管在已连接应用的域允许列表中可能指定了访问限制，嵌入式指标视图仍将显示。注意： 从嵌入式视图的工具栏访问的指标数据将按预期工作。（在 2023 年 10 月版 (Tableau 2023.3) 中，Tableau 停用了嵌入指标的功能。）