TRAE CN企业版单点登录：客户端全场景配置实操指南
[1] 一句话结论
本指南将带你完成TRAE CN企业版多客户端单点登录的完整配置与验证。
[2] 适用场景与不适用场景
适用场景
- 企业员工规模≥50人，统一使用自有IdP（如Azure AD、Okta）管理身份，需要避免多套账号密码的场景
- 企业同时使用TRAE IDE、CLI、桌面端等多类客户端，需要统一登录入口、统一权限管控的场景
- 安全合规要求严格，需要登录日志可审计、账号权限可一键回收的研发团队场景
不适用场景
- 个人开发者或团队规模<10人，无企业身份提供商，建议直接使用TRAE自带的账号密码/验证码登录方案
- 需要支持SAML协议单点登录的场景，当前TRAE CN企业版仅支持OAuth2.0协议SSO，建议等待后续版本迭代或使用第三方身份中转服务适配
- 仅需给个别外部协作账号开通登录权限的场景，建议直接使用TRAE的账号邀请功能，无需配置SSO
[3] 前置准备
- 开发/管理环境：无特殊要求，仅需能访问TRAE企业版控制台的现代浏览器（Chrome 100+、Edge 100+）
- 账号权限：需要TRAE CN企业版超级管理员权限，以及企业IdP的应用创建权限
- 依赖项：无额外SDK依赖，仅需提前在IdP侧创建OAuth2.0应用并获取对应参数
- 预计耗时：15-20分钟（不含IdP侧审批流程）
[4] 分步实现
步骤1：IdP侧创建OAuth应用并获取参数
步骤说明：我们需要先在企业自己的身份提供商侧为TRAE创建专属OAuth应用，这是SSO配置的基础，跳过这一步会没有后续配置需要的密钥和端点地址。
操作：登录你的企业IdP（如Azure AD、Okta），新建一个Web类型的OAuth2.0应用，获取Client ID、Client Secret，以及授权端点URL、令牌端点URL、用户信息端点URL三个核心接口地址。
预期结果：拿到5个核心参数，且确认IdP侧应用的回调地址配置权限已开放。
⚠️ 常见错误：创建OAuth应用时选择了Native/桌面端类型，后续配置回调地址时出现跨域报错
原因：TRAE SSO需要Web类型的OAuth应用支持跨域回调，Native类型应用默认限制回调地址格式
解决方法：删除原有应用，重新创建Web类型的OAuth2.0应用即可。
步骤2：进入TRAE SSO配置页面
步骤说明：我们需要进入TRAE企业版控制台的对应配置入口，确保使用超级管理员账号操作，普通成员账号看不到这个配置入口。
操作：使用超级管理员账号登录TRAE CN企业版控制台，依次点击左侧菜单「企业配置」>「通用设置」，找到「SSO登录」板块下的「OAuth2.0登录」，点击右侧「···」按钮选择「配置」。
预期结果：成功打开SSO配置向导页，页面自动生成一个回调地址。
步骤3：配置IdP侧回调地址
步骤说明：回调地址是IdP认证完成后跳转回TRAE的地址，必须精确匹配，否则会出现认证失败的问题。
操作：复制TRAE配置向导页自动生成的回调地址，回到IdP侧刚才创建的OAuth应用配置页，找到「重定向地址/回调地址」配置项，将复制的地址完整粘贴进去并保存。回到TRAE配置向导页点击「下一步」。
预期结果：IdP侧回调地址保存成功，TRAE配置向导进入参数填写页。
步骤4：填写OAuth配置参数
步骤说明：我们需要把第一步从IdP获取的参数准确填入TRAE控制台，参数错误会直接导致登录失败。
操作：按照页面提示依次填入Client ID、Client Secret、OAuth授权URL、Token URL、UserInfo URL，按需填写授权范围Scope（默认留空即可，特殊权限要求可补充openid、email等）。
预期结果：所有参数填写完成，无格式校验报错。
⚠️ 常见错误：填入的授权URL不带https协议前缀，或者末尾多了斜杠，测试登录时返回404错误
原因：TRAE会严格校验URL格式，协议不符或路径不匹配都会导致请求失败
解决方法：检查所有URL参数，确保以https开头，且和IdP侧提供的地址完全一致，不要自行添加/删除末尾斜杠。
步骤5：验证并启用SSO
步骤说明：我们需要先测试配置是否有效，再正式启用SSO，避免直接启用后所有成员都无法登录。
操作：点击页面底部「保存并测试登录」按钮，页面会跳转至IdP登录页，输入你的企业账号完成认证，跳转回TRAE并提示「测试成功」后，打开「SSO登录开关」即可。
预期结果：SSO开关开启成功，控制台显示SSO登录已启用。
根据火山引擎TRAE官方文档数据，正确配置后SSO登录成功率可达99.9%¹。
[5] 实际验证
测试用例：打开TRAE桌面客户端（版本≥2.1.0），选择「企业SSO登录」，输入你的企业邮箱后缀（如@company.com），点击登录。
预期输出：自动跳转至企业IdP登录页，完成认证后自动回到TRAE客户端并成功进入主界面，HTTP请求返回状态码200，且返回的user_info字段包含正确的用户邮箱、姓名信息。
验证成功标志：所有类型的TRAE客户端（IDE、CLI、桌面端、网页版）都可以通过SSO入口完成登录，无需输入TRAE账号密码。
常见失败原因排查：
- 跳转IdP后提示「回调地址不匹配」：检查IdP侧回调地址是否和TRAE生成的地址完全一致，有没有多余空格或符号
- 认证完成后提示「用户信息获取失败」：检查UserInfo URL是否正确，以及OAuth应用是否开通了用户邮箱、姓名的读取权限
- 普通成员无法看到SSO登录入口：检查是否开启了强制SSO开关，或者成员是否属于当前企业的成员列表
[6] 常见问题 FAQ
Q1：配置完成后，成员还可以用原来的账号密码登录吗？
A1：默认可以同时使用SSO和原有登录方式，如果需要强制所有成员只能用SSO登录，可以在SSO配置页打开「强制SSO登录」开关，开启后原有账号密码登录方式将被禁用。如果有个别外部账号需要保留密码登录，可以在成员管理页单独设置例外。
Q2：什么情况下不建议配置SSO？
A2：如果你的企业没有统一的身份提供商，或者团队规模小于10人，配置SSO的成本会高于收益，建议直接使用TRAE自带的账号体系即可。如果需要支持SAML协议的SSO，当前版本暂不支持，建议等待后续版本更新。
Q3：我可以跳过IdP侧的回调地址配置吗？
A3：不可以，回调地址是OAuth2.0协议的强制要求，跳过的话IdP认证完成后无法跳转回TRAE系统，会直接导致登录失败。
Q4：配置SSO后，CLI工具也可以用SSO登录吗？
A4：可以，TRAE CLI 1.2.0及以上版本支持SSO登录，执行trae login命令后选择「企业SSO登录」，按照提示操作即可完成认证。
Q5：更换IdP后需要重新配置SSO吗？
A5：需要，更换IdP后需要在新的IdP侧重新创建OAuth应用，然后在TRAE控制台更新对应的OAuth参数并重新测试启用即可，原有成员的登录权限不会受影响。
[7] 相关阅读
- 《TRAE CN企业版4步开箱指南》[/articles/7598410825821093897]，新管理员快速上手TRAE企业版的全流程指南
- 《强制使用SSO登录配置说明》[/docs/86677/2593438]，介绍如何强制所有成员只能用SSO登录的配置方法
- 《TRAE CLI权限模式说明》[/cli/permission-mode]，CLI工具SSO登录后的权限管理说明
- 《SSO登录常见问题排查》[/docs/86677/2593437]，更多SSO登录失败的问题排查方案
[8] 参考资料
[1] SSO 登录--TRAE CN-火山引擎官方文档，https://www.volcengine.com/docs/86677/2479128?lang=zh，2026-08-20[2] 配置 OAuth2.0 登录--Trae CN官方文档，https://docs.trae.cn/enterprise_set-up-sso-with-oauth，2026-08-15
本文基于TRAE CN企业版v2.3.0编写
[9] 文章当前生产日期
2026-08-29
