单点登录（SSO）

SSO 设置和使用

---

危险

本指南适用于系统管理员。如果你缺乏必要的技术专业知识，请联系你的 IT 部门寻求帮助。

Prevu3D Cloud Platform 通过行业标准协议支持安全的单点登录（SSO）：

• SAML 2.0 – 用于身份验证和用户登录。

• SCIM 2.0 – 用于自动用户和组配置。

支持的身份提供商

任何完全支持 SAML 2.0 和/或 SCIM 2.0 协议的身份提供商都应与 Prevu3D 兼容，包括 Okta、Google Workspace、OneLogin、Ping Identity 等。Prevu3D 的实现遵循官方 SAML 2.0 和 SCIM 2.0 规范，确保与现代身份系统的广泛兼容性。

我们已彻底测试了与以下系统的集成：

• Microsoft Entra ID（原 Azure Active Directory）

• JumpCloud（英文）

注意

• 每个 Prevu3D 组织一次仅支持与一个身份提供商的一个连接。

• SSO 功能包含在 Enterprise 订阅中。请联系 sales@prevu3d.com 为你的组织启用它。

SAML 2.0 – 身份验证设置

前提条件

要使用 Prevu3D 配置基于 SAML 的 SSO，你将需要：

• 对你 Prevu3D 组织的管理员访问权限。

• 对你 IdP 的访问权限，并有权限配置应用程序。

步骤

1. 登录你的 Prevu3D 账户（使用你的电子邮件地址和密码）

2. 转到设置选项卡

3. 从左侧菜单中选择 SSO 选项卡

无法访问 “SSO” 选项卡？

1. 如果它缺失，则你不是组织管理员。

2. 如果它呈灰色，则你的组织尚未订阅 SSO 功能。

4. 从 SSO 选项卡复制以下值并将它们粘贴到你的 IdP 配置中：

   • Service Provider Endpoint – 你的 IdP 提交 SAML 断言的目标 URL。你的 IdP 可能将其称为 ACS URL、Reply URL 或 Assertion Consumer Service URL。

   • Service Provider Entity ID – Prevu3D 在 SAML 交换中的唯一标识符。你的 IdP 可能将其称为 Audience、Identifier 或 SP Entity ID。

警告

在你的 IdP 中输入 Entity ID 时，请与 SSO 选项卡上显示的内容完全一致，包括完整的后缀（例如 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-production-############-Prevu3DCloudPlatform）。请复制粘贴该值，而不要手动重新键入。

如果你的 IdP 发送缩短的或友好名称形式的受众值（例如 Prevu3D），即使其余配置都正确，身份验证也会因受众不匹配而被拒绝。这是最常见的设置错误 — 请参阅故障排除。

5. 从你的 IdP 检索以下内容并在 SSO 选项卡上输入它们：

   • SAML Certificate (PEM format)

   • SAML Endpoint URL

6. 如果未启用 SCIM，请定义 SAML 属性映射 – 请参阅下方的 SAML 属性映射。

   

警告

当启用并配置 SCIM 配置时，这些属性是可选的。SCIM 会自动管理用户详情。

7. 点击页面底部的 Save。

8. 在向用户推广之前先验证配置 – 请参阅下方的验证你的配置。

SAML 属性映射

每个字段告诉 Prevu3D 应从身份提供商发送的 SAML 断言中读取哪个属性（claim）。你输入的值必须与 IdP 中配置的属性名称完全一致，包括大小写。

字段	应输入的内容	示例值
First Name SAML Attribute Key	包含用户名字的 IdP 属性名称	givenName、firstName、http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Last Name SAML Attribute Key	包含用户姓氏的 IdP 属性名称	familyName、surname、lastName
Role SAML Attribute Key（可选）	包含要分配的 Prevu3D 角色的 IdP 属性名称。仅当你希望从 IdP 管理 Prevu3D 角色时才需要 – 请参阅角色映射	Prevu3DRole
Default Organization Role	在未提供角色属性、属性为空或未配置角色映射时分配的角色 – 请参阅角色映射	Guest（推荐）

不确定你的 IdP 发送哪些属性名称？可使用 SAML-tracer 等浏览器扩展捕获 SAML 跟踪，查看 AttributeStatement 中列出的名称，或查阅你 IdP 中的应用程序配置。

向用户推广 SSO

配置保存并验证后，有两个因素决定你的用户能否实际登录。

