注册 EAS 以启用嵌入内容的 SSO

适用于： Tableau Cloud, Tableau Server

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

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

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

重要信息：

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

步骤 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。

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

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

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

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

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

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

  2. 导航到“用户身份和访问”>“授权服务器”，然后执行以下操作：

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

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

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

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

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

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

  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

步骤 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-viz id='tab-viz' src='https://<your_server>/t/<your_site>/...'
	toolbar='hidden'>
</tableau-viz>

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

疑难解答

当嵌入内容无法在您的外部应用程序中显示或 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。
回到顶部
感谢您的反馈!您的反馈已成功提交。谢谢!