--- schema_version: "1" id: 66f09df6d9cbe2709594a1bf90432f98f781ec275164be029fccbcc0eb0f4ef3 title: SAML 要求 collection: tableau version: current locale: zh-cn portal_url: https://docs.salesforce.com/tableau/current/zh-cn/server-linux/saml_requ.md canonical_url: https://help.tableau.com/current/server-linux/zh-cn/saml_requ.htm source_site: help.tableau.com content_type: documentation content_hash: a7c7cfca1800aef609938222c747d6715fa88ae9940639da9d17c96b90fe450e description: Review the SAML requirements for Tableau Server. --- [跳转到主要内容](#main-content) # SAML 要求 在 Tableau Server 上配置 SAML 之前，确保您的环境满足要求。 **重要信息：**IdP 和 Tableau Server 上的 SAML 配置都区分大小写。例如，使用 IdP 和 Tableau Server 上配置的 URL 必须完全匹配。 ## 证书和身份提供程序 (IdP) 要求 若要将 Tableau Server 配置为使用 SAML，您需要以下内容： - ****证书文件**。**PEM 编码的 x509 证书文件，扩展名为 .crt。此文件由 Tableau Server 而不是 IdP 使用。如果有 SSL 证书，在某些情况下您可以将同一个证书与 SAML 一起使用。有关详细信息，请参见本文后面的[为 SAML 使用 SSL 证书和密钥文件](#Cert_Name)。 Tableau Server 需要证书密钥对来签署发送到 IdP 的请求。这减少了中间人攻击的威胁，因为难以欺骗签名的请求。此外，Tableau Server 会验证它收到的 AuthNResponse 是否来自从受信任的 IdP。Tableau Server 使用 IdP 生成的签名验证 AuthNResponse。IdP 证书元数据在初始 SAML 配置过程中提供给 Tableau Server。 并非所有 IdP 都需要签名的请求。默认情况下，Tableau Server 需要签名的请求。我们建议使用此配置，以确保与 IdP 的通信传输更安全。与您的 IdP 团队合作，了解是否需要禁用签名的请求。若要禁用签名的请求，请参见[samlSettings 实体](https://help.tableau.com/current/server-linux/zh-cn/entity_saml.htm)。 - **签名算法。**证书必须使用安全签名算法，例如 SHA-256。如果您尝试通过使用 SHA-1 签名哈希的证书为 SAML 配置 Tableau Server，则 Tableau Server 将拒绝该证书。您可以通过设置 tsm [wgserver.saml.blocklisted\_digest\_algorithms](https://help.tableau.com/current/server-linux/zh-cn/cli_configuration-set_tsm.htm#wgserver5) 配置键，将 Tableau Server 配置为接受安全性较低的 SHA-1 哈希。 - **RSA 密钥和 ECDSA 曲线大小。**Tableau Server 证书的 RSA 密钥强度必须为 2048，IdP 证书的 RSA 密钥强度必须为 2048，或者 ECDSA 曲线大小必须为 256。 您可以通过设置相应的配置键 [wgserver.saml.min\_allowed.rsa\_key\_size](https://help.tableau.com/current/server-linux/zh-cn/cli_configuration-set_tsm.htm#wgserver4) 和 [wgserver.saml.min\_allowed.elliptic\_curve\_size](https://help.tableau.com/current/server-linux/zh-cn/cli_configuration-set_tsm.htm#wgserver2)，将 Tableau Server 配置为安全性较低的大小。 - ****证书密钥文件**。**RSA 或 DSA 私钥文件，扩展名为 .key。RSA 密钥必须为 PKCS#1 或 PKCS#8 格式。 密码保护要求如下所示： - 无法使用密码保护 PKCS#1 RSA 密钥文件。 - 若要使用密码保护的密钥文件，您必须使用 RSA PKCS#8 文件配置 SAML。**注意：**不支持包含 null 密码的 PKCS#8 文件。 - 特定于站点的 SAML 部署不支持受密码保护的密钥文件。 **支持概要** | 密钥文件格式 | 服务器范围 SAML 支持 | 站点级别 SAML 支持 | | --- | --- | --- | | PKCS#8 RSA | 是 | 否 | | PKCS#8（无密码/空密码） | 否 | 否 | | PKCS#1 RSA | 是 | 是 | | PKCS#1 RSA（密码） | 否 | 否 | | PKCS#1 DSA（密码） | 否 | 否 | - **IdP 必须使用安全的签名算法对 SAML 断言进行签名。**默认情况下，Tableau Server 将拒绝使用 SHA-1 算法签名的 SAML 断言。您可以通过设置 tsm [wgserver.saml.blocklisted\_digest\_algorithms](https://help.tableau.com/current/server-linux/zh-cn/cli_configuration-set_tsm.htm#wgserver5) 配置键，将 Tableau Server 配置为接受使用安全性较低的 SHA-1 哈希签名的断言。 - ****支持 SAML 2.0 或更高版本的 IdP 帐户**。**您需要一个外部身份提供程序帐户。一些示例包括 PingFederate、SiteMinder 和 Open AM。 - ****支持导入和导出 XML 元数据的 IdP 提供程序**。**尽管手动创建的元数据文件可以工作，但 Tableau 技术支持无法协助进行生成该文件或排除其问题。 - **username：**必填。IdP 配置必须包含“username”属性或声明，并且 Tableau Server 上的相应 SAML 配置属性也必须设置为“username”。 ### SSL 卸载 如果在将身份验证请求发送到 Tableau Server 之前，您的组织在代理服务器处终止了来自 IdP 的 SSL 连接，则您可能需要进行代理配置。在这种情况下，SSL 在代理服务器处被“卸载”，这意味着 https 请求在代理服务器处被终止，然后通过 http 转发到 Tableau Server。 Tableau Server 将验证从 IdP 返回的 SAML 响应消息。由于 SSL 在代理处被卸载，因此 Tableau Server 将使用它收到的协议进行验证，但 IdP 响应的格式是使用 https 设置的，因此验证将失败，除非代理服务器包括设置为 `https` 的 X-Forwarded-Proto 标头。请参见[将 Tableau Server 配置为使用反向代理服务器和/或负载平衡器](https://help.tableau.com/current/server-linux/zh-cn/proxy.htm#Configur)。 ### 为 SAML 使用 SSL 证书和密钥文件 如果将 PEM 编码的 x509 证书文件用于 SSL，则可以将同一个文件用于 SAML。对于 SSL，证书文件用于加密流量。对于 SAML，证书用于进行身份验证。 除了上面的[证书和身份提供程序 (IdP) 要求](#Certific)中列出的要求外，若要为 SSL 和 SAML 使用相同的证书，证书还必须满足以下条件才能用于 SAML： - 确认证书仅包含适用于 Tableau Server 的证书，而不包含任何其他证书或密钥。 为此，您可以创建证书文件的备份副本，然后在文本编辑器中打开该副本以查看其内容。 ## 用户管理要求 如果启用 SAML，用户身份验证将在 Tableau 外部通过 IdP 执行。但是，用户管理通过身份存储执行：外部身份存储（Active Directory 或 LDAP），或由 Tableau Server 在本地身份存储中执行。有关使用 Tableau Server 规划用户管理的详细信息，请参见[身份存储](https://help.tableau.com/current/server-linux/zh-cn/plan_identity_store.htm)。 在安装过程中配置用户身份验证时，您必须选择反映所需 SAML 使用方式的选项。请注意，如果要使用特定于站点的 SAML，您必须在配置单独站点之前先配置服务器范围 SAML。 - **对于特定于站点的 SAML：**如果在 Tableau Server 上有多个站点，并且希望为特定 IdP 或 IdP 应用程序设置每个站点（或将某些站点配置为不使用 SAML），请将 Tableau Server 配置为使用本地身份存储管理用户。对于特定于站点的 SAML，Tableau Server 依靠 IdP 进行身份验证，并且不使用密码。 - **对于服务器范围 SAML：**如果配置具有单一 IdP 的服务器范围 SAML，您可以将 Tableau Server 配置为使用本地身份存储或外部身份存储。 - **对于服务器范围 SAML 身份验证和特定于站点的 SAML 身份验证:** - **使用本地身份存储时**，请务必使用具有电子邮件地址格式的用户名。使用完整的电子邮件地址可帮助保证用户名在 Tableau Server 中的唯一性，即使两个用户具有相同的电子邮件前缀但电子邮件域不同也是如此。为了确保身份的唯一性，请在两个系统中利用完整的电子邮件地址格式，或将 Tableau Server 升级到版本 2022.1.x 或更高版本并运行[身份迁移](https://help.tableau.com/current/server-linux/zh-cn/identity_migration.htm)后台作业。 - **在多站点环境中**，所有用户都通过在站点级别配置的 SAML IdP 进行身份验证。在这种方案中，您将为属于多个站点的用户指定服务器范围的默认 SAML IdP。若要配置此方案，Tableau Server 必须配置为使用本地身份存储。 - **匹配 SAML 用户名属性时忽略域**。从 Tableau Server 版本 2021.4.21、2022.1.17、2022.3.9 和 2023.1.5 开始，您可以将 Tableau Server 配置为在将身份提供程序 (IdP) 用户名与 Tableau Server 上的用户帐户匹配时忽略用户名属性的域部分。例如，IdP 中的用户名属性可能是 `alice@example.com`，以便于 Tableau Server 中名为 `alice` 的用户匹配。如果您已在 Tableau Server 中定义了与用户名属性的前缀部分匹配但与用户名属性的域部分不匹配的用户，则忽略用户名属性的域部分可能很有用。 **重要信息：**在未采取预防措施的情况下，我们不建议忽略域名。具体来说，请验证用户名在您在 IdP 中创建的已配置域中是否唯一。将 Tableau Server 配置为忽略域名可能会导致用户意外登录。考虑您的 IdP 针对多个域（例如，`example.com` 和 `tableau.com`）进行配置的情况。如果组织中有两个用户具有相同的名字，但用户帐户不同（例如，`alice@tableau.com`和`alice@example.com`），那么您可能会遇到映射不匹配的情况。 若要将 Tableau Server 配置为从 IdP 中忽略用户名属性中的域名，请将 `wgserver.ignore_domain_in_username_for_matching` 设置为 `true`。有关详细信息，请参见[wgserver.ignore\_domain\_in\_username\_for\_matching](https://help.tableau.com/current/server-linux/zh-cn/cli_configuration-set_tsm.htm#ignore_domain)。 **注意：** - 此命令仅适用于以下位置的 Tableau Server 部署：`legacy-identity-mode` 或尚未通过[身份迁移](https://help.tableau.com/current/server-linux/zh-cn/identity_migration.htm)更新以使用身份服务的部署。 - 在更改 tsm 命令以忽略用户名属性中的域名时，Tableau Server 中的所有用户名必须具有域名。 **注意：** [REST API](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm) 和 [tabcmd](http://onlinehelp.tableau.com/current/server/zh-cn/tabcmd.htm) 不支持 SAML 单点登录 (SSO)。若要登录，您必须指定已在服务器上创建的用户的名称和密码。可以通过本地身份存储或外部身份存储管理用户，具体取决于您配置 Tableau Server 的方式。REST API 或 tabcmd 调用将具有您在登录时使用的用户的权限。 ## SAML 兼容性注意事项和要求 - **匹配的用户名**：存储在 Tableau Server 中的用户名必须与 IdP 在 SAML 断言中发送的已配置用户名属性匹配。默认情况下，Tableau Server 期望传入断言包含名为“username”的属性以及该用户的信息。举例来说，如果 Jane Smith 的用户名在 PingFederate 中存储为 jsmith，那么它在 Tableau Server 中也必须存储为 jsmith。 **在身份验证期间配置 SAML 时** 如果要在初始 Tableau Server 设置过程中配置 SAML，请在运行安装程序之前确保您的 IdP 存在计划使用的帐户。在 Tableau Server 设置过程中，您将创建服务器管理员帐户。 **运行多个域时** 如果使用 Active Directory 或 LDAP 外部身份存储，并且在多个域中运行（也就是说，用户属于多个域或 Tableau Server 安装包括多个域），则 IdP 必须在 SAML 断言中为用户同时发送用户名_和_域属性。。这些用户名和域属性都必须与 Tableau Server 中存储的用户名和域完全匹配。执行以下操作_之一_： - 在用户名字段中设置 `domain\username` - 在域字段中设置域并在用户名字段中设置用户名 设置域属性时，可以使用完全限定域名 (FQDN) 或短名称。 如果未指定域，则将其视为默认域。 有关详细信息，请参见[支持多个域](https://help.tableau.com/current/server-linux/zh-cn/users_manage_ad.htm#multiple_domains)和[配置服务器范围 SAML](https://help.tableau.com/current/server-linux/zh-cn/config_saml.htm)的**“使用TSM CLI”**中的“匹配断言”部分。 - **签名算法：**Tableau Server 使用 SHA256 签名算法。 - **单点注销 (SLO)**：Tableau Server 支持服务提供商 (SP) 发起的 SLO 和身份提供程序 (IdP) 发起的 SLO，用于服务器范围的 SAML 和特定于站点的 SAML。 为了确保 SLO 按预期工作，需要 SAML HTTP-POST 绑定。有关详细信息，请参见下面的 [HTTP-POST 绑定](#binding)。有关 SLO 故障排除支持，请参见 [IDP 发起的单点注销行为不符合预期](https://help.salesforce.com/s/issue?id=a02Ka00000mmzqj)知识文章。 - **外部身份验证类型：**Tableau Server 支持一次使用一种外部身份验证类型。 - **相互 SSL**：Tableau Server 不同时支持相互 SSL（双向 SSL）和 SAML。如果要使用相互 SSL，您可以在 IdP 上对其进行配置。 - **断言编码**：断言必须为 UTF-8 编码。 - **加密和 SAML 断言**： - **服务器范围 SAML：**针对服务器范围 SAML 进行 Tableau Server 配置时，Tableau Server 支持来自 IdP 的加密断言。作为服务器范围 SAML 的初始配置的一部分，您上传的证书将启用加密断言。SAML 请求和响应可以通过 HTTP 或 HTTPS 发送。 - **特定于站点的 SAML：**针对站点范围 SAML 进行 Tableau Server 配置时，Tableau Server 不支持来自 IdP 的加密断言。但是，所有 SAML 请求和响应都通过 HTTPS 发送，以确保与 IdP 的通信安全。不支持 HTTP 请求和响应。 - **Tableau Server 中适用于 tabcmd 用户的用户标识**：如上面的[用户管理要求](#saml_user_mgmt)部分中所述，若要使用 tabcmd，您必须以服务器上定义的用户身份登录。您不能将 SAML 帐户与 **tabcmd** 一起使用。 - **将 SAML SSO 与 Tableau Desktop 结合使用**：默认情况下，Tableau Desktop 允许 SP 发起的 SAML 身份验证。 如果您的 IdP 不支持此功能，您可以使用以下命令为 Tableau Desktop 禁用 SAML 登录。 `tsm authentication saml configure --desktop-access disable` 有关详细信息，请参见 [tsm authentication saml ](https://help.tableau.com/current/server-linux/zh-cn/cli_authentication_tsm.htm#TSMsaml)。 - **分布式安装**：TSM 版本的 Tableau Server（2018.2 及更高版本）使用客户端文件服务在多节点群集中共享文件。在群集中的初始节点上配置 SAML 后，客户端文件服务会将证书和密钥文件分发到其他节点。 - **登录 URL**：为了使用户能够登录，您的 IdP 必须配置为具有可将 POST 请求发送到以下 URL 的 SAML 登录端点： `https:///wg/saml/SSO/index.html`。 - **注销 URL**：为了使用户能够在使用 SAML 登录后注销（单点注销，或 SLO），您的 IdP 必须配置为具有可将 POST 请求发送到以下 URL 的 SAML 注销端点： `https:///wg/saml/SingleLogout/index.html`。 **注意：**Tableau Server 支持服务提供商 (SP) 发起的 SLO 和身份提供程序 (IdP) 发起的 SLO，用于服务器范围的 SAML 和特定于站点的 SAML。 - **注销后重定义 URL**：默认情况下，当用户注销 Tableau Server 时，将显示登录页面。  若要在注销后显示其他页面，请带 `-su` 或 `--signout-url` 选项使用 `tsm authentication saml configure` 命令。 - 若要指定绝对 URL，请使用以 `http://` 或 `https://` 开头的完全限定的 URL，如此示例中所示： `tsm authentication saml configure -su https://example.com` - 若要指定相对于 Tableau Server 主机的 URL，请使用以 /（斜杠）开头的页面： `tsm authentication saml configure -su /ourlogoutpage.html` - **Active Directory 联合服务 (AD FS)**：您必须配置 AD FS 以返回使用 SAML 的 Tableau 身份验证的其他属性。Name ID 和 username 属性可映射到相同的 AD 属性：SAM 帐户名称。 - **AuthNContextClassRef**：AuthNContextClassRef 是一个可选的 SAML 属性，用于强制验证 IdP 启动的流程中的某些身份验证“上下文”。您可以使用 TSM 为此属性设置逗号分隔值。设置此属性后，Tableau Server 将验证 SAML 响应是否至少包含列出的值之一。如果 SAML 响应不包含配置的值之一，则即使用户已成功使用 IdP 进行身份验证，身份验证也将被拒绝。 将此可选属性留空将导致默认行为：任何成功经过身份验证的 SAML 响应都将导致用户在 Tableau Server 中被授予会话。 仅支持为服务器范围 SAML 评估该值。如果配置了站点 SAML，则将忽略 `AuthNContextClassRef` 该属性。 - 若要使用 TSM Web 界面设置此值，请参见[配置服务器范围 SAML](https://help.tableau.com/current/server-linux/zh-cn/config_saml.htm)。 - 若要使用 [tsm configuration set](https://help.tableau.com/current/server-linux/zh-cn/cli_configuration_tsm.htm#TSMSet)设置此值，请使用 `wgserver.saml.authcontexts` 键设置逗号分隔的值列表。 - 若要使用 JSON 配置文件设置此值，请参见[samlSettings 实体](https://help.tableau.com/current/server-linux/zh-cn/entity_saml.htm)。 ## 将 SAML SSO 用于 Tableau 客户端应用程序 Tableau Server 用户（具有 SAML 凭据）可从 Tableau Desktop 或 Tableau Mobile 应用登录到服务器。为了全面兼容，我们建议 Tableau 客户端应用程序版本与服务器的版本匹配。若要使用特定于站点的 SAML 进行连接，用户必须运行 Tableau 客户端应用程序版本 10.0 或更高版本。 从 Tableau Desktop 或 Tableau Mobile 连接到 Tableau Server 时，将使用服务提供程序 (SP) 发起的连接。 ### 将经过身份验证的用户重定向回 Tableau 客户端 用户登录到 Tableau Server 时（使用 SP 发起的工作流），Tableau Server 会向 IdP 发送一个 SAML 请求 (`AuthnRequest`)，其中包括 Tableau 应用程序的 **RelayState** 值。如果用户已通过诸如 Tableau Desktop 或 Tableau Mobile 等 Tableau 客户端登录到 Tableau Server，则务必在 IdP 对 Tableau 的 SAML 响应内返回 RelayState 值，以将用户定向到特定的 Tableau 资源。 当用户直接从 IdP（使用 IdP 发起的工作流） 启动 Tableau Server 登录过程时，IdP 可以在 SAML 响应中包括 **RelayState** 值，以将用户定向到特定的 Tableau 资源。例如，RelayState 值可以设置为 `/#/site/[site-url]/views/[view-name]/[workbook-tab-name]`。 如果在这些情形下未正确返回 RelayState 值，则会在 Web 浏览器中将用户转向其 Tableau Server 主页，而不是重定向回他们从中登录的应用程序。 与身份提供商和内部 IT 团队合作，确认此值将包括在 IdP 的 SAML 响应内，然后由位于 IdP 和 Tableau Server 之间的任何网络设备（例如代理或负载平衡器）保留。 ## XML 数据要求 在 SAML 配置过程中，您会在 Tableau Server 和 IdP 之间交换 XML 元数据。此 XML 元数据用于在用户启动 Tableau Server 登录过程时验证用户的身份验证信息。 Tableau Server 和 IdP 都各自会生成自己的元数据。每组元数据都必须包含以下列表中描述的信息。如果任何一组元数据缺少信息，则在您配置 SAML 或在用户尝试登录时可能会发生错误。 ### HTTP-POST 对于服务器范围 SAML，Tableau Server 对于 SAML 通信仅支持 HTTP POST 请求。在由 IdP 导出的 SAML 元数据 XML 文档中，`Binding` 属性必须设置为 HTTP-POST。 **注意：** - Tableau Server 不支持单点注销 (SLO) 的 HTTP-REDIRECT 绑定。更具体地说，SP 发起的 SLO（当用户直接从 Tableau Server 中单击“注销”时）或 IdP 发起的 SLO（当用户注销身份提供程序时）都不支持 HTTP-REDIRECT 绑定。某些身份提供程序可能会为 SLO 请求使用 HTTP-REDIRECT 绑定。为 SLO 使用 HTTP-REDIRECT 将导致注销失败，因为 Tableau Server 将不会正确处理通过 HTTP-REDIRECT 发送的注销请求。确保您的 IdP 配置为对所有 SAML 通信使用 HTTP-POST 绑定。 - 特定于站点的 SAML 确实支持 HTTP-Redirect 绑定。有关详细信息，请参见[配置特定于站点的 SAML](https://help.tableau.com/current/server-linux/zh-cn/saml_site_specific.htm)。 - 当 `Binding` 属性设置为 `HTTP-POST` 时，Tableau Server 和 IdP 每次导出的 SAML 元数据必须包含以下元素。 - 指定身份验证成功后 IdP 重定向到的 URL 的元素。这是服务提供商元数据（而不是身份提供程序元数据）中所必需的。 `` 对于站点 SAML，`Location` 端点为 `/samlservice/public/sp/metadata?alias=`。 - 注销端点元素显示在 Tableau Server 元数据中，并指定 IdP 将用于 Tableau Server 的注销端点的 URL。如果此元素不在 IdP 元数据中，Tableau Server 将无法与 IdP 协调注销端点，并且“SAML 注销”功能在 Tableau Server 内将不可用： `` - 此元素应出现在 IdP 元数据中，并指定 Tableau Server 将用于 IdP 的注销端点的 URL。 `` ### 名为 _username_ 的属性 您必须配置 IdP 以返回在 `saml:AttributeStatement` 元素中包括 `username` 属性的断言。声明的属性类型必须为 `xs:string`（_不_应将其键入为 `xs:any`）。 以下示例显示此项可能的样子。 _issuer-information_ ... ... ... ... **_user-name_** 默认情况下，Tableau Server 将在 Idp 返回的 AuthNResponse 中读取 `username` 属性。但是，某些 IdP 可能返回用于标识用户的不同属性。 若要更改传递 `username` 值的 SAML 属性，请运行以下 TSM 命令： `tsm authentication saml map-assertions --user-name `。 请参见[tsm authentication](https://help.tableau.com/current/server-linux/zh-cn/cli_authentication_tsm.htm#tsm)。 ### 使用 SAML 断言的动态群组成员身份 从 Tableau Server 2024.2 开始，如果配置了 SAML （或站点 SAML） 并启用功能的设置（服务器范围或站点级别），您可以通过身份提供商 (IdP) 发送的 SAML XML 响应中包含的自定义声明来动态控制群组成员身份。 配置后，在用户身份验证期间，IdP 会发送包含两个自定义组成员身份声明的 SAML 断言：组 (`https://tableau.com/groups` ) 和组名（例如，“Group1”和“Group2”）来将用户声明到其中。Tableau 验证该断言，然后启用对组以及权限依赖于这些组的内容的访问权限。 有关详细信息，请参见[使用断言的动态组成员身份](https://help.tableau.com/current/server-linux/zh-cn/groups_create_local.htm#assertions)。 **SAML XML 响应示例** Group1 Group2 ### SAML 断言中的用户属性 从 Tableau Server 2026.2 开始，在配置并启用功能的设置后，您可以在登录期间将身份提供程序 (IdP) 发送的 SAML XML 响应中的用户属性断言传递到 Tableau Server。这些用户属性可与 Tableau 的用户属性函数 (`USERATTRIBUTE()`, `USERATTRIBUTEINCLUDES()`) 结合使用，动态控制和自定义内容。Tableau 验证该断言，然后启用对内容的访问。 有关详细信息，请参见[使用用户属性自定义和控制数据访问](https://help.tableau.com/current/server-linux/zh-cn/config_saml.htm#user_attributes)。 **SAML XML 响应示例** South South West