如何设置 TruTrip 的 SAML SSO 集成

TruTrip 支持使用 SAML 2.0 的单点登录 (SSO)。借助 SAML SSO，您的团队可以通过组织的身份提供商 (IdP)（例如 JumpCloud）登录 TruTrip，而无需使用单独的 TruTrip 密码。

本文面向为公司设置 SAML SSO 的 IT 管理员。内容涵盖开始之前需要准备的事项、如何配置身份提供商、如何测试连接以及出现问题时的解决方法。

注意： SAML SSO 仅用于登录，不会创建 TruTrip 帐户。每个用户必须先拥有 TruTrip 帐户，或已受邀加入 TruTrip，才能使用 SSO 登录。

开始之前

请确保：

• 您的组织拥有有效的 TruTrip 企业帐户。
• 您已联系 TruTrip 支持团队，申请为您的公司开通 SAML SSO。
我们的团队将协助您完成设置。
• 所有需要 SSO 访问权限的用户都已拥有 TruTrip 帐户或已收到邀请。
• 您身份提供商中每个用户的电子邮件地址与其 TruTrip 帐户电子邮件地址完全匹配。
• 您的身份提供商支持 SAML 2.0。
• 您拥有管理员权限才能在您的身份提供商中创建 SAML 应用程序。

步骤 1：在您的身份提供商中创建 TruTrip 应用程序

在您的身份提供商中，为 TruTrip 创建一个新的 SAML 2.0 应用程序，并输入以下值。

设置	值
SP 实体 ID / 受众 URI	https://app.trutrip.co/saml
ACS URL / 回复URL	https://api.trutrip.co/v1/oauth/login/saml/callback
NameID	用户的电子邮件地址
NameID 格式	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
SAML 版本	2.0
签名算法	RSA-SHA256

SAML 响应或断言必须经过签名。

除非 TruTrip 支持部门另有指示，否则请保持断言加密关闭状态。

注意： SP 实体 ID 和 ACS URL 必须与上述值完全匹配。即使是微小的差异，例如多一个空格或漏掉一个字符，都会导致登录失败。

步骤 2：映射用户属性

在 SAML 断言中包含以下用户详细信息。

属性	要求	描述
email	必填	用户的 TruTrip 帐户电子邮件地址
firstName	推荐	用户名字
姓氏	推荐	用户的姓氏

例如，对于名为 John Doe 的用户：

NameID：john.doe@example.com

email：john.doe@example.com

firstName：John

lastName：Doe

使用 Microsoft Entra ID (Azure AD)？ 默认情况下，Entra ID 会将用户主体名称 (UPN) 作为 NameID 发送，而不是电子邮件地址。如果用户的 UPN 与其电子邮件地址不同，请更改 NameID 声明以使用用户的电子邮件地址。另请检查您的声明名称是否设置为 email、firstName 和 lastName。

步骤 3：将您的身份提供商详细信息发送给 TruTrip

创建应用程序后，请将以下详细信息发送给 TruTrip 支持：

信息	必填
身份提供商实体 ID / 颁发者	是
身份提供商单点登录URL	是
公钥 X.509 签名证书	是

您通常可以在身份提供商的 SAML 应用程序页面上找到这些信息，通常位于名为“SSO 信息”或“元数据”的部分。

重要提示：仅发送公钥 X.509 证书。切勿将身份提供商的私钥发送给 TruTrip 或任何其他人。

步骤 4：使用单个用户进行测试

我们建议在将 SAML SSO 推广到整个公司之前，先使用单个用户进行测试。选择一个在 TruTrip 和您的身份提供商中都已拥有帐户且电子邮件地址相同的现有用户。

您无需创建新的测试用户。

1. 选择您的测试用户。 选择一位已拥有 TruTrip 帐户和您身份提供商帐户的用户，并确保两个帐户中的电子邮件地址完全相同。
2. 在您的身份提供商中将 TruTrip 应用程序分配给该用户。
3. 登录。 请用户打开您身份提供商的用户门户并选择 TruTrip。应用程序。
4. 确认测试成功。 用户应该可以直接进入 TruTrip 主页，而无需输入 TruTrip 密码。