域配置与新用户

你的电子邮件域必须与你的 Prevu3D 组织关联。域配置可实现：

• 登录页面重定向 – 点击使用 SSO 登录并输入你域下电子邮件的用户会被重定向到你的 IdP。

• 即时账户创建 – 当你域下从未使用过 Prevu3D 的用户通过你的 IdP 成功完成身份验证时，系统会自动创建 Prevu3D 账户，姓名根据你的 SAML 属性映射填充，并应用 Default Organization Role。无需邀请或手动创建账户。

注意

域配置由 Prevu3D 在你的 Enterprise SSO 入门流程中完成。请联系 support@prevu3d.com 认领你的电子邮件域。

在域配置完成之前，你域下的用户不会被重定向到你的 IdP，并且在进行身份验证时可能会收到 invalid_user_email_domain 错误。

警告

通过 SSO 创建的用户会获得 Default Organization Role，并且默认没有项目访问权限。请通过组（配合组映射）或直接将用户添加到项目中来授予项目访问权限。

已配置 SSO 的域下的用户应使用 SSO 登录，而不是通过电子邮件邀请链接创建基于密码的账户。

现有用户与账户关联

在启用 SSO 之前创建的账户需要与你的身份提供商关联一次，然后才能用于 SSO。用户首次使用 SSO 登录时，系统会引导他们完成此操作，并且他们的项目和数据将保留。他们看到的步骤记录在注册和登录中。

警告

关联需要每个用户现有的 Prevu3D 密码，因此忘记密码的用户必须先重置密码才能进行关联。

若要完全避免这一步骤，请联系 support@prevu3d.com，一次性关联你电子邮件域下的所有账户。这样用户就不会看到关联流程。

验证你的配置

在大范围推广 SSO 之前，请先与一小组用户进行测试并确认：

• 从 Prevu3D 登录页面（使用 SSO 登录）和你的 IdP 仪表板都能成功登录。

• 新账户上的名字和姓氏填充正确。

• 当存在角色属性时，分配的是预期的组织角色。

• 没有映射角色的用户会获得预期的默认角色。

• 没有用户获得超出预期的权限。

• 如果你使用组映射，组成员身份按预期应用。

注意

使用 SAML-tracer 等浏览器扩展捕获的 SAML 跟踪，是准确核实你的 IdP 发送了哪些属性和受众值的最快方式。

角色映射（可选）

你可以通过自定义 SAML 属性（例如 Prevu3DRole）分配 Prevu3D 组织级角色：

• Admin – 公司范围内的完全权限

• Guest – 无默认访问权限（必须在项目级别授予）

如果未提供角色属性，则应用默认角色。出于安全原因，我们建议将此设置为 Guest。

警告

如果启用了 SCIM，则角色分配应改为通过 SCIM 处理。

组映射（可选）

也可以将你 IdP 系统中的组映射到 Prevu3D 组，以简化你组织中人员的访问管理。以下步骤指导你完成组映射。

• 配置你的 IdP 通过 SAML 属性传递组成员身份。

• 在 SSO 选项卡上输入此属性。

• 在 Prevu3D 的 “Groups” 部分，点击 “Edit group” 并指定你 IdP 期望的 SAML 组值。

• 此映射在用户登录 Prevu3D Cloud 时应用于用户。如果用户已登录，他们应注销并重新登录以使访问更改生效。

注意

• 组映射在登录时应用。用户必须注销并重新登录以应用更新的访问权限。

• 确保该组被授予一些访问权限；有关更多信息，请参阅组部分。

警告

• 如果启用了 SCIM，则组创建和成员身份分配应改为通过 SCIM 处理。

SCIM 2.0 – 配置设置

Prevu3D 通过 **SCIM 2.0 协议（跨域身份管理系统）**支持用户和组配置。

前提条件

• 你的组织必须使用 Enterprise 计划。

• 你的 IdP 必须支持 SCIM（例如 Azure AD/Entra、Okta、JumpCloud）。

SCIM 启用的功能

• 用户配置 – 新用户会自动在 Prevu3D 中创建

• 用户取消配置 – 当用户在你的 IdP 中被禁用时，他们会被禁用或移除

• 组分配 – 组和角色可以从你的 IdP 集中管理

设置指南

1. 以组织管理员身份登录你的 Prevu3D 账户。

2. 转到设置选项卡

