Linux 版 Tableau Server 帮助

在 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 证书和密钥文件。

  Tableau Server 需要证书密钥对来签署发送到 IdP 的请求。这减少了中间人攻击的威胁，因为难以欺骗签名的请求。此外，Tableau Server 会验证它收到的 AuthNResponse 是否来自从受信任的 IdP。Tableau Server 使用 IdP 生成的签名验证 AuthNResponse。IdP 证书元数据在初始 SAML 配置过程中提供给 Tableau Server。

  并非所有 IdP 都需要签名的请求。默认情况下，Tableau Server 需要签名的请求。我们建议使用此配置，以确保与 IdP 的通信传输更安全。与您的 IdP 团队合作，了解是否需要禁用签名的请求。若要禁用签名的请求，请参见samlSettings 实体。

• 签名算法。证书必须使用安全签名算法，例如 SHA-256。如果您尝试通过使用 SHA-1 签名哈希的证书为 SAML 配置 Tableau Server，则 Tableau Server 将拒绝该证书。您可以通过设置 tsm wgserver.saml.blocklisted_digest_algorithms 配置键，将 Tableau Server 配置为接受安全性较低的 SHA-1 哈希。

• RSA 密钥和 ECDSA 曲线大小。Tableau Server 证书的 RSA 密钥强度必须为 2048，IdP 证书的 RSA 密钥强度必须为 2048，或者 ECDSA 曲线大小必须为 256。

  您可以通过设置相应的配置键 wgserver.saml.min_allowed.rsa_key_size 和 wgserver.saml.min_allowed.elliptic_curve_size，将 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 配置键，将 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 配置为使用反向代理服务器和/或负载平衡器。

为 SAML 使用 SSL 证书和密钥文件

如果将 PEM 编码的 x509 证书文件用于 SSL，则可以将同一个文件用于 SAML。对于 SSL，证书文件用于加密流量。对于 SAML，证书用于进行身份验证。

除了上面的证书和身份提供程序 (IdP) 要求中列出的要求外，若要为 SSL 和 SAML 使用相同的证书，证书还必须满足以下条件才能用于 SAML：

• 确认证书仅包含适用于 Tableau Server 的证书，而不包含任何其他证书或密钥。

  为此，您可以创建证书文件的备份副本，然后在文本编辑器中打开该副本以查看其内容。

用户管理要求

如果启用 SAML，用户身份验证将在 Tableau 外部通过 IdP 执行。但是，用户管理通过身份存储执行：外部身份存储（Active Directory 或 LDAP），或由 Tableau Server 在本地身份存储中执行。有关使用 Tableau Server 规划用户管理的详细信息，请参见身份存储。

在安装过程中配置用户身份验证时，您必须选择反映所需 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 或更高版本并运行身份迁移后台作业。

  • 在多站点环境中，所有用户都通过在站点级别配置的 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。

    注意：

    • 此命令仅适用于以下位置的 Tableau Server 部署：legacy-identity-mode 或尚未通过身份迁移(链接在新窗口中打开)更新以使用身份服务的部署。
    • 在更改 tsm 命令以忽略用户名属性中的域名时，Tableau Server 中的所有用户名必须具有域名。

注意： REST API 和 tabcmd 不支持 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) 或短名称。

  如果未指定域，则将其视为默认域。

  有关详细信息，请参见支持多个域和配置服务器范围 SAML的“使用TSM CLI”中的“匹配断言”部分。

• 签名算法：Tableau Server 使用 SHA256 签名算法。

• 单点注销 (SLO)：Tableau Server 支持服务提供商 (SP) 发起的 SLO 和身份提供程序 (IdP) 发起的 SLO，用于服务器范围的 SAML 和特定于站点的 SAML。

• 外部身份验证类型：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 用户的用户标识：如上面的用户管理要求部分中所述，若要使用 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 <commands>。

• 分布式安装：TSM 版本的 Tableau Server（2018.2 及更高版本）使用客户端文件服务在多节点群集中共享文件。在群集中的初始节点上配置 SAML 后，客户端文件服务会将证书和密钥文件分发到其他节点。

• 登录 URL：为了使用户能够登录，您的 IdP 必须配置为具有可将 POST 请求发送到以下 URL 的 SAML 登录端点：

  https://<tableauserver>/wg/saml/SSO/index.html。

• 注销 URL：为了使用户能够在使用 SAML 登录后注销（单点注销，或 SLO），您的 IdP 必须配置为具有可将 POST 请求发送到以下 URL 的 SAML 注销端点：

  https://<tableauserver>/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。

  若要使用 tsm configuration set设置此值，请使用 wgserver.saml.authcontexts 键设置逗号分隔的值列表。

  若要使用 JSON 配置文件设置此值，请参见samlSettings 实体。

