ZYZHIXI OAuth2 关联授权文档

本文档定义了 Zibll OAuth2 代理服务的接口规范与安全建议。

1. 基础信息

2. 术语与参数

字段	说明
client_id	应用唯一标识（在 Provider 后台创建应用获取）
client_secret	应用密钥（请勿泄露，仅限服务端使用）
redirect_uri	授权回调地址（必须与后台配置完全一致，精确匹配）
code	临时授权码（有效期 10 分钟，一次性）
access_token	资源访问令牌（默认有效期 2 小时）
refresh_token	刷新令牌（有效期 180 天，滑动过期，每次刷新会轮换）

3. 核心流程

3.1 授权 (Authorize)

引导用户在浏览器访问：GET /authorize

请求参数：

参数	说明
response_type	固定为 `code`
client_id	应用标识
redirect_uri	回调地址
state	接入方生成的随机串（用于防 CSRF，回调时原样返回）
scope	权限范围（默认 `basic`，可选 `email`, `profile`, `phone`）

用户同意后回调：{redirect_uri}?code={CODE}&state={STATE}

3.2 换取令牌 (Token)

接入方后端通过 code 换取令牌：POST /token

请求参数（Form 或 JSON）：

参数	说明
grant_type	固定为 `authorization_code`
client_id	应用标识
client_secret	应用密钥
code	回调获取的 code
redirect_uri	必须与授权时一致

成功响应 (200 OK)：

json

{

  “access_token”: “AT_xxx”,

  “token_type”: “bearer”,

  “expires_in”: 7200,

  “refresh_token”: “RT_xxx”,

  “refresh_token_expires_in”: 15552000

}

错误响应：

json

{

  “code”: “invalid_grant”,

  “message”: “code 无效或已过期”,

  “data”: {}

}

3.3 刷新令牌 (Refresh)

当 `access_token` 快过期时，使用 `refresh_token` 获取新令牌：POST /token

请求参数：

参数	说明
grant_type	固定为 `refresh_token`
client_id	应用标识
client_secret	应用密钥
refresh_token	当前的 refresh_token

> 说明： `refresh_token` 采用旋转机制，每次刷新都会返回新的 refresh_token，旧令牌立即失效。

3.4 吊销令牌 (Revoke)

主动失效令牌：POST /revoke

请求参数：

参数	说明
client_id	应用标识
client_secret	应用密钥
token	要吊销的令牌
token_type_hint	可选 `access_token` 或 `refresh_token`

成功响应 (200 OK)：

json

{

  “revoked”: true

}

错误响应：

json

{

  “code”: “invalid_client”,

  “message”: “client_secret 无效”,

  “data”: {}

}

4. 用户信息接口

4.1 获取用户信息 (UserInfo)

GET /userinfo

Header: Authorization: Bearer <access_token>

成功响应 (200 OK)：

json

{

  “userinfo”: {

    “openid”: “o_xxx”,

    “name”: “用户名”,

    “avatar”: “https://…”,

    “email”: “user@example.com”,

    “phone”: “+8613800000000”,

    “description”: “个人简介”

  }

}

4.2 获取 UnionID (UnionID)

GET /unionid

Header: Authorization: Bearer <access_token>

成功响应 (200 OK)：

json

{

  “openid”: “o_xxx”,

  “unionid”: “123”

}

5. 服务端回调与签名安全

当异步任务（如撤销授权）完成时，Provider 会 `POST application/json` 到接入方。

5.1 撤销授权回调

当用户撤销授权时，Provider 会向应用配置的回调地址发送通知。

请求方法： `POST`  

Content-Type： `application/json`

请求体示例：

json

{

  “appid”: “app_xxx”,

  “openid”: “o_xxx”,

  “user_id”: 123,

  “status”: “revoked”,

  “revoked_at”: 1704067200,

  “timestamp”: 1704067200,

  “nonce”: “random_str”,

  “event_id”: “evt_xxx”,

  “sign2”: “sha256_signature”

}

字段说明：

字段	说明
appid	应用标识
openid	用户 OpenID
user_id	用户 ID
status	状态（revoked）
revoked_at	撤销时间（Unix 时间戳）
timestamp	Unix 时间戳
nonce	随机字符串
event_id	事件 ID（用于去重）
sign2	签名

接入方应返回：

json

{

  “code”: 0,

  “message”: “success”

}

5.2 签名算法 (Sign2)

全链路仅支持 V2 全字段签名。算法如下：

1. 排除 `sign` 和 `sign2` 参数

2. 将剩余所有参数按 Key 的 ASCII 码升序排序

3. 将排序后的参数拼成 `key1=value1&key2=value2`（value 为数组或对象时转 JSON，字符进行 rawurlencode）

4. 使用 `client_secret` 作为 Key，对该字符串执行 HMAC-SHA256

5.3 幂等建议

回调 Payload 包含 `event_id`。接入方应：

验签：验证 `sign2`

去重：检查 `event_id` 是否已处理过

处理：执行业务逻辑并返回 200 OK

6. 错误码规范

错误码	HTTP	说明
invalid_request	400	参数缺失或格式错误
invalid_client	401	client_secret 校验失败
invalid_grant	400	code/refresh_token 无效或已过期
unauthorized_client	403	应用不存在或未启用
ip_not_allowed	403	调用 IP 不在白名单

部分开发者可能会使用 AI 工具辅助开发，这边直接提供MD文档。