> ## Documentation Index
> Fetch the complete documentation index at: https://docs.counso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置 SAML 单点登录

SAML 单点登录（SSO）让成员通过组织的身份提供商（IdP）登录工作区。请由同时有权限访问工作区设置和 IdP 管理后台的管理员配置并测试连接。

## 开始前

准备一位 IdP 管理员，以及邮箱和姓名属性完整的测试账号。配置 IdP 时保留工作区的 SSO 设置页，因为其中显示的服务参数必须与 IdP 中的设置一致。测试通过前，管理员应保留可用的恢复登录方式。

## 创建 SAML 应用

1. 在工作区管理区域打开 **People & Security（人员与安全）**，再进入 **Single Sign-On（单点登录）**。选择启用 SSO 的设置项，让工作区显示 SAML 参数。
2. 记录页面显示的 **ACS（断言消费者服务）URL** 和 **Entity ID / Audience URI（实体标识符/受众 URI）**。在 IdP 中新建 SAML 2.0 应用，并准确填入这些值。
3. 在 IdP 中设置应用名称和工作区提供的服务参数，并配置用于识别用户的必需属性：
   * **Email（邮箱，`email`）**：成员在工作区使用的邮箱。
   * **First name（名，`given_name`）**：映射 IdP 中的名字字段。
   * **Last name（姓，`family_name`）**：映射 IdP 中的姓氏字段。
   * **Email verified（邮箱已验证，`email_verified`）**：填写工作区 SAML 设置要求的值。

不同 IdP 的属性标签和 Schema 名称可能不同。按 IdP 所需格式映射，并遵循工作区显示的要求。例如，部分 IdP 会用 Name Identifier Claim 表示邮箱；请确认最终邮箱与成员在工作区使用的邮箱一致。

4. 从 IdP 应用复制 **Single Sign-On URL（单点登录地址）** 和 **X.509 certificate（X.509 证书）**。
5. 回到工作区的 SSO 设置页，填写这些 IdP 参数，然后选择 **Create SAML Configuration（创建 SAML 配置）**。

## 强制启用前先测试

在隐私窗口中用专门的测试账号登录，确认身份验证进入预期工作区，且成员邮箱和姓名识别正确。如果界面提供自动加入工作区选项，先确认它符合组织的域名策略。

测试成功后，管理员可以为整个工作区强制使用 SAML。强制启用可能会让仍使用其他登录方式的成员退出，因此要提前说明如何通过 IdP 登录，并为管理员保留恢复途径。

## 可选：由 IdP 发起登录

有些组织会从 IdP 发起登录，而不是先打开工作区。只有当工作区的 SSO 配置支持这种方式时才使用。先与身份团队评估相关安全影响；如需启用，请联系工作区支持人员为对应连接打开此流程。否则请使用从工作区开始的标准登录流程。

## 故障排查

* 对照工作区显示的准确值，检查 IdP 中的 ACS URL 和 Audience。
* 确认邮箱 Claim 与成员在工作区使用的邮箱一致，且必需的姓名和验证属性均已填写。
* 确认证书和登录地址来自正确的 IdP 应用。
* 在测试账号和管理员恢复登录方式均可用前，不要强制启用 SSO。