将 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 时，Tableau Server 会向 IdP 发送一个 SAML 请求 (AuthnRequest)，其中包括 Tableau 应用程序的 RelayState 值。如果用户已通过诸如 Tableau Desktop 或 Tableau Mobile 等 Tableau 客户端登录到 Tableau Server，则在 IdP 对 Tableau 的 SAML 响应内返回 RelayState 值至关重要。

如果在此情形下未正确返回 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 和 HTTP REDIRECT：Tableau Server 支持 SAML 通信的 HTTP POST 和 HTTP REDIRECT 请求。在由 IdP 导出的 SAML 元数据 XML 文档中，Binding 属性可以设置为HTTP-POST 或 HTTP-REDIRECT。

• 当 Binding 属性设置为 HTTP-POST 时，Tableau Server 和 IdP 每次导出的 SAML 元数据必须包含以下元素。

  • 指定身份验证成功后 IdP 重定向到的 URL 的元素。这是服务提供商元数据（而不是身份提供程序元数据）中所必需的。

    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<tableau-server>/wg/saml/SSO/index.html index="0" isDefault="true"/>

    对于站点 SAML，Location 端点为 /samlservice/public/sp/metadata?alias=<site alias>。

  • 注销端点元素显示在 Tableau Server 元数据中，并指定 IdP 将用于 Tableau Server 的注销端点的 URL。如果此元素不在 IdP 元数据中，Tableau Server 将无法与 IdP 协调注销端点，并且“SAML 注销”功能在 Tableau Server 内将不可用：

    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://SERVER-NAME:9031/idp/slo"

  • 验证您从 IdP 获得的元数据 XML 是否包括绑定设置为 HTTP-POST 的 SingleSignOnService 元素，如以下示例中所示：

    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://SERVER-NAME:9031/idp/SSO.saml2"/>

  • 此元素应出现在 IdP 元数据中，并指定 Tableau Server 将用于 IdP 的注销端点的 URL。

    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://SERVER-NAME:9031/idp/slo"/>

• 名为 username 的属性：您必须配置 IdP 以返回在 saml:AttributeStatement 元素中包括 username 属性的声明。声明的属性类型必须为 xs:string（不应将其键入为 xs:any）。

  以下示例显示此项可能的样子。

  <saml:Assertion assertion-element-attributes>
    <saml:Issuer>issuer-information</saml:Issuer>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
      ...
    </Signature>
    <saml:Subject>
      ...
    </saml:Subject>
    <saml:Conditions condition-attributes >
      ...
    </saml:Conditions>
    <saml:AuthnStatement authn-statement-attributes >
      ...
    </saml:AuthnStatement>
  
    <saml:AttributeStatement>
      <saml:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
            user-name
      </saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>

  默认情况下，Tableau Server 将在 Idp 返回的 AuthNResponse 中读取 username 属性。但是，某些 IdP 可能返回用于标识用户的不同属性。

  若要更改传递 username 值的 SAML 属性，请运行以下 TSM 命令：

  tsm authentication saml map-assertions --user-name <USER-NAME>。

  请参见tsm authentication。

• 使用 SAML 断言的动态组成员身份：

  从 Tableau Server 2024.2 开始，如果配置了 SAML （或站点 SAML） 并启用功能的设置（服务器范围或站点级别），您可以通过身份提供商 (IdP) 发送的 SAML XML 响应中包含的自定义声明来动态控制群组成员身份。

  配置后，在用户身份验证期间，IdP 会发送包含两个自定义组成员身份声明的 SAML 断言：组 (https://tableau.com/groups) 和组名（例如，“Group1”和“Group2”）来将用户声明到其中。Tableau 验证该断言，然后启用对组以及权限依赖于这些组的内容的访问权限。

  有关详细信息，请参见使用断言的动态组成员身份。

  SAML XML 响应示例

  <saml2p:Response
    xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
      .....
      .....
    <saml2:Assertion
      .....
      .....
      xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
      <saml2:AttributeStatement
    		xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
    		<saml2:Attribute
      		Name="https://tableau.com/groups"
  			NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
    			<saml2:AttributeValue
  				xmlns:xs="http://www.w3.org/2001/XMLSchema"
  				xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  				xsi:type="xs:string">Group1
  			</saml2:AttributeValue>
  			<saml2:AttributeValue
  				xmlns:xs="http://www.w3.org/2001/XMLSchema"
  				xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  				xsi:type="xs:string">Group2
  			</saml2:AttributeValue>
      	<saml2:Attribute>
      </saml2:AttributeStatement>
    </saml2:Assertion>
  </saml2p:Response>