测试成功后，将 TruTrip 应用程序分配给其他用户或用户组。

用户如何登录

用户通过其身份提供商门户（例如 JumpCloud 用户门户）打开 TruTrip 应用程序进行登录。然后，他们将自动登录到 TruTrip。

注意： 目前无法从 TruTrip 登录页面启动 SAML SSO 登录。

用户应始终从您的身份提供商登录。

如果 SAML SSO 设置为贵公司必需的登录方式，则用户只需通过您的身份提供商登录，无需单独的 TruTrip 密码。

TruTrip 中保留哪些内容

SAML SSO 用于确认用户身份，但不会更改用户在 TruTrip 中的操作权限。

以下内容由 TruTrip 管理，您的身份提供商不会设置：

• 公司成员资格
• 用户角色和权限
• 账单访问权限
• 差旅政策
• 审批权限

在用户登录之前，TruTrip 会检查 SAML 响应是否真实，是否来自您配置的身份提供商，以及是否属于您公司中的现有用户。

故障排除

用户已登录身份提供商，但 TruTrip 登录未完成

请检查用户是否已拥有 TruTrip 帐户或已收到邀请。

SAML SSO 不会创建新的 TruTrip 用户。

用户的电子邮件地址不匹配

TruTrip 将不同的电子邮件地址视为不同的用户。例如，您的身份提供商中的 john@example.com 和 TruTrip 中的 john.doe@example.com 将不匹配。请确保您的身份提供商发送的电子邮件地址与 TruTrip 帐户的电子邮件地址完全相同。

如果您使用 Microsoft Entra ID，请参阅步骤 2 中关于 NameID 的说明。

用户无法看到 TruTrip 应用程序

请检查用户或其所属组是否已在您的身份提供程序中分配给 TruTrip 应用程序。

登录失败，出现配置错误

请检查您的身份提供程序中的 ACS URL 和 SP 实体 ID 是否与步骤 1 中的值完全匹配。

登录失败，出现签名错误

TruTrip 存档的证书可能与您的身份提供程序当前使用的证书不匹配。

这种情况通常发生在证书过期或被替换之后。请联系 TruTrip 支持团队进行更新。

更改您的签名证书

SAML 签名证书会过期，需要定期更换。在身份提供商中切换到新证书之前，请将新的公钥 X.509 证书发送给 TruTrip 支持团队。这样我们就可以更新您的配置，并将登录中断降至最低。

重要提示：切勿发送您的身份提供商的私钥。

关闭 SAML 单点登录

在从身份提供商中移除或禁用 TruTrip 应用程序之前，请联系 TruTrip 支持团队。

如果 SAML SSO 是贵公司要求的登录方式，我们将首先为贵公司切换到其他登录方式，以确保您的用户不会失去对 TruTrip 的访问权限。

联系 TruTrip 支持解决登录问题

为了帮助我们快速解决问题，请提供以下信息：

• 贵公司名称
• 受影响用户的电子邮件地址
• 您的身份提供商（例如，JumpCloud 或 Microsoft Entra ID）
• 登录尝试的大致时间
• 用户看到的任何错误消息（屏幕截图会有帮助）

请勿发送密码、私钥、访问令牌、会话数据或任何其他登录密钥。

在向用户推出 SAML SSO 之前，请确认：

• 您的身份提供商中已创建 TruTrip SAML 应用程序。
• SP 实体 ID 和 ACS URL 与步骤 1 中的值完全匹配。
• NameID 是用户的电子邮件地址，使用电子邮件地址采用 NameID 格式。
• 已映射 email、firstName 和 lastName 属性。
• SAML 响应或断言使用 RSA-SHA256 签名。
• 您的 IdP 实体 ID、SSO URL 和公共证书已发送至 TruTrip 支持团队。
• 您选择的测试用户已通过您的身份提供商成功登录。
• 所有需要访问权限的用户都拥有 TruTrip 帐户，且电子邮件地址匹配，并已分配到 TruTrip 应用程序。

---

⚠️ This article has been automatically translated from English. If there are any differences or inconsistencies, please refer to the English version as the most up-to-date source.