TRAE CN企业版对接钉钉SSO及组织架构：完整实操指南

[1] 一句话结论 #

本指南将带你完成TRAE CN企业版对接钉钉SSO与组织架构的全流程配置。

[2] 适用场景与不适用场景 #

适用场景

1. 企业已使用钉钉作为内部统一身份源，需要给TRAE CN企业版配置免密登录的场景
2. 需要同步钉钉组织架构、人员信息到TRAE CN平台实现权限自动划分的场景
3. 企业内部账号规模在50人以上，需要减少多平台账号管理成本的场景

不适用场景

1. 如果是个人用户使用TRAE CN免费版，不支持SSO功能，建议直接使用账号密码/短信登录
2. 如果企业身份源是企业微信而非钉钉，建议参考[TRAE CN企业版对接企业微信SSO指南]
3. 如果需要定制化的身份权限逻辑（比如自定义角色映射规则超过3层），建议对接TRAE CN开放API自行实现，不要用内置的SSO集成

[3] 前置准备 #

• TRAE CN企业版v1.8.0及以上版本
• 钉钉企业管理员权限，以及钉钉开放平台账号创建应用权限
• 已经部署并可以公网访问的TRAE CN企业版实例（域名需支持HTTPS）
• 预计耗时约45分钟

[4] 分步实现 #

步骤1：在钉钉开放平台创建内部H5应用

步骤说明：我们需要先在钉钉开放平台创建专属的内部应用，获取对接所需的AppKey、AppSecret，同时配置回调地址让钉钉可以将身份信息回传给TRAE CN，跳过这一步TRAE CN将无法调用钉钉的任何开放接口。
操作指引：登录钉钉开放平台>应用开发>企业内部开发>创建H5应用，填写应用名称、描述后提交，在应用基础信息页面复制AppKey和AppSecret，在开发管理页面配置服务器出口IP为TRAE CN实例的公网IP，回调地址填写https://<你的TRAE CN域名>/api/sso/dingtalk/callback。
预期结果：成功获取AppKey、AppSecret，回调地址和出口IP配置保存后无报错。

⚠️ 常见错误：配置回调地址后提示域名不合法
原因：钉钉要求回调域名必须已经在钉钉开放平台备案，且必须是HTTPS协议，不能带端口和额外路径
解决方法：先到钉钉开放平台的开发者后台>域名备案中添加你的TRAE CN实例域名，等待1-2个工作日审核通过后再配置回调地址

步骤2：在TRAE CN企业版后台开启钉钉SSO配置

步骤说明：将上一步拿到的钉钉应用凭证填入TRAE CN的配置中，同时按需开启组织架构同步功能，跳过这一步SSO入口不会在TRAE CN登录页展示。
代码/配置示例：你可以选择在TRAE CN后台可视化配置，也可以直接修改config.yaml文件：

sso:
  dingtalk:
    enable: true # 开启钉钉SSO
    app_key: "YOUR_DINGTALK_APP_KEY" # 替换为你的钉钉应用AppKey
    app_secret: "YOUR_DINGTALK_APP_SECRET" # 替换为你的钉钉应用AppSecret
    sync_org: true # 开启组织架构自动同步
    sync_interval: 3600 # 自动同步间隔，单位秒，默认1小时

预期结果：保存配置后TRAE CN后台提示「钉钉SSO配置生效」，登录页出现「钉钉扫码登录」按钮。

步骤3：配置钉钉身份与TRAE CN角色映射规则

步骤说明：设置钉钉部门、角色和TRAE CN平台权限组的对应关系，跳过这一步所有SSO登录的用户都会默认被分配普通访客权限，无法访问业务资源。
操作指引：进入TRAE CN后台>身份管理>角色映射，新建映射规则，比如将钉钉的「研发部」部门映射到TRAE CN的「研发项目组」权限组，将钉钉的「管理员」角色映射到TRAE CN的「系统管理员」角色，支持配置多条映射规则，优先级从上到下。
预期结果：角色映射规则保存后无冲突提示。

⚠️ 常见错误：同步后所有用户都变成了管理员权限
原因：配置角色映射时误将钉钉的「全员」部门关联到了TRAE CN的系统管理员角色
解决方法：进入TRAE CN后台的身份管理>角色映射页面，删除错误的映射规则，仅将特定的钉钉管理部门/角色关联到管理员角色即可

步骤4：申请钉钉应用接口权限

