Skip to content

Hello OP 对接 SUD OpenPaaS 示例 ​

本文以 helloOP-developer(helloOP 开发者中心)为参考实现,说明平台应用(APP)如何落地 存量数据同步流程 中描述的 OAuth 2.0 授权与存量数据拉取能力。

本示例对应的抽象协议见 开放接口(Webhook)。helloOP 采用 Spring Authorization Server 标准 OAuth 2.0 端点 + 开发者业务 API,语义对齐 Webhook 规范,路径与请求形态按 RFC 6749 / 业务约定实现。


1. 示例定位 ​

抽象角色(存量同步 SOP)helloOP 中的对应
平台应用(APP)= AS + RShelloOP-developer-server
SUD OpenPaaS = OAuth2 Client在 helloOP 中注册的第三方应用(oauth2_registered_client)
游戏厂商(CP)helloOP 开发者账号(t_developer)
cp_idJWT uid claim(开发者主键 ID)

业务目标不变:厂商在 SUD OpenPaaS 发起「绑定 helloOP 账号」→ 浏览器完成 helloOP 登录授权 → SUD 换取 Token → 拉取该开发者的主体与游戏存量数据。


2. helloOP-developer 模块结构 ​

text
helloOP-developer/
├── helloOP-developer-api/                 # Feign / DTO(跨服务)
└── helloOP-developer-server/              # Spring Boot 应用
    └── src/main/java/.../developer/
        ├── config/
        │   └── SecurityConfig.java        # 多层安全过滤链 + OAuth2 AS
        ├── controller/
        │   ├── auth/LoginController       # POST /developer/login(开发者控制台)
        │   ├── developer/DeveloperController
        │   │                              # GET /developer/info(OpenPaaS 拉取主体)
        │   ├── app/DeveloperAppController # POST /developer/app/create(注册 Client)
        │   └── game/DeveloperGameController
        │                                  # 游戏列表 / 详情 / 资质 / ICP 拉取
        └── service/                       # 开发者、应用、游戏业务实现

2.1 安全过滤链(理解对接的关键) ​

