当前位置 > 支持 > 帮助中心 > Tableau 帮助手册 > Windows 版 Tableau Server > 帮助 > 管理服务器

配置 Tableau 已连接应用以启用嵌入内容的 SSO

版本：2022.1 及更高版本

从 Tableau Server 版本 2022.1 开始， Tableau 已连接应用通过促进您的 Tableau Server 站点与嵌入 Tableau 内容的自定义应用程序之间建立明确的信任关系，实现无缝且安全的身份验证体验。

已连接应用提供以下好处：

限制对哪些内容可以嵌入以及该内容可以嵌入的位置的访问
为用户提供使用单点登录 (SSO) 访问嵌入内容的能力，而不必与身份提供程序 (IdP) 集成
为用户提供直接从自定义应用程序进行身份验证的能力

注意：

在 Tableau Server 版本 2021.4 中，可通过 Tableau REST API 中的已连接应用方法(链接在新窗口中打开)使用无 UI 的已连接应用功能。
Tableau 已连接应用和 Salesforce 已连接应用不同并且提供不同的功能。如今，Tableau 已连接应用已针对在自定义应用程序中嵌入 Tableau 视图和指标进行了优化。

已连接应用的工作方式

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

已连接应用的关键组件

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

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

已连接应用工作流程

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

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

创建已连接应用

步骤 1：创建已连接应用

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

以服务器管理员或站点管理员身份登录 Tableau Server。
从左侧窗格中，选择“设置”>“已连接应用”，然后单击“新建已连接应用”按钮。
在“创建已连接应用”对话框中，执行以下操作：

在“已连接应用名称”文本框中，输入已连接应用的名称。
从“应用于”下拉菜单中，选择“所有项目”或“仅一个项目”来控制可以嵌入哪些视图或指标。如果您选择“仅一个项目”选项，请选择要确定范围的特定项目。
在“域允许列表”中，使用下面的域格式设置中描述的规则指定域，以控制可以嵌入视图或指标的位置。
完成后，单击“创建”按钮。

在已连接应用的名称旁边，单击操作菜单并选择“启用”。出于安全考虑，已连接应用在创建时默认设置为禁用。
记下已连接应用的 ID（也称为客户端 Id），以在下面的“步骤 3”中使用。

步骤 2：生成密文

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

在您在“步骤 1”中创建的已连接应用的详细信息页面上，单击“生成新密文”按钮。
记下要在下面的“步骤 3”中使用的密文 ID 和密文值。

步骤 3：配置 JWT

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

有效的 JWT 包括以下信息：

来自“步骤 1”的已连接应用 ID（也称为客户端 ID）
“步骤 2”中生成的密文 ID 和密文值

注册的声明和标题：

声明	描述或必需值
“`iss`”（颁发者）	必需（在标题中或作为声明）。标识受信任的已连接应用及其签名密钥的唯一颁发者 URI。
“`alg`”（算法）	必需（在标题中或作为声明）。JWT 签名算法。仅支持 HS256。
“sub”（使用者）	经过身份验证的 Tableau Server 用户的。
“`aud`”（受众群体）	值必须是：“`tableau`”
“`exp`”（过期时间）	有效的 JWT 不得过期。JWT 的过期时间必须在配置的最长有效期内。可以使用 tsmvizportal.oauth.connected_apps.max_expiration_period_in_minutes命令配置最长有效期。
“`jti`”(JWT ID)	要求采用声明形式。JWT ID 声明为 JWT 提供唯一标识符，并且区分大小写。
“`scp`”（范围）	支持的值包括： “`tableau:views:embed`” “`tableau:metrics:embed`” 注意：

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

示例 JWT

以下是 Java 和 Python 语言的示例 JWT。

Java

String secret = "secretvalue";
	String kid = "connectedAppSecretId";
	String clientId = "connectedAppClientId";
	List<String> scopes = new
ArrayList<>(Arrays.asList("tableau:views:embed"));
	String username ="username";
	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)
		.build();
	SignedJWT signedJWT = new SignedJWT(header, claimsSet);
	signedJWT.sign(signer);
	model.addAttribute("token", signedJWT.serialize());

Python

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"]
	},
		connectedAppSecretKey,
		algorithm = "HS256",
		headers = {
		'kid': connectedAppSecretId,
		'iss': connectedAppClientId
        }
  )

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

步骤 4：嵌入后续步骤

配置 JWT 后，您必须向自定义应用程序中添加嵌入代码。确保在自定义应用程序调用的 Web 组件中包含您在上述“步骤 3”中配置的有效 JWT。

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

嵌入指标，请参见 Tableau 帮助中的将指标嵌入网页(链接在新窗口中打开)主题。
Tableau Embedding API v3(链接在新窗口中打开) 嵌入 Tableau 视图和指标。

注意：为了让用户在访问嵌入式内容时成功进行身份验证，浏览器必须配置为允许第三方 Cookie 或使用分区存储。Mozilla Firefox 默认启用分区存储，并且可以在 Google Chrome 浏览器上启用。

管理已连接应用

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

以服务器管理员或站点管理员身份登录 Tableau Server。
从左侧窗格中，选择“设置”>“已连接应用”。
选中您要管理的已连接应用旁边的复选框，然后执行以下一项或多项操作：

根据您组织的安全策略指定的轮换时间线生成新密文。若要生成额外的密文，请单击已连接应用的名称，然后单击“生成新密文”按钮。一个已连接应用最多可以有两个密文。这两个密文可以同时处于活动状态，不会过期，并且在被删除之前一直有效。
通过单击已连接应用的名称查看已连接应用的创建时间、其 ID、项目和域范围及其密文，查看已连接应用详细信息。
更改项目范围或域，在“操作”菜单中，选择“编辑”。进行更改并单击“更新”。
注意：如果您更改项目或域范围，并且新项目或新域中不存在嵌入的内容，则嵌入的视图或指标无法显示，用户在访问嵌入的内容时会看到错误。
通过单击已连接应用的名称来删除密文。在已连接应用页面上，单击密文旁边的“操作”并选择“删除”。在确认对话框中，再次选择“删除”。
注意：如果自定义应用程序正在使用已连接应用的密文，则删除密文后无法显示嵌入的视图或指标。有关详细信息，请参见下面的禁用或删除已连接应用或删除密文的影响。
禁用已连接应用，在“操作”菜单中，选择“禁用”。如果自定义应用程序正在使用已连接应用，则在禁用已连接应用后无法显示嵌入的视图或指标。有关详细信息，请参见下面的禁用或删除已连接应用或删除密文的影响。

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

若要通过已连接应用向您的用户显示嵌入式视图或指标，需要启用已连接应用并生成密文。如果已连接应用正在您的自定义应用程序中使用并且被禁用或删除，或者其密文被删除或替换，则用户在访问嵌入内容时将收到错误。

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

域允许列表规则

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

域选项

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

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

域格式设置

在域允许列表文本框中，您可以输入一个域、多个域或根本不输入域。域允许列表遵守 CSP（内容安全策略）框架的 frame-ancestors 标头(链接在新窗口中打开)允许的任何格式设置。

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

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

若要指定...	示例	嵌入访问
域范围	*.myco.com	可以从 myco.com 下的所有子域访问嵌入的内容。
多个离散域	myco.com events.myco.com ops.myco.com	嵌入的内容可从所有三个域访问。
没有域	[没有域]	对嵌入内容的访问被阻止。

已知问题

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

工具栏功能：当嵌入式内容定义了工具栏参数时，并非所有工具栏功能都可以使用。为了解决此问题，我们建议您像下面的示例一样隐藏工具栏参数。
```
<tableau-viz id='tab-viz' src='https://<your_server>/t/<your_site>/...'
	toolbar='hidden'>
</tableau-viz>
```

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

此部分中的其他文章

对已连接应用进行故障排除

当嵌入内容无法在您的自定义应用程序中显示时，您可以使用浏览器的开发人员工具来检查和识别可能与用于显示嵌入内容的 Tableau 已连接应用相关联的错误代码。

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

错误代码	摘要	描述	潜在的解决方案或解释
5	SYSTEM_USER_NOT_FOUND	找不到 Tableau 用户	若要解决此问题，请验证 JWT 中的“sub”（使用者）声明值为 Tableau Server 的“用户名”。此值区分大小写。
16	LOGIN_FAILED	登录失败	此错误通常是由 JWT 中的以下声明问题之一引起的： “exp”（过期时间）超过了默认的最长有效期。若要解决此问题，请查看有效 JWT 所需的已注册声明(链接在新窗口中打开)并确保使用正确的值。若要更改最长有效期，可以使用vizportal.oauth.connected_apps.max_expiration_period_in_minutes命令。 “sub”（使用者）正在调用未知用户。若要解决此问题，请验证“sub”声明是否为“username”。此值区分大小写。
126	CONNECTED_APP_NOT_FOUND	找不到已连接应用	若要解决此问题，请验证是否已启用已连接应用并且在 JWT 中引用了正确的客户端 ID（也称为已连接应用程序 ID）。
127	CONNECTED_APP_SECRET_NOT_FOUND	找不到已连接应用的密文	若要解决此问题，请验证 JWT 中是否引用了正确的已连接应用的密文 ID 和密文值。
128	CONNECTED_APP_SECRET_LIMIT_EXCEEDED	已达到密文的最大限制	一个已连接应用最多允许使用两个密文。当尝试创建第三个密文时，可能会发生此错误。若要解决此问题，请在创建新密文之前从已连接应用中删除一个密文。
133	INVALID_CONNECTED_APP_DOMAIN_SAFELIST	域允许列表包含一个或多个无效字符	当域允许列表包含一个或多个无效字符时，可能会发生此错误。
10083	BAD_JWT	JWT 标头包含问题	此错误通常是由 JWT 标头的以下问题之一引起的： JWT 标头中缺少“secret key”（Kid）或“clientId”（颁发者）声明。若要解决此问题，请确保包含此信息。 JWT 未签名或已加密。Tableau 不支持未签名或已加密的 JWT。
10084	JWT_PARSE_ERROR	JWT 包含问题	若要解决此问题，请验证以下各项： JWT 中引用的“aud”（受众群体）值是否使用“tableau”值。此值区分大小写。 “aud”（受众群体）、“sub”（主题）、“jti”（JWT ID）都包含在 JWT 中。
10085	COULD_NOT_FETCH_JWT_KEYS	JWT 找不到密钥	找不到密文。若要解决此问题，请验证是否调用了正确的颁发者。
10087	BLOCKLISTED_JWS_ALGORITHM_USED_TO_SIGN	JWT 签名算法存在问题	若要解决此问题，您可以移除签名算法。有关详细信息，请参见vizportal.oauth.external_authorization_server.blocklisted_jws_algorithms。
10089	CONNECTED_APP_NOT_FOUND	找不到已连接应用	若要解决此问题，请确保颁发者调用正确的已连接应用 ID（也称为客户端 ID）。
10090	CONNECTED_APP_DISABLED	已连接应用被禁用	用于验证信任的已连接应用已禁用。若要解决此问题，请启用已连接应用。
10091	JTI_ALREADY_USED	需要唯一的 JWT	JWT 已在身份验证过程中使用。若要解决此问题，必须生成新的 JWT。