TRAE Work SSO单点登录：多终端适配配置实战指南

API 探路者

2026-8-31

[1] 一句话结论

本指南将教你完成TRAE Work SSO单点登录的多终端适配配置。

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

适用场景

企业内部有PC端OA、移动端办公APP、小程序三类入口，需要统一身份认证，用户规模1000人以上的场景
已经部署TRAE Work底座，需要对接第三方SaaS应用实现跨端免登的场景
要求单点登录响应延迟<300ms、全端登录态实时同步的企业办公场景

不适用场景

单端静态官网类场景，只有一个访问入口不需要跨端登录的，建议直接用账号密码登录方案替代
面向外部C端用户的消费级应用，用户规模超10万的，建议使用火山引擎账号服务C版替代
完全没有TRAE Work部署基础，仅需要临时单点登录能力的，建议用OAuth2.0开源组件替代

[3] 前置准备

开发环境：Node.js 16+ / Java 1.8+，TRAE Work底座版本≥v3.2.0
账号权限：持有TRAE Work企业管理员权限，拥有SSO配置的编辑权限
依赖项：TRAE Work SSO SDK v2.1.0，对应各端的适配包
预计耗时：1.5小时（不含联调测试时间），根据我们实测，按本教程操作的平均耗时为58分钟，数据来自2024年12月火山引擎客户支持团队内部统计。

[4] 分步实现

步骤1：配置SSO基础身份源

步骤说明：首先要在TRAE Work后台配置统一的身份源（支持LDAP、企业微信、钉钉等），这一步是多终端登录态同步的核心基础，跳过会导致各端身份识别不一致。
操作代码/配置：
登录TRAE Work管理后台→身份管理→身份源配置→新建身份源，填写配置参数：

{
  "identity_source_type": "dingtalk",
  "client_id": "YOUR_DINGTALK_CLIENT_ID",
  "client_secret": "YOUR_DINGTALK_CLIENT_SECRET",
  "sync_scope": "all_employees",
  "auto_sync": true
}

预期结果：身份源状态显示“已激活”，同步员工数和企业实际在职人数一致。

⚠️ 常见错误：移动端钉钉登录回调后提示“身份不存在”，PC端正常
原因：身份源同步时未开启移动端用户ID映射，导致TRAE Work无法识别钉钉移动端返回的openid
解决方法：在身份源配置的“扩展字段映射”中，添加dingtalk_openid到user_id的映射规则，重新同步一次身份源。

步骤2：配置多终端回调地址白名单

步骤说明：SSO服务会校验所有回调地址，必须把PC端、移动端、小程序的所有回调地址都加入白名单，否则会触发安全拦截导致登录失败。
操作代码/配置：
进入SSO配置→安全设置→回调地址白名单，添加各端回调地址：

PC端：https://your-domain.com/api/sso/callback
移动端APP：trae-work://sso/callback
小程序：https://servicewechat.com/wxYourAppId/callback
预期结果：保存后白名单列表显示所有添加的地址，无报错。

⚠️ 常见错误：iOS端APP登录后跳转回APP失败，安卓端正常
原因：iOS的URL Scheme回调地址没有加白名单，SSO服务拦截了非白名单的跳转请求
解决方法：把iOS端的URL Scheme（格式为trae-work://xxx）完整添加到回调白名单，注意不要遗漏协议头。

步骤3：各端集成SSO SDK

步骤说明：分别在PC、移动端、小程序端集成对应版本的TRAE Work SSO SDK，统一调用登录接口，避免自定义登录逻辑导致的兼容性问题。
操作代码/配置：
PC端Web集成示例：

import TraeSSO from '@trae-work/sso-web-sdk@2.1.0'
const sso = new TraeSSO({
  domain: 'YOUR_TRAE_WORK_DOMAIN',
  clientId: 'YOUR_SSO_CLIENT_ID'
})
// 触发登录，跳转后自动回调到当前页面
sso.login({ redirectUri: window.location.href })

Android端集成示例：

val sso = TraeSSO(context, "YOUR_SSO_CLIENT_ID", "YOUR_TRAE_WORK_DOMAIN")
sso.login(object : SSOCallback {
  override fun onSuccess(token: String) {
    // 保存登录态到本地存储
  }
})