3. 从左侧菜单中选择 SSO 选项卡

4. 滚动到 SCIM Provisioning 部分并启用它。

   

5. 你将找到：

   • SCIM Base URL（Entra ID 用户，请参阅下面的警告）

   • Bearer Token

注意

出于安全或凭据轮换的需要，你也可以在需要时轮换 bearer token。

警告

使用 Entra ID (Azure AD) 配置 SCIM 时，你必须在 Prevu3D 提供的 SCIM Base URL 末尾追加 ?aadOptscim062020。

6. 在你的身份提供商（例如 Microsoft Entra ID）中：

   • 打开 Prevu3D 企业应用程序。

   • 启用 SCIM provisioning。

   • 输入从 SSO 选项卡获取的 SCIM Base URL 和 Bearer Token。

7. 为以下内容配置属性映射：

   • userName、givenName、familyName、email

   • 可选：groups、roles、active

8. 保存你的配置

   你的 IdP 现在将根据配置计划自动将用户和组与 Prevu3D 同步。

故障排除

现象	可能原因	应对方法
IdP 重定向回 Prevu3D 后登录未完成	SAML 断言中的受众值与 Service Provider Entity ID 不完全一致。你的 IdP 可能发送了缩短的或友好名称形式的值。	在你的 IdP 中，将 Audience / Identifier / Entity ID 字段设置为 SSO 选项卡上显示的确切值，包括完整的后缀。
用户在登录页面输入电子邮件和密码，但从未被转到 IdP	主登录表单仅适用于基于密码的账户。	让用户点击登录按钮下方的使用 SSO 登录，然后输入其工作电子邮件。
在使用 SSO 登录界面输入工作电子邮件后没有重定向	该电子邮件域未与你的 Prevu3D 组织关联。	请联系 support@prevu3d.com 配置你的电子邮件域。
在 IdP 完成身份验证后出现 {"statusCode":401,"message":"invalid_user_email_domain"}	原因相同：该用户的电子邮件域未与你的组织关联。	请联系 support@prevu3d.com 配置你的电子邮件域。
用户看到”会话已超时”并被要求重新输入电子邮件	这是在启用 SSO 之前创建的账户进行一次性账户关联流程中的正常环节。	让用户继续操作；这并非错误。请参阅现有用户与账户关联。
现有用户的账户关联未完成	关联需要用户现有的 Prevu3D 密码，而他们可能已不记得。	让他们通过忘记密码重置密码，或向 support@prevu3d.com 申请为你的域进行批量关联。
新账户上的姓名为空或不正确	在 SSO 选项卡上输入的 SAML Attribute Key 与你的 IdP 发送的属性名称不匹配。这些值区分大小写。	捕获 SAML 跟踪，查看 AttributeStatement 中的属性名称，并更新映射使其完全一致。
用户被分配了非预期的角色	未发送角色属性，因此应用了 Default Organization Role；或者角色属性值与某个 Prevu3D 角色不匹配。	核实 Role SAML Attribute Key 以及你的 IdP 发送的值，然后检查你的 Default Organization Role 设置。
组访问权限更改未生效	组映射仅在登录时应用。	让用户注销并重新登录。
在浏览器中直接打开 Service Provider Endpoint URL 返回 {"statusCode":500,"message":"Internal server error"}	这是预期行为。该端点仅接受 SAML POST 请求，不能在浏览器中直接打开。	这并不表示配置存在问题。请改为从登录页面或你的 IdP 登录来进行测试。

注意

如果问题仍未解决，请捕获一次未成功登录尝试的 SAML 跟踪，隐去其中的敏感值，并发送至 support@prevu3d.com。请附上断言中显示的受众值和属性名称 — 这可以让我们的团队一次性诊断出大多数问题。

定义

• IdP，身份提供商：指注册所有用户并支持连接到各种其他服务的系统。这是你组织、用户和组的真实来源。例如：Azure AD、JumpCloud……

• SP，服务提供商：指消费 SSO 信息的服务应用程序，在本例中为 Prevu3D Cloud。

• SSO，单点登录：指一种机制，允许用户从单个门户获取其凭据，并跨多个应用程序分发用户管理配置。

• SAML，安全断言标记语言：一种行业范围的协议，支持跨多个基于云的平台使用 SSO。

• SCIM，跨域身份管理系统：用于配置用户和组的协议。