文档中心

TRAE CN

SSO 登录

配置 OAuth2.0 登录

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

适用客户端

TraeCode

TraeCode Plugin

TraeCode CLI

TraeWork 桌面版和网页版

TRAE 移动端

配置 OAuth2.0 登录

前置条件

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

Client ID（通常为应用 ID）

Client Secret（通常为应用密钥）

相关的 OAuth 端点 URL，包括授权端点、令牌端点和用户信息端点

操作步骤

前往企业配置 > 通用设置。

在 SSO 登录 > OAuth2.0 登录部分，点击 ··· > 配置。

界面上出现 SSO 登录配置窗口。

在回调地址部分，复制 TRAE 为你的企业自动生成的回调地址。

前往企业的 IdP 服务管理中心，打开你为 TRAE 企业版创建的 OAuth 应用，然后将应用的重定向地址配置为上一步中复制的回调地址。

返回 SSO 登录配置面板，然后点击下一步按钮。

你将进入 OAuth 参数配置面板。

配置以下 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 登录配置详解” 部分。

完成参数配置后，你可以：

点击保存并测试登录，系统将保存配置并发起一次真实的 SSO 登录流程来验证配置的正确性。

点击保存，直接保存配置。

打开 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 参数以英文逗号分隔多个值，例如：

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

值	描述
openid	OIDC 基础权限，允许 TRAE 获取用户的唯一标识（sub）。
profile	允许 TRAE 获取用户的名称（name）、头像等基础信息。
email	允许 TRAE 获取用户的邮箱地址（email）。注意：若不包含此权限，部分 IdP 的 UserInfo 接口将不返回 email 字段，导致登录失败。

提示

不同 IdP 对 Scope 的值的命名可能不同。如果使用非 OIDC 标准的 IdP（如内部自研认证系统），请参考该 IdP 的文档获取正确的值。

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 接口：

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

提示

TRAE 最多重试 3 次，两种调用方式均会尝试，建议至少保证一种方式可用。

响应字段要求

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

字段	类型	是否必填	描述
email	string	是	用户的邮箱地址，用于匹配 TRAE 账号。若缺失则登录失败。
sub	string / number	否（建议传入）	用户在 IdP 中的唯一标识，用于账号关联。
name	string	是	用户的展示名称。若缺失则登录失败。
avatar	string (URL)	否	用户的头像地址。若缺失，则保留用户当前在 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 网关的企业。

参数	参考值
OAuth URL	https://accounts.feishu.cn/open-apis/authen/v1/authorize
Token URL	https://open.feishu.cn/open-apis/authen/v2/oauth/token
UserInfo URL	https://open.feishu.cn/open-apis/authen/v1/user_info
Scope	contact:user.email:readonly contact:user.employee_id:readonly (条件必填) contact:user.employee:readonly

前置操作：

在飞书开放平台（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 登录的成员）。

提示

飞书的 UserInfo 接口将用户信息包裹在 data 字段下（如 data.email、data.name）。TRAE 已内置对此结构的自动兼容，无需额外配置字段映射。用户邮箱对应 data.email（个人邮箱），用户唯一标识对应 data.open_id。

飞书集成平台

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

参数	参考值
OAuth URL	https://anycross.feishu.cn/sso/{应用标识}/oauth2/auth
Token URL	https://anycross.feishu.cn/sso/{应用标识}/oauth2/token
UserInfo URL	https://anycross.feishu.cn/sso/{应用标识}/oauth2/userinfo
Scope	profile,email

前置操作：

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

将 TRAE 的回调地址设置为应用的登录回调地址。

若你已为企业创建了专属域名，建议同时添加 TRAE 企业版公共域名的回调地址和企业专属域名的回调地址，格式为 {完整域名}/oauth/callback，从而避免因后续修改域名访问策略而导致 SSO 登录失败。关于 TRAE 企业版客户端支持的公共域名和专属域名，参考域名类型与适用范围。

将授权模式设置为 authorization_code，为权限范围（Scope）配置 Email 和 profile，将返回类型设置为 code。

URL 中的 {应用标识} 为飞书集成平台中自建应用的唯一标识，将其替换为实际值。

提示

飞书集成平台的 UserInfo 接口遵循标准 OIDC 格式，email、name 字段位于响应根层级，TRAE 可直接解析，无需额外配置。

最近更新时间：2026.10.10 17:34:31

这个页面对您有帮助吗？

有用

无用