> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trae.cn/llms.txt
> Use this file to discover all available pages before exploring further.

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

## 适用客户端 {#hkMOa9ipe}

OAuth2.0 登录适用于以下客户端：

* TRAE IDE
* TRAE Work 桌面版、网页版和移动版
* TRAE 插件
* TRAE CLI

## 配置 OAuth2.0 登录 {#a569c1e0}

### 前置条件 {#448392e3}

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

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

### 操作步骤 {#6a762b62}


1. 登录 [TRAE 企业版控制台](https://console.enterprise.trae.cn/)。
2. 前往 **企业配置** > **通用设置**。
3. 在 **SSO 登录** > **Auth2.0 登录** 部分，点击 **···** > **配置**。
   界面上出现 **SSO 登录配置** 窗口。
4. 在 **回调地址** 部分，复制 TRAE 为你的企业自动生成的回调地址。
5. 前往企业的 IdP 服务管理中心，打开你为 TRAE 企业版创建的 OAuth 应用，然后将应用的重定向地址配置为上一步中复制的回调地址。
6. 返回 SSO 登录配置面板，然后点击 **下一步** 按钮。
   你将进入 OAuth 参数配置面板。
   ![Image=500x583](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/73bf4cb6309a4faba271668167b80c07~tplv-goo7wpa0wc-image.image)
7. 配置以下 OAuth 参数：
   <!-- @cols-width: 180,100,550 -->
   | | | | \
   |**参数** |**是否必填** |**描述** |
   |---|---|---|
   |Client ID |是 |你在 IdP 中为 TRAE 创建的 OAuth 应用的唯一标识符。 |
   |Client Secret |是 |你所创建的 OAuth 应用的密钥。TRAE 用该密钥向 IdP 服务换取访问令牌。 |
   |OAuth URL |是 |IdP 的授权端点。用户将被重定向至此页面完成认证。 |
   |Token URL |是 |IdP 的令牌端点。TRAE 后端通过此端点用授权码换取访问令牌。 |
   |UserInfo URL |是 |IdP 的用户信息端点。TRAE 调用此接口获取用户的身份信息。 |
   |Scope |否 |请求的授权范围，定义了 TRAE 可以访问的用户信息。多个值用英文逗号分隔。 |
   :::notice 注意
   Client Secret 属于高敏感凭据，请勿在任何客户端代码、日志或版本控制系统中暴露。TRAE 仅在后端服务器与 IdP 之间使用此密钥，不会将其暴露给前端或用户。
   :::   


更多关于参数的说明参考 “SSO 配置详解” 部分。

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

## SSO 配置详解 {#a7ed4665}

### 回调地址配置要求 {#f8290a20}

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

需注意：

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

### Scope 参数配置说明 {#fe1669b6}

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

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

```Plain Text
openid,profile,email
```

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

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

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

### state 参数说明 {#1ae57b77}

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

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

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

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

### Token 交换认证方式 {#8be5ba18}

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

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

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

### UserInfo 接口规范 {#8b8ae7c3}

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

#### 调用方式 {#d63bf8f5}

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

```Plain Text
GET {UserInfo URL}
Authorization: Bearer {access_token}
```

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

```Plain Text
GET {UserInfo URL}?access_token={access_token}
```

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

#### 响应字段要求 {#a7f021e1}

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

<!-- @cols-width: 150,141,121,452 -->
| | | | | \
|**字段** |**类型** |**是否必填** |**描述** |
|---|---|---|---|
|`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 接入示例 {#c2862b97}

### 飞书开放平台 {#7523243a}

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

<!-- @cols-width: 200,488 -->
| | | \
|**参数** |**参考值** |
|---|---|
|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` |

**前置操作：**

* 在飞书开放平台（open.larkoffice.com）创建企业自建应用。
* 在应用的 **开发配置** > **安全设置** 部分，将 TRAE 的回调地址添加为应用的重定向 URL。
   若你已为企业创建了专属域名，建议同时添加 TRAE 企业版公共域名的回调地址（`https://console.enterprise.trae.cn/oauth/callback`）和企业专属域名的回调地址（`https://vpcxxxxxxx.trae.volces.com/oauth/callback`），从而避免因后续修改域名访问策略而导致 SSO 登录失败。
* 在应用的 **开发配置** > **权限管理** 部分，开通以下权限：
   * `contact:user.email:readonly`：用于获取邮箱
   * `contact:user.employee_id:readonly`：用于获取用户 ID
* 发布应用并设置可见范围（添加需要使用 TRAE SSO 登录的成员）。

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

### 飞书集成平台 {#ae5ab716}

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

<!-- @cols-width: 200,450 -->
| | | \
|**参数** |**参考值** |
|---|---|
|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` |

**前置操作：**

参考[此文档](https://anycross.larkoffice.com/documentation/sso/protocol/OAuth)，在飞书集成平台（anycross.feishu.cn）创建 SSO 自建应用，并启用 OAuth 2.0 协议。参数配置要求如下：

* 将 TRAE 的回调地址设置为应用的登录回调地址。
   若你已为企业创建了专属域名，建议同时添加 TRAE 企业版公共域名的回调地址（`https://console.enterprise.trae.cn/oauth/callback`）和企业专属域名的回调地址（`https://vpcxxxxxxx.trae.volces.com/oauth/callback`），从而避免因后续修改域名访问策略而导致 SSO 登录失败。
* 将授权模式设置为 `authorization_code`，为权限范围（Scope）配置 `Email` 和 `profile`，将返回类型设置为 `code`。
* URL 中的 `{应用标识}` 为飞书集成平台中自建应用的唯一标识，将其替换为实际值。

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