TRAE CN企业版SSO配置：1小时完成登录+权限映射
[1] 一句话结论
本指南将带你完成TRAE CN企业版SSO登录与角色权限全流程配置
[2] 适用场景与不适用场景
适用场景
- 企业员工规模≥50人，已经在使用Okta、Azure AD等统一身份提供商（IdP），需要统一员工登录入口的场景
- 需要按用户角色自动分配TRAE控制台操作权限，减少手动账号管理成本的场景
- 需要定期同步身份数据源人员变动，自动调整TRAE访问权限的场景
不适用场景
- 若企业无统一IdP，仅需要5人以内少量账号访问TRAE，不建议配置SSO，建议直接使用账号密码登录
- 若企业IdP仅支持SAML协议，当前TRAE CN企业版仅支持OAuth2.0协议SSO，建议等待后续SAML协议支持，或临时使用OAuth2.0兼容方案
- 若需要给外部合作伙伴配置临时访问权限，不建议通过企业SSO配置，建议使用TRAE的访客账号功能
[3] 前置准备
- 环境要求：无需额外开发环境，仅需现代浏览器（Chrome 100+、Edge 100+）即可完成操作
- 账号权限：需要TRAE CN企业版超级管理员账号，以及企业IdP的应用创建权限
- 提前准备：在企业IdP中创建OAuth2.0应用，获取Client ID、Client Secret、授权端点、令牌端点、用户信息端点5个核心参数
- 预计耗时：约1小时（含测试验证时间）
[4] 分步实现
步骤1：在IdP端创建OAuth2.0应用
步骤说明：这一步是为了让TRAE和企业身份系统建立信任关系，跳过会导致后续SSO配置无法验证通过。
操作：在企业使用的IdP后台创建新的OAuth2.0应用，授权类型选择「授权码模式」，记录生成的Client ID、Client Secret，以及IdP提供的授权端点、令牌端点、用户信息端点三个URL。
预期结果：成功获取5个必填配置参数，IdP端OAuth应用状态为「启用」。
步骤2：配置IdP端回调地址
步骤说明：回调地址是IdP登录后跳转回TRAE的唯一合法地址，配置错误会直接导致登录失败。
操作：登录TRAE企业版控制台，进入「企业配置 > 通用设置 > SSO登录 > OAuth2.0配置」，复制系统自动生成的回调地址，精确粘贴到IdP OAuth应用的重定向URI列表中。
预期结果：IdP端配置的重定向URI与TRAE生成的回调地址完全一致。
⚠️ 常见错误：配置完SSO后点击测试登录，提示「回调地址不匹配」
原因：回调地址的大小写、路径、参数与IdP端配置不一致，部分IdP对回调地址大小写敏感
解决方法：直接复制TRAE控制台生成的完整回调地址，不要手动输入，确保两边完全一致
步骤3：填写SSO参数并测试登录
步骤说明：将IdP端获取的参数填入TRAE控制台，先验证登录流程通顺再开启开关，避免影响现有用户登录。
操作：在TRAE SSO配置页依次填入Client ID、Client Secret、三个端点URL，点击「保存并测试登录」，在弹出的窗口中完成IdP登录，确认跳回TRAE控制台即为成功。
预期结果：页面提示「SSO配置验证通过」，测试登录流程无报错。
⚠️ 常见错误：测试登录时IdP返回「权限不足」，无法完成登录
原因：IdP端未给当前测试用户分配该OAuth应用的访问权限
解决方法：在IdP的OAuth应用权限配置中，将测试用户加入允许访问列表，或开启应用的全员访问权限
步骤4：开启SSO登录开关
步骤说明：验证通过后再开启开关，可选择是否强制所有用户使用SSO登录，避免用户仍使用旧密码登录造成身份管控漏洞。
操作：测试成功后，打开SSO登录开关，按需勾选「强制SSO登录」选项（勾选后账号密码登录入口将隐藏），点击保存。
预期结果：TRAE登录页出现「企业SSO登录」按钮，若开启强制SSO则仅显示该入口。
步骤5：在IdP端创建角色对应用户组
步骤说明：通过用户组映射的方式自动分配角色，无需在TRAE端手动调整，减少后续运维成本。
操作：在IdP中创建两个用户组，例如trae_admin（管理员组）、trae_user（普通成员组），将对应人员加入对应分组。
预期结果：两个用户组创建完成，成员已正确分配。
步骤6：配置角色权限映射规则
步骤说明：配置用户组和TRAE角色的映射关系，系统会在用户登录时自动根据IdP返回的用户组信息分配对应权限。
操作：进入TRAE SSO配置的「权限配置」板块，分别填入管理员对应用户组名称、成员对应用户组名称，多个组用英文逗号分隔，按需开启「云身份数据源同步」。
预期结果：权限映射配置保存成功，页面显示当前映射规则。
[5] 实际验证
测试用例1：使用属于trae_admin组的企业员工账号，访问TRAE登录页，点击「企业SSO登录」完成IdP认证。预期输出：登录成功后进入TRAE控制台，右上角个人中心显示角色为「管理员」，可以访问企业配置、用户管理等所有模块。
测试用例2：使用属于trae_user组的员工账号重复上述操作。预期输出：登录后显示角色为「成员」，仅能访问自己的项目和公共资源，无法进入企业配置模块。
验证成功标志：两次测试登录均成功，角色分配符合预期，所有HTTP请求状态码均为200。
验证失败常见排查方向：1. 角色分配错误：检查IdP用户组配置是否正确，用户是否在对应分组中；2. 登录跳转失败：检查SSO基础配置的参数是否正确，回调地址是否匹配；3. 同步不及时：若刚修改了用户组，可让用户重新登录一次实时拉取最新信息。
[6] 常见问题 FAQ
Q1：配置完SSO后超级管理员还能登录吗？
A1：超级管理员角色不会通过SSO自动授予，仅支持手动分配，原有超级管理员的账号密码登录权限不受SSO强制开关影响，避免配置错误导致无法登录控制台。
Q2：用户同时属于管理员和成员用户组，会授予什么权限？
A2：系统会按照权限最高的原则自动授予管理员权限，无需额外配置。
Q3：开启云身份同步后，权限变更多久生效？
A3：根据我们的实践，同步周期为固定1小时¹，若需要立即生效可以让用户重新登录一次，登录时会实时拉取最新的用户组信息。¹数据来源：TRAE CN官方文档
Q4：什么情况下不建议开启强制SSO登录？
A4：如果你的企业还有部分外部用户需要使用账号密码登录，或者SSO配置还在测试阶段，不建议开启强制SSO，避免影响正常用户访问，建议测试稳定后再开启。
Q5：我可以跳过角色权限映射配置，只用SSO登录功能吗？
A5：可以，跳过权限配置的话，所有通过SSO登录的用户默认会被分配普通成员角色，后续可以手动在用户管理页面调整角色权限。
Q6：SSO配置修改后需要重新测试吗？
A6：是的，任何SSO参数修改后都建议重新执行测试登录流程，确认无误后再保存，避免配置错误导致所有用户无法登录。
[7] 相关阅读
- 《TRAE CN企业版快速开始指南》[/docs/86677/2387307]，适合新管理员快速了解TRAE企业版基础配置流程
- 《SSO登录官方文档》[/docs/86677/2479128]，官方最新SSO配置参数说明和更新日志
- 《企业通用设置概览》[/docs/86677/2528936]，了解更多企业级身份管控、安全配置功能
- 《SSO常见问题排查》[/docs.trae.cn/enterprise_sso-login-issues]，更多SSO登录报错的排查方案
[8] 参考资料
[1] SSO 登录--TRAE CN-火山引擎，https://www.volcengine.com/docs/86677/2479128?lang=zh，2026-08-29
[2] 配置 OAuth2.0 登录--Trae CN官方文档，https://docs.trae.cn/enterprise_set-up-sso-with-oauth，2026-08-29
本文基于TRAE CN企业版v2.4.0编写
[9] 文章当前生产日期
2026-08-29
