SSO单点登录对接

第三方系统通过SSO接入Easyai Server的登录流程与契约

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

请求体：

字段类型必填说明
accessTokenstring是SSO Provider 签发的访问令牌

请求示例：

{
  "accessToken": "sso_access_token_xxx"
}

4.2 标准响应结构

字段类型含义
statusstring调用结果：success / failed
messagestring错误或成功描述
dataobject | null成功时返回登录信息

data 常见字段：

字段类型含义
tokenstringEasyai Server 访问令牌
refresh_tokenstringEasyai Server 刷新令牌
sso_idstring第三方用户主标识（映射自 SSO id）
tenantIdstring | null租户标识（Portal 判定关键字段）
rolestring本系统角色
balancenumber当前余额（可选）

成功响应示例：

{
  "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>

返回字段要求：

字段类型必填含义
idstring是用户唯一主键，映射 sso_id
usernamestring是用户账号
permissionsstring否参与角色映射
tenantIdstring | null否租户信息（Portal 路径依赖）
emailstring否邮箱
mobilestring否手机号
avatarstring否头像
nicknamestring否昵称
balancenumber否初始余额展示信息

返回示例：

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

6. 环境变量与配置表单

6.1 环境变量

变量名必填示例说明
SSO_API_URL是http://localhost:5001/auth/userSSO 用户信息接口地址

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 对接表单（建议双方确认）

项目示例说明
SSO 地址http://sso.xxx.com/auth/user映射 SSO_API_URL
Token 传递方式query access_token当前协议约定
用户主键字段id必须全局稳定唯一
权限字段permissions用于角色映射
租户字段tenantIdPortal 集成依赖字段

7. 完成标准

  • POST /auth/sso/login 在真实 Token 下可稳定成功
  • sso_id 与第三方 id 一致且稳定
  • token 刷新链路可用，登录态可持续
文档总览
SSO、Portal能力与任务回调的一体化对接文档入口
Portal能力对接
基于SSO的资源白名单、权限等级与余额能力对接规范