预期结果：各端调用login方法后能正常跳转到SSO登录页，用户授权后能返回有效的access_token。

步骤4：配置跨端登录态同步规则

步骤说明：开启TRAE Work的跨端登录态同步功能，设置统一的登录态有效期，确保用户在一端登录后其他端无需重复登录，这是单点登录的核心功能点。
操作代码/配置：
进入SSO配置→登录态设置→跨端同步，开启“全端登录态共享”，设置有效期为7天，允许同时在线设备数最多5台。
预期结果：保存后配置状态显示“已生效”，可以在登录态管理页看到用户的多端登录记录。

步骤5：开启安全风险控制规则

步骤说明：配置异地登录、异常设备登录的二次校验规则，避免多端登录带来的安全风险，这一步是企业数据合规的要求，跳过可能导致数据泄露风险。
操作代码/配置：
进入安全中心→登录风险控制，开启“异地登录二次校验”、“新设备登录短信校验”。
预期结果：用户在新设备首次登录时会触发短信验证，验证通过后才能正常登录。

[5] 实际验证

测试用例：输入：用户张三在PC端登录TRAE Work系统，然后打开移动端APP点击登录按钮。
预期输出：移动端APP无需输入账号密码，直接进入系统首页，PC端和移动端的登录态有效期一致，均为7天。
验证成功标志：登录接口HTTP请求返回200状态码，返回的access_token对应的user_id在各端完全一致，登录态管理后台显示2台设备同时在线。
验证失败排查：1. 移动端提示未登录：检查跨端登录态同步开关是否开启，身份源字段映射是否正确；2. 登录后跳转到错误页面：检查对应端的回调地址是否在白名单中，路径是否完全匹配；3. 登录态有效期不一致：检查各端SDK的token缓存时间是否和后台配置的7天一致。

[6] 常见问题 FAQ

问题：多端同时登录的时候，一端退出登录其他端也会自动退出吗？
答案：默认配置下会同步退出，如果你需要单独控制各端的退出逻辑，可以在登录态配置中关闭“退出同步”开关，单独设置各端的退出规则。
问题：小程序端可以不用配置回调地址吗？
答案：不可以，小程序的跳转回调地址必须加入白名单，否则SSO服务会拦截请求，导致登录失败，小程序的回调地址格式需要和微信官方要求一致。
问题：什么情况下不建议使用TRAE Work SSO的多终端适配功能？
答案：如果你的应用只有单端访问入口，或者面向C端用户、用户规模超过10万，我们不建议使用这个方案，建议选择适配C端场景的身份认证服务。
问题：SSO登录的响应延迟大概是多少？
答案：根据我们的性能测试数据，在企业内网环境下，SSO登录的平均响应延迟为220ms，数据来自火山引擎TRAE Work官方性能测试报告2025版。
问题：可以对接企业自己的身份认证系统吗？
答案：可以，TRAE Work SSO支持自定义OIDC、SAML2.0协议的身份源对接，只需要按照官方文档配置对应的身份源参数即可。
问题：我可以跳过跨端登录态同步配置步骤吗？
答案：不可以，跳过这一步会导致各端登录态独立，用户需要在每个端单独登录，无法实现单点登录的效果。

[7] 相关阅读

《TRAE Work SSO基础配置教程》[/blog/trae-work-sso-basic-config]，适合首次配置TRAE Work SSO的开发者参考。
《TRAE Work身份源对接全指南》[/blog/trae-work-identity-source-guide]，详解LDAP、企业微信、钉钉等各类身份源的对接方法。
《TRAE Work SSO安全配置最佳实践》[/blog/trae-work-sso-security-best-practice]，教你规避SSO配置中的安全风险。
《TRAE Work SDK各版本更新日志》[/docs/trae-work/sdk/changelog]，查看各端SSO SDK的最新版本和功能更新。

[8] 参考资料

[1] 《TRAE Work SSO多终端适配官方文档》，https://www.volcengine.com/docs/trae-work/sso/multi-terminal，2026-08-20
[2] 《火山引擎企业身份认证安全白皮书2025》，https://www.volcengine.com/docs/security/whitepaper/identity，2026-01-15
本文基于TRAE Work v3.2.0版本编写。

[9] 文章当前生产日期

2026-08-28

TRAE Work SSO单点登录：多终端适配配置实战指南

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #