配置 OAuth2.0 登录

TRAE 企业版支持基于 OAuth 2.0 协议的 SSO 登录。企业管理员完成 OAuth 2.0 登录配置后，企业成员只需输入企业邮箱，即可跳转至企业身份提供方（IdP）完成身份验证，并登录 TRAE 企业版客户端。

适用客户端

• TRAE
• TRAE Plugin
• TRAE CLI
• TraeWork 桌面版和网页版
• TRAE 移动端

配置 OAuth2.0 登录

前置条件

在企业的 IdP 中，为 TRAE 创建一个 OAuth 应用，并获取以下信息：

• Client ID（通常为应用 ID）
• Client Secret（通常为应用密钥）
• 相关的 OAuth 端点 URL，包括授权端点、令牌端点和用户信息端点

操作步骤

1. 登录 TRAE 企业版控制台。
2. 前往 企业配置 > 通用设置。
3. 在 SSO 登录 > OAuth2.0 登录 部分，点击 ··· > 配置。
   界面上出现 SSO 登录配置 窗口。
4. 在 回调地址 部分，复制 TRAE 为你的企业自动生成的回调地址。
5. 前往企业的 IdP 服务管理中心，打开你为 TRAE 企业版创建的 OAuth 应用，然后将应用的重定向地址配置为上一步中复制的回调地址。
6. 返回 SSO 登录配置面板，然后点击 下一步 按钮。
   你将进入 OAuth 参数配置面板。
   
7. 配置以下 OAuth 参数：

   参数	是否必填	描述
   Client ID	是	你在 IdP 中为 TRAE 创建的 OAuth 应用的唯一标识符。
   Client Secret	是	你所创建的 OAuth 应用的密钥。TRAE 用该密钥向 IdP 服务换取访问令牌。
   OAuth URL	是	IdP 的授权端点。用户将被重定向至此页面完成认证。
   Token URL	是	IdP 的令牌端点。TRAE 后端通过此端点用授权码换取访问令牌。
   UserInfo URL	是	IdP 的用户信息端点。TRAE 调用此接口获取用户的身份信息。
   Scope	否	请求的授权范围，定义了 TRAE 可以访问的用户信息。多个值用英文逗号分隔。

   注意

   Client Secret 属于高敏感凭据，请勿在任何客户端代码、日志或版本控制系统中暴露。TRAE 仅在后端服务器与 IdP 之间使用此密钥，不会将其暴露给前端或用户。

更多关于参数的说明参考 “OAuth2.0 登录配置详解” 部分。

8. 完成参数配置后，你可以：
   • 点击 保存并测试登录，系统将保存配置并发起一次真实的 SSO 登录流程来验证配置的正确性。
     或
   • 点击 保存，直接保存配置。
9. 打开 OAuth2.0 登录 开关。

   提示

   若已启用火山引擎云身份中心登录，需先禁用该方式后，才可以启用 OAuth2.0 登录。

OAuth2.0 登录配置详解

回调地址配置要求

TRAE 的 OAuth 回调地址由系统自动生成，在 SSO 登录配置弹窗的第一步中展示。接入 SSO 登录前，必须将此地址精确填写到 IdP 的 OAuth 应用的 “Redirect URI” 或 “Allowed Callback URLs” 中。

需注意：

• 回调地址必须完全匹配（大小写、路径、末尾斜杠均需一致），IdP 会对重定向 URL 做严格校验。
• 不同企业的 TRAE 部署地址不同，以配置弹窗中展示的实际地址为准。
• 如果企业为 TRAE 配置了自定义域名，回调地址将使用自定义域名。

Scope 参数配置说明

Scope 参数用于向 IdP 声明 TRAE 需要获取的用户信息权限范围。TRAE 使用访问令牌调用 UserInfo 接口时，IdP 会根据已授权的权限范围决定返回哪些用户属性。

在 TRAE 的 SSO 登录配置表单中，Scope 参数以英文逗号分隔多个值，例如：

openid,profile,email

建议至少包含以下权限，以确保 TRAE 能获取必要的用户信息：

state 参数说明

state 是 OAuth 2.0 流程中的防 CSRF 安全参数，由 TRAE 服务端在每次发起授权请求时自动生成，企业无需手动配置。

IdP 必须将接收到的 state 原封不动地附加在回调地址上返回给 TRAE。若 state 被修改或丢弃，TRAE 将拒绝该回调请求并报错。

针对不同 IdP 的行为差异，TRAE 已内置以下兼容处理：

• 自动处理 URL 编码（如将 %3D 转换为 =）。
• 同时支持 URL-safe Base64 和标准 Base64，自动回退。
• 自动将空格还原为 +，同时兼容部分将 + 解码为空格的 IdP。

Token 交换认证方式

在通过授权码换取访问令牌时（调用 Token URL），TRAE 使用 OAuth 2.0 Auto-Detect 模式，会自动探测 IdP 支持的认证方式：

• Header 方式：将 client_id 和 client_secret 通过 Authorization: Basic 请求头传递。
• Body 方式：将 client_id 和 client_secret 作为表单参数放在请求体中。

两种方式 TRAE 均支持，IdP 只需支持其中之一即可。

UserInfo 接口规范

TRAE 在获取访问令牌后，会调用配置的 UserInfo URL 来获取用户的身份信息。以下是对该接口的规范要求。

调用方式

TRAE 优先使用 HTTP Bearer Token 方式调用 UserInfo 接口：

GET {UserInfo URL}
Authorization: Bearer {access_token}

如果接口返回非 200 状态码，TRAE 会自动回退到 Query Parameter 方式重试：

GET {UserInfo URL}?access_token={access_token}

响应字段要求

UserInfo 接口必须返回 JSON 格式数据，TRAE 会从中提取以下字段：

字段提取顺序：

TRAE 优先从响应根层级提取上表中的字段；若未命中，则自动回退到 data 字段下查找。企业无需做额外的字段映射配置，两种响应形态均可被正确解析：

• 响应根层级（标准格式）：{ "email": "user@example.com", "name": "张三" }
• data 字段（嵌套格式）：{ "data": { "email": "user@example.com", "name": "张三" } }

邮箱匹配规则：

TRAE 会对比 IdP 返回的 email 字段与用户在登录页面输入的邮箱。两者必须一致（大小写不敏感），否则登录会被拒绝并返回 “email not match” 错误。企业需确保成员使用其在 TRAE 中注册的企业邮箱发起 SSO 登录。

IdP 接入示例

飞书开放平台

企业可以在飞书开放平台上创建自建应用，然后直接复用飞书身份体系接入 TRAE SSO。这是飞书接入 TRAE SSO 的主流方式，适合尚未部署独立 SSO 网关的企业。

前置操作：

• 在飞书开放平台（open.larkoffice.com）创建企业自建应用。
• 在应用的 开发配置 > 安全设置 部分，将 TRAE 的回调地址添加为应用的重定向 URL。
  若你已为企业创建了专属域名，建议同时添加 TRAE 企业版公共域名的回调地址和企业专属域名的回调地址，格式为 {完整域名}/oauth/callback，从而避免因后续修改域名访问策略而导致 SSO 登录失败。关于 TRAE 企业版客户端支持的公共域名和专属域名，参考域名类型与适用范围。
• 在应用的 开发配置 > 权限管理 部分，开通以下权限：
  • contact:user.email:readonly：用于获取邮箱。
  • contact:user.employee_id:readonly：用于获取用户 ID。
  • (条件必填) contact:user.employee:readonly：获取用户的受雇信息。当飞书未配置工作邮箱，且需要使用企业邮箱作为兜底邮箱时，必须额外配置该权限。
• 发布应用并设置可见范围（添加需要使用 TRAE SSO 登录的成员）。

飞书集成平台

企业可以在飞书集成平台上构建统一的 SSO 网关（聚合多个 IdP），然后让 TRAE 复用该统一接入点。

前置操作：

参考此文档，在飞书集成平台（anycross.feishu.cn）创建 SSO 自建应用，并启用 OAuth 2.0 协议。参数配置要求如下：

• 将 TRAE 的回调地址设置为应用的登录回调地址。
  若你已为企业创建了专属域名，建议同时添加 TRAE 企业版公共域名的回调地址和企业专属域名的回调地址，格式为 {完整域名}/oauth/callback，从而避免因后续修改域名访问策略而导致 SSO 登录失败。关于 TRAE 企业版客户端支持的公共域名和专属域名，参考域名类型与适用范围。
• 将授权模式设置为 authorization_code，为权限范围（Scope）配置 Email 和 profile，将返回类型设置为 code。
• URL 中的 {应用标识} 为飞书集成平台中自建应用的唯一标识，将其替换为实际值。