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

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

## 适用客户端 {#hkMOa9ipe}

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

## 配置 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 登录** > **OAuth2.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-topic.webp)
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 之间使用此密钥，不会将其暴露给前端或用户。
   :::   


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

8. 完成参数配置后，你可以：
   * 点击 **保存并测试登录**，系统将保存配置并发起一次真实的 SSO 登录流程来验证配置的正确性。
      或
   * 点击 **保存**，直接保存配置。
9. 打开 **OAuth2.0 登录** 开关。
   :::tip 提示
   若已启用火山引擎云身份中心登录，需先禁用该方式后，才可以启用 OAuth2.0 登录。
   :::   


## OAuth2.0 登录配置详解 {#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` | \
| | * (条件必填) `contact:user.employee:readonly`  |

**前置操作：**

* 在飞书开放平台（open.larkoffice.com）创建企业自建应用。
* 在应用的 **开发配置** > **安全设置** 部分，将 TRAE 的回调地址添加为应用的重定向 URL。
   若你已为企业创建了专属域名，建议同时添加 TRAE 企业版公共域名的回调地址和企业专属域名的回调地址，格式为 `{完整域名}/oauth/callback`，从而避免因后续修改域名访问策略而导致 SSO 登录失败。关于 TRAE 企业版客户端支持的公共域名和专属域名，参考[域名类型与适用范围](/enterprise_access-control-for-trae-enterprise-exclusive-edition#hLR8WrdaZ)。
* 在应用的 **开发配置** > **权限管理** 部分，开通以下权限：
   * `contact:user.email:readonly`：用于获取邮箱。
   * `contact:user.employee_id:readonly`：用于获取用户 ID。
   * (条件必填) `contact:user.employee:readonly`：获取用户的受雇信息。当飞书未配置工作邮箱，且需要使用企业邮箱作为兜底邮箱时，必须额外配置该权限。
* 发布应用并设置可见范围（添加需要使用 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 企业版公共域名的回调地址和企业专属域名的回调地址，格式为 `{完整域名}/oauth/callback`，从而避免因后续修改域名访问策略而导致 SSO 登录失败。关于 TRAE 企业版客户端支持的公共域名和专属域名，参考[域名类型与适用范围](/enterprise_access-control-for-trae-enterprise-exclusive-edition#hLR8WrdaZ)。
* 将授权模式设置为 `authorization_code`，为权限范围（Scope）配置 `Email` 和 `profile`，将返回类型设置为 `code`。
* URL 中的 `{应用标识}` 为飞书集成平台中自建应用的唯一标识，将其替换为实际值。

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