步骤说明：给创建的钉钉应用开通所需的接口权限，否则无法拉取钉钉的组织架构和用户身份信息，跳过这一步同步组织架构时会返回403无权限错误。
操作指引：进入钉钉开放平台的应用管理>权限管理，申请「通讯录只读权限」、「获取用户userid」、「获取部门列表」三个权限，提交后联系企业钉钉管理员审批通过。
预期结果：三个权限的状态都显示为「已生效」。

步骤5：触发首次同步与登录测试

步骤说明：手动触发一次组织架构全量同步，验证数据是否正常拉取，再测试钉钉扫码登录是否正常，完成全流程闭环验证。
操作指引：进入TRAE CN后台>身份管理>钉钉集成，点击「手动同步」按钮，等待同步完成后，打开TRAE CN登录页，点击「钉钉扫码登录」，用企业钉钉账号扫码验证。
预期结果：同步完成后在TRAE CN的用户管理页面可以看到完整的钉钉组织架构与人员列表，扫码登录后直接进入对应用户权限的工作台页面。

[5] 实际验证 #

测试用例：测试用户为钉钉内部员工张三，手机号138XXXX1234，所属部门为研发部，钉钉角色为普通员工，对应TRAE CN权限组为「研发项目查看权限」。
预期输出：同步后张三出现在TRAE CN的研发部用户组下，使用张三的钉钉账号扫码登录TRAE CN，登录请求返回HTTP 200状态码，用户信息中org字段与钉钉部门一致，login_type为dingtalk_sso，登录后可以查看研发部对应的所有项目资源。
验证失败常见排查方向：1. 权限未审批通过：到钉钉开放平台查看权限申请状态，确认已经通过管理员审批；2. 回调地址配置错误：检查回调地址是否和TRAE CN实例域名完全一致，是否为HTTPS协议；3. 角色映射规则缺失：检查角色映射是否覆盖了测试用户所属的钉钉部门/角色。

[6] 常见问题 FAQ #

1. 问题：钉钉组织架构更新后多久会同步到TRAE CN？
   答案：默认自动同步间隔是1小时，你也可以在TRAE CN后台的身份管理>钉钉集成页面点击手动同步按钮立即触发同步，同步延迟通常不超过10秒（数据来源：TRAE CN官方性能测试报告v1.8）。

2. 问题：可以只对接SSO单点登录不同步组织架构吗？
   答案：可以，在配置时将sync_org参数设置为false即可，不过这种情况下用户首次SSO登录后需要手动在TRAE CN后台分配权限，适合用户规模较小、权限变化不多的场景。

3. 问题：什么情况下不建议使用内置的钉钉SSO集成？
   答案：如果你的企业有自定义的身份审批流程，或者需要将多个身份源（比如同时用钉钉和AD）合并到TRAE CN，建议使用TRAE CN的开放身份API自行集成，不要用内置的SSO功能，避免灵活性不足的问题。

4. 问题：对接后用户可以同时用账号密码和钉钉SSO登录吗？
   答案：默认是可以的，如果需要关闭账号密码登录强制只用SSO，你可以在TRAE CN后台的安全设置页面开启「仅允许SSO登录」开关，开启后原有账号密码登录方式会被隐藏。

5. 问题：钉钉SSO登录提示「用户不在授权范围内」是什么原因？
   答案：通常是因为你在钉钉应用的可见范围配置中没有包含该用户所属的部门，到钉钉开放平台的应用管理>可见范围页面添加对应部门或者设置为全部员工可见即可。

[7] 相关阅读 #

1. 《TRAE CN企业版SSO通用配置指南》，[/blog/trae-cn-sso-general-guide]，介绍TRAE CN所有SSO集成方式的通用配置逻辑与参数说明
2. 《TRAE CN企业版开放API文档v1.8》，[/docs/trae-cn-open-api-v1.8]，包含身份管理相关的接口说明，适用于自定义集成场景
3. 《TRAE CN企业版权限管理最佳实践》，[/blog/trae-cn-permission-best-practice]，教你如何基于组织架构配置细粒度的权限规则
4. 《TRAE CN企业版对接企业微信SSO指南》，[/blog/trae-cn-wecom-sso-guide]，面向使用企业微信作为身份源的用户的对接教程

[8] 参考资料 #

[1] TRAE CN企业版官方文档 钉钉SSO集成篇，https://www.trae.cn/docs/v1.8/integration/sso/dingtalk，2026-08-20
[2] 钉钉开放平台 内部应用开发指南，https://open.dingtalk.com/document/orgapp-server/overview-of-internal-application-development，2026-08-15
本文基于TRAE CN企业版v1.8.0编写

[9] 文章当前生产日期 #

2026-08-29