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

适用于： Tableau Cloud, Tableau Server

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

  • 通过您已为 Tableau Cloud 站点配置的身份提供程序 (IdP)，针对嵌入到您的外部应用程序中的 Tableau 内容为您的用户提供单点登录 (SSO) 站点体验
  • 使用 JSON Web 令牌 (JWT) 以编程方式代表用户授权访问 Tableau REST API（从 Tableau Cloud 2023 年 10 月开始为元数据 API）

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

重要信息：

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

步骤 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 中的一个或多个组的名称匹配。有关详细信息，请参见下面的按需访问（仅限嵌入工作流程）部分。

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

仅适用于嵌入工作流。

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

注意：

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

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

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

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

  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 请求能够以具有按需访问权限的用户身份发出。

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

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

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

    <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。
回到顶部
感谢您的反馈!您的反馈已成功提交。谢谢!