Order匹配路径认证方式用途
1/oauth2/**OAuth2 协议授权、换码、刷新、吊销等标准端点
2/developer/**Bearer JWT(须含 uid)开发者业务 API;OpenPaaS 拉数走此链
3/external/**、/pink/**放行其他外部能力(与本示例无关)
4其余表单登录login.html 等;Authorization Code 流程的登录页

两条登录路径不要混用:

对比项AS 表单登录(对接 SUD 时使用)自定义 REST 登录
入口浏览器访问 /oauth2/authorize → 未登录跳转 /login.htmlPOST /developer/login
产出Session → 继续授权 → 颁发 authorization_code直接返回开发者 JWT
适用第三方(SUD OpenPaaS)绑定账号开发者本人使用控制台管理应用/游戏

SUD 对接必须走 Authorization Code,不要用 POST /developer/login 代替授权流程。


3. 完整对接流程 ​

3.1 阶段零:将 SUD 注册为 OAuth2 Client(一次性) ​

由 helloOP 侧具备开发者权限的管理员完成(可在控制台或通过 API):

  1. POST /developer/login 获取管理用 JWT(仅用于创建 Client,与用户绑定流程无关)。

  2. POST /developer/app/create 注册应用:

    http
    POST /developer/app/create
    Authorization: Bearer {开发者管理JWT}
    Content-Type: application/json
    
    {
      "clientName": "SUD OpenPaaS",
      "redirectUris": [
        "https://{sud-op-host}/callback"
      ],
      "scopes": "read write"
    }
  3. 响应中的 clientId / clientSecret(明文仅返回一次)配置到 SUD OpenPaaS 后端;后续所有厂商绑定复用这对凭证。

提供 redirectUris 后,Client 将启用 authorization_code(并通常同时支持 refresh_token 等)。

3.2 阶段一:用户授权(浏览器) ​

text
用户浏览器              SUD OpenPaaS                    helloOP-developer
    │                    │                                    │
    │  点击「绑定 helloOP」│                                    │
    │───────────────────→│                                    │
    │  302 重定向         │                                    │
    │←───────────────────│                                    │
    │  Location:                                              │
    │  https://{helloOP}/oauth2/authorize                     │
    │    ?response_type=code                                  │
    │    &client_id={clientId}                                │
    │    &redirect_uri=https://{sud}/callback                 │
    │    &scope=read write                                    │
    │    &state={随机值}                                       │
    │───────────────────────────────────────────────────────→│
    │                    │                     校验 client_id /│
    │                    │                     redirect_uri  │
    │                    │                     未登录 → /login.html
    │  展示 helloOP 登录页 │                                    │
    │←───────────────────────────────────────────────────────│
    │  POST /oauth2/do-login(表单:username + password)       │
    │───────────────────────────────────────────────────────→│
    │                    │                     认证通过 → 生成 code
    │  302 → redirect_uri?code=...&state=...                  │
    │←───────────────────────────────────────────────────────│
    │───────────────────→│  校验 state                         │

要点:

  • 登录页在 helloOP 域名下,SUD 看不到账号密码;
  • state 由 SUD 生成并在回调时校验;
  • redirect_uri 必须与注册时完全一致。

3.3 阶段二:用授权码换 Token(服务端) ​

http
POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={AUTHORIZATION_CODE}
&redirect_uri=https://{sud}/callback
&client_id={clientId}
&client_secret={clientSecret}

成功响应(标准 OAuth2):

json
{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "...",
  "scope": "read write"
}

helloOP 通过 OAuth2TokenCustomizer 在 access_token 中写入 uid(开发者 ID)。SUD 可将该 uid 视为抽象协议中的 cp_id,用于账号映射。

3.4 阶段三:拉取存量数据 ​

所有拉取接口均需:

http
Authorization: Bearer {access_token}

且 Token 必须包含 uid claim;client_credentials 颁发的无 uid Token 不能访问 /developer/**。

推荐顺序:

顺序helloOP 接口说明
1GET /developer/info主体信息;主体 ID 从 Token uid 解析,无需路径传参
2GET /developer/game/list已上线游戏列表(分页)
3GET /developer/game/basic-info?bundle_id=单游戏基本信息
4GET /developer/game/qualification?bundle_id=单游戏资质(软著/版号等)
5GET /developer/game/icp-filing?bundle_id=单游戏 ICP 备案(对应 game.queryICP)

列表项中的 bundle_id(包名)作为后续详情/资质/ICP 的查询键。

3.5 阶段四:Token 续签 ​

http
POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={refresh_token}
&client_id={clientId}
&client_secret={clientSecret}

解绑时可调用 POST /oauth2/revoke 吊销 Token。


4. 抽象 Webhook ↔ helloOP 接口映射 ​

存量同步 WebhookhelloOP 实现差异说明
oauth.authorizeGET /oauth2/authorize标准浏览器重定向;成功后 302 回 redirect_uri,而非 JSON 包一层 code
oauth.accessTokenPOST /oauth2/token(grant_type=authorization_code)application/x-www-form-urlencoded;厂商标识在 JWT uid,不单独返回 cp_id 字段
oauth.refreshTokenPOST /oauth2/token(grant_type=refresh_token)同上,标准 Token 端点
cp.queryDetailGET /developer/info字段:id / subject_name / subject_type / uscc / username / status
cp.queryKYCGET /developer/info主体级 KYC 与 info 同构;更细主办方/负责人见 game.queryICP
game.queryListGET /developer/game/list分页键为 page_no / page_size;列表项为 bundle_id / name / version
game.queryDetailGET /developer/game/basic-info?bundle_id=请求键为 bundle_id,非 game_id
game.queryKYCGET /developer/game/qualification?bundle_id=结构化 software_copyright / publication_number 等
game.queryICPGET /developer/game/icp-filing?bundle_id=含顶层 license_no;枚举字段返回文案

若 APP 选择完全按 Webhook 文档实现自定义 HTTPS 接口(JSON Body + 签名头),语义仍应对齐上表;helloOP 选择标准 OAuth2 + REST GET,便于与 Spring Authorization Server 生态兼容。


5. 拉取接口字段摘要 ​

5.1 主体信息 GET /developer/info ​

字段说明
id三方平台主体 ID(即 Token uid / 映射用 cp_id)
subject_name主体名称
subject_type0 个人,1 企业
uscc统一社会信用代码(企业)
username登录用户名
status0 禁用,1 启用

5.2 游戏列表 GET /developer/game/list ​

字段说明
list[].bundle_id游戏包名(后续拉取键)
list[].name游戏名称
list[].version最新版本号
total / page_no / page_size分页信息

仅返回已上线(status=1)游戏。

5.3 游戏基本信息 / 资质 / ICP ​

  • basic-info:名称、图标、引擎、分类、简介、客服与隐私政策等
  • qualification:software_copyright、publication_number、补充材料等
  • icp-filing:主办方、负责人、游戏备案、前置审批、授权书等

请求均携带 bundle_id Query 参数与 Bearer Token。统一响应外壳为:

json
{
  "ret_code": 0,
  "ret_msg": "success",
  "data": { },
  "timestamp": 1719820800000
}

6. 端到端时序(helloOP) ​


7. 对接检查清单 ​

APP(helloOP)侧 ​

  • [ ] 已注册 SUD Client,redirect_uri 白名单正确
  • [ ] Authorization Code 登录页可正常认证开发者账号
  • [ ] access_token 含 uid,且 /developer/** 拒绝无 uid Token
  • [ ] 提供主体、游戏列表、详情、资质(及 ICP)拉取接口
  • [ ] 支持 refresh_token;可选支持 revoke

SUD OpenPaaS 侧 ​

  • [ ] 安全存储 client_id / client_secret
  • [ ] 授权发起带随机 state,回调严格校验
  • [ ] 仅服务端换码,前端不接触 client_secret
  • [ ] 用 uid 完成厂商账号映射并持久化 Token
  • [ ] 按列表分页拉全量游戏,缺失项可告警重试
  • [ ] Token 过期自动刷新;刷新失败引导重新授权

8. 相关文档 ​

  • 存量数据同步流程 — 通用业务与安全要求
  • 开放接口 — APP 需实现的抽象 Webhook 协议
  • helloOP 工程内接口说明:helloOP-developer 模块 openpaas-developer-api.md / docs/sud-op-integration-flow.md