单点登录（Single Sign\-On，SSO）功能允许企业成员使用公司统一的身份认证体系登录TRAE。企业管理员在 TRAE 控制台中配置 SSO（Single Sign\-On）登录后，成员只需输入企业邮箱即可跳转至企业的身份认证系统完成登录。 ## 套餐要求团队版、旗舰版 ## SSO 登录流程概览

参与方说明如下： |**角色** |**描述** | |---|---| |用户 |希望登录 TRAE 的企业成员。 | |TRAE 企业版控制台 |企业配置管理平台，用于让企业管理员管理 SSO 登录相关的配置。 | |TRAE 的账号服务 |TRAE 后端服务，负责 SSO 配置匹配、身份验证和会话管理。 | |企业的身份认证服务 |企业自有的身份认证服务（IdP），如 Okta、Azure AD、Google Workspace 等。 | 流程说明如下： |**序号** |**步骤** |**描述** | |---|---|---| |1 |发起 SSO 登录 |企业成员访问 TRAE 登录页面，选择 “企业 SSO 登录” 方式。 | |2 |输入企业邮箱 |成员输入企业邮箱地址，系统根据邮箱域名找到对应的 SSO 配置。 | |3 |跳转企业认证 |TRAE 将该成员的浏览器重定向至企业的 IdP 页面（如 Okta、Azure AD 等）。 | |4 |完成身份验证 |该成员在企业的 IdP 页面中完成身份验证（支持账号密码、MFA 等方式）。 | |5 |返回 TRAE |认证成功后，浏览器自动跳转回 TRAE。 | |6 |登录完成 |TRAE 的账号服务验证该成员的身份信息，建立登录会话，然后将该用户登入 TRAE IDE。 | ## 配置 SSO 登录 ### 前置条件在企业的 IdP 中，为 TRAE 创建一个 OAuth 应用，并获取以下信息： * Client ID（通常为应用 ID） * Client Secret（通常为应用密钥） * 相关的 OAuth 端点 URL，包括授权端点、令牌端点和用户信息端点 ### 操作步骤 1. 登录 [TRAE 企业版控制台](https://console.enterprise.trae.cn/)。 2. 前往 **企业配置** \> **通用设置**。 3. 在 **更多登录** \> **SSO 登录** 部分，点击 **···** \> **配置**。界面上出现 **SSO 登录配置** 窗口。 4. 在 **回调地址** 部分，复制 TRAE 为你的企业自动生成的回调地址。 5. 前往企业的 IdP 服务管理中心，打开你为 TRAE 企业版创建的 OAuth 应用，然后将应用的重定向地址配置为上一步中复制的回调地址。 6. 返回 SSO 登录配置面板，然后点击 **下一步** 按钮。你将进入 OAuth 参数配置面板。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/73bf4cb6309a4faba271668167b80c07) 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 之间使用此密钥，不会将其暴露给前端或用户。

更多关于参数的说明参考 “SSO 配置详解” 部分。 8. 完成参数配置后，你可以： * 点击 **保存并测试登录**，系统将保存配置并发起一次真实的 SSO 登录流程来验证配置的正确性。或 * 点击 **保存**，直接保存配置。 9. 打开 SSO 登录开关。 ## SSO 配置详解 ### 回调地址配置要求 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` 参数以英文逗号分隔多个值，例如： ```Plain Text openid,profile,email ``` 建议至少包含以下权限，以确保 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` 接口： ```Plain Text GET {UserInfo URL} Authorization: Bearer {access_token} ``` 如果接口返回非 200 状态码，TRAE 会自动回退到 Query Parameter 方式重试： ```Plain Text GET {UserInfo URL}?access_token={access_token} ```

提示

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` | **前置操作：** * 在飞书开放平台（open.larkoffice.com）创建企业自建应用。 * 在应用的 **开发配置** \> **安全设置** 部分，将 TRAE 的回调地址添加为应用的重定向 URL。 * 在应用的 **开发配置** \> **权限管理** 部分，开通以下权限： * `contact:user.email:readonly`：用于获取邮箱 * `contact:user.employee_id:readonly`：用于获取用户 ID * 发布应用并设置可见范围（添加需要使用 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` | **前置操作：** 参考[此文档](https://anycross.larkoffice.com/documentation/sso/protocol/OAuth)，在飞书集成平台（anycross.feishu.cn）创建 SSO 自建应用，并启用 OAuth 2.0 协议。参数配置要求如下： * 将 TRAE 的回调地址设置为应用的登录回调地址。 * 将授权模式设置为 `authorization_code`，为权限范围（Scope）配置 `Email` 和 `profile`，将返回类型设置为 `code`。 * URL 中的 `{应用标识}` 为飞书集成平台中自建应用的唯一标识，将其替换为实际值。

提示

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

TRAE CN