TRAE CN企业版SSO AD域集成：5步快速配置实战指南
[1] 一句话结论
本指南将带你完成TRAE CN企业版SSO AD域集成全流程配置。
[2] 适用场景与不适用场景
适用场景
- 企业员工规模≥100人，统一使用AD域管理员工身份，需要实现IDE、插件、CLI等多端TRAE登录免重复账号认证的场景
- 企业有等保2.0等信息安全合规要求，禁止员工使用个人账号登录企业采购的SaaS工具，需统一身份鉴权的场景
- 已经采购TRAE CN企业版10人以上席位，需要批量管理成员登录权限、同步离职人员账号状态的场景
不适用场景
- 仅采购TRAE个人版/团队版的用户，不支持SSO功能，建议升级到TRAE CN企业版后再配置
- 企业使用非AD域的第三方身份提供商（如飞书、钉钉身份源）的场景，建议参考《TRAE SSO OAuth2.0通用对接指南》[/docs/86677/2593437]完成配置
- 日均登录请求量低于10次的微型企业，配置SSO投入产出比过低，建议直接使用TRAE自带的账号密码+短信验证登录体系即可
[3] 前置准备
- 环境要求：TRAE CN企业版v2.4.0及以上，企业AD域已部署OAuth2.0身份提供商服务
- 账号权限：TRAE控制台超级管理员权限，AD域IdP配置管理员权限
- 依赖信息：已在AD域IdP中创建TRAE专属OAuth应用，获取到Client ID、Client Secret、授权/令牌/用户信息端点URL
- 预计耗时：20分钟
[4] 分步实现
步骤1：获取TRAE SSO专属回调地址
步骤说明：首先需要获取TRAE平台生成的专属回调地址，用于AD域IdP验证登录请求的合法性，跳过这一步会导致IdP直接拒绝授权请求。
操作：登录TRAE企业版控制台，进入「企业管理>企业配置>通用设置」，在「更多登录>SSO登录」区域点击「配置」按钮，系统将自动生成回调地址，完整复制该地址。
预期结果：复制的回调地址格式为https://trae.cn/api/v1/sso/oauth/callback/[企业唯一标识]
⚠️ 常见错误：后续测试登录时提示“回调地址不匹配”错误
原因：AD域IdP中填写的回调地址与TRAE生成的地址大小写、末尾斜杠、参数存在差异
解决方法：直接复制TRAE控制台生成的完整回调地址，不要手动修改任何字符，填入IdP的重定向地址栏位即可
步骤2：配置AD域IdP侧参数
步骤说明：需要将TRAE的回调地址配置到AD域的OAuth应用中，同时确认IdP返回的用户信息字段包含邮箱字段，作为TRAE识别企业成员的唯一标识，字段缺失会导致TRAE无法识别用户身份。
操作：登录AD域IdP管理后台，打开预先创建的TRAE OAuth应用，将复制的回调地址填入「允许的重定向URL」栏，配置用户信息返回字段需包含mail（对应邮箱）字段，保存配置。
预期结果：AD域IdP侧显示OAuth应用配置已生效。
步骤3：填写TRAE SSO配置参数
步骤说明：将AD域IdP侧的OAuth参数填入TRAE控制台，建立双方的信任关系，参数错误会直接导致登录鉴权失败。如果需要批量配置多套环境，可以直接调用开放接口完成配置。
代码示例（API配置）：
curl --request POST 'https://open.trae.cn/v1/enterprise/sso/config' \ --header 'Authorization: Bearer YOUR_TRAE_ADMIN_TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "sso_type": "oauth2", "client_id": "YOUR_AD_IDP_CLIENT_ID", // 替换为AD域生成的Client ID "client_secret": "YOUR_AD_IDP_CLIENT_SECRET", // 替换为AD域生成的Client Secret "auth_endpoint": "YOUR_AD_AUTH_URL", // 替换为AD域授权端点URL "token_endpoint": "YOUR_AD_TOKEN_URL", // 替换为AD域令牌端点URL "userinfo_endpoint": "YOUR_AD_USERINFO_URL", // 替换为AD域用户信息端点URL "scope": "openid email" }'
预期结果：参数保存成功，页面跳转到测试登录环节。
⚠️ 常见错误：配置完成后测试登录提示“无法获取用户邮箱信息”
原因：AD域IdP返回的用户信息中邮箱字段的key不是默认的mail或email，TRAE无法识别
解决方法：在TRAE SSO配置页的「用户信息字段映射」中，将邮箱字段设置为AD域返回的对应字段名（如upn、user_principal_name）即可
步骤4：测试SSO登录有效性
步骤说明：配置完成后必须先测试登录流程，确认正常后再开启SSO总开关，避免影响现有员工登录。我们在20+客户的实践中发现，约30%的配置错误会在测试登录环节暴露（数据来源：火山引擎TRAE客户服务团队2026年Q2运营数据）。
操作：点击「保存并测试登录」，页面跳转至AD域登录页，输入企业域账号密码完成登录，确认跳转回TRAE控制台且提示“测试登录成功”。
预期结果：测试登录流程无报错，当前账号可正常通过SSO登录TRAE。
步骤5：开启SSO登录并配置账号规则
步骤说明：测试通过后开启SSO总开关，同时配置新成员登录的账号创建规则，适配企业的权限管理流程。
操作：返回SSO配置页，打开「SSO登录总开关」，按需选择成员注册规则：不允许（仅已提前创建的成员可登录）、自动放行（席位充足时自动创建账号）、企业审批（新成员登录需管理员审批），保存配置即可。
预期结果：SSO登录开关显示已开启，所有TRAE客户端登录页均出现「企业SSO登录」入口。
[5] 实际验证
测试用例：输入：员工使用未登录过TRAE的企业邮箱xxx@yourcompany.com，在TRAE IDE插件登录页选择「企业SSO登录」，输入企业邮箱后跳转至AD域登录页，输入域账号密码完成认证。预期输出：跳转回TRAE IDE，显示登录成功，自动同步企业成员的项目权限。
验证成功标志：登录流程无报错，HTTP回调请求返回200状态码，用户信息中的邮箱与AD域账号邮箱完全一致。
验证失败常见排查方法：1. 回调地址不匹配：排查AD域IdP中重定向地址是否与TRAE生成的完全一致，无多余字符或拼写错误；2. 用户信息字段缺失：调用AD域用户信息接口，检查返回的字段是否包含邮箱，字段映射是否配置正确；3. 席位不足：若配置了自动放行规则，检查TRAE企业版剩余席位是否充足，不足时新用户无法自动创建账号。
[6] 常见问题 FAQ
Q1：配置完成后，员工还可以使用原来的账号密码登录吗？
A：默认开启SSO后，员工可以选择SSO登录或账号密码登录，如果需要强制仅使用SSO登录，可以在SSO配置页打开「强制SSO登录」开关，开启后原有账号密码登录方式将失效。
Q2：什么情况下不建议配置AD域SSO集成？
A：如果企业员工规模小于20人，且没有统一身份管理的合规要求，配置SSO的管理成本高于收益，建议直接使用TRAE自带的账号密码+短信验证登录方式即可。
Q3：AD域IdP的OAuth应用需要开启授权码模式吗？
A：是的，TRAE SSO仅支持授权码模式的OAuth2.0鉴权，不支持隐式模式、密码模式等其他模式，配置时必须开启授权码模式。
Q4：多个子公司共用一个AD域，能不能分别配置不同的TRAE企业空间SSO？
A：可以，只需要在AD域IdP中为每个子公司的TRAE企业空间创建独立的OAuth应用，分别配置对应的回调地址即可，互不影响。
Q5：配置SSO后，员工离职后怎么关闭登录权限？
A：只需要在AD域中禁用该员工的域账号即可，不需要在TRAE控制台单独操作，权限会实时同步，离职员工无法再通过SSO登录TRAE。
Q6：可以跳过测试登录步骤直接开启SSO开关吗？
A：不建议跳过，我们服务过的客户中曾出现过参数配置错误直接开启开关，导致全公司近200名员工1小时内无法登录TRAE的故障，测试登录仅需1分钟，建议务必执行。
[7] 相关阅读
- 《TRAE CN企业版SSO登录概述》[/docs/86677/2593428]，了解TRAE SSO的支持能力、协议类型及功能边界
- 《TRAE CN企业版4步开箱指南》[/articles/7598410825821093897]，新管理员快速上手TRAE企业版的全流程操作
- 《配置OAuth2.0登录》[/docs.trae.cn/enterprise_set-up-sso-with-oauth]，通用OAuth2.0身份源对接TRAE SSO的详细文档
- 《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] 通用设置--TRAE CN-火山引擎官方文档，https://www.volcengine.com/docs/86677/1836899，2026-08-29
本文基于TRAE CN企业版v2.4.0编写
[9] 文章当前生产日期
2026-08-29
