SSO单点登录对接

1. 目标

第三方系统通过 SSO Token 与 Easyai Server 建立统一登录，最终拿到 Easyai Server 自身签发的登录态（token/refresh_token）。

2. 参与方

• Client：前端或业务调用方
• Easyai Server：登录网关与业务服务
• SSO Provider：第三方身份提供方

3. 时序图

4. Easyai Server 登录接口

4.1 接口定义

• Method: POST
• Path: /auth/sso/login
• Content-Type: application/json

请求体：

请求示例：

{
  "accessToken": "sso_access_token_xxx"
}

4.2 标准响应结构

data 常见字段：

成功响应示例：

{
  "status": "success",
  "message": "登录成功",
  "data": {
    "token": "jwt_access_token",
    "refresh_token": "jwt_refresh_token",
    "sso_id": "68c0203f19621fd444269c75",
    "tenantId": "tenant_a",
    "role": ["user"],
    "balance": 100
  }
}

失败语义：

• 缺少 accessToken：认证失败
• accessToken 无效/过期：认证失败
• SSO 返回主键缺失（id 为空）：登录失败

5. SSO Provider 接口契约

Easyai Server 将调用：

• Method: GET
• URL: ${SSO_API_URL}
• Query: access_token=<accessToken>

返回字段要求：

返回示例：

{
  "id": "68c0203f19621fd444269c75",
  "username": "alice",
  "permissions": ["portal:easyai:model"],
  "tenantId": "tenant_a",
  "organizationIds": ["507f1f77bcf86cd799439011", "507f191e810c19729de860ea"],
  "email": "alice@example.com",
  "mobile": "13800000000",
  "avatar": "https://cdn.example.com/avatar.png",
  "nickname": "Alice",
  "balance": 100
}

5.1 登录时自动加入组织（可选）

管理员在 组织管理 → 编辑 弹窗中查看并复制只读的 组织 ID，由客户身份服务维护用户与组织的对应关系，在上述用户信息响应中返回 organizationIds。

使用 EasyAI 已存在组织的 _id，与 tenantId、组织名称及外部部门 ID 不同，不会自动创建组织。POST /auth/sso/login 仍然只传 accessToken，浏览器提交的组织字段不作为入组依据；客户 SSO 身份服务须确认用户有权加入所返回的组织。

数组内只接受字符串 ID，会去除首尾空格、规范化 ObjectId 并去重。空数组不会退出组织；管理员移除成员后，若后续 SSO 登录仍返回该组织，用户会被重新加入。

组织变更在下一次实际调用 SSO 登录接口时生效，不实时同步或强制刷新已有前端登录态。Token 无效、身份信息缺失、账号禁用及账号创建失败等原有登录失败条件仍然有效。

6. 环境变量与配置表单

6.1 环境变量

6.1.1 配置位置

Docker 部署场景下，请在 docker-compose.yml 的 easyai-server 服务 environment 中配置 SSO_API_URL。

示例（docker-compose）：

services:
  easyai-server:
    environment:
      - SSO_API_URL=http://sso.example.com/auth/user

示例：

SSO_API_URL=http://localhost:5001/auth/user

6.2 对接表单（建议双方确认）

7. 完成标准

• POST /auth/sso/login 在真实 Token 下可稳定成功
• sso_id 与第三方 id 一致且稳定
• token 刷新链路可用，登录态可持续
• 启用组织入组时，核验新老用户的组织成员列表、重复登录去重、无效 ID 跳过及未指定有效组织时的默认规则

Canvas CLI 服务端接入

Portal 智能体需要通过用户 SSO token 操作画布时，使用 Canvas CLI 的 SSO 接入。该文档通过时序图说明凭证兑换、传给 CLI、刷新和注销，并提供无需 EasyAI 后端源码的完整调用示例。