OAuth内容已完善，各位可以通过这个小脚本快速对接调试，为了更方便的管理和维护，请各位开发者及时同步更新。

当前版本：2026-06-22

1. 背景说明

摸鱼派提供一套类 OAuth / OpenID 的第三方登录能力。第三方站点可以引导用户跳转到摸鱼派完成登录与授权，随后通过服务端校验回跳参数，获取用户身份与已授权资源访问令牌。

当前版本支持：

• 使用摸鱼派账号登录第三方站点
• 按授权范围读取用户基础信息、积分信息、发帖信息
• 使用 access_token 调用用户资源接口
• 使用 refresh_token 无感续签 access_token

2. 能力概览

第三方站点接入时，需要完成以下流程：

1. 构造 /openid/login 授权链接并跳转用户到摸鱼派。
2. 用户确认授权后，摸鱼派回跳到第三方站点。
3. 第三方站点调用 /openid/verify 校验回跳参数。
4. 校验通过后获得 access_token 与 refresh_token。
5. 使用 Authorization: Bearer <access_token> 调用用户资源接口。
6. access_token 过期前后，可通过 /openid/token 使用 refresh_token 续签。

3. 授权范围

第三方站点可以在 /openid/login 中通过 fishpi.scope 请求需要的权限。多个权限可使用空格或英文逗号分隔。

说明：

• 不传 fishpi.scope 时，默认按 profile.read 处理。
• 第三方站点请求的权限会在授权页默认勾选且不可取消。
• 用户可以额外勾选站点未请求的权限。
• 如果最终授权范围缺少站点请求的权限，本次授权失败。

4. 接入流程

4.1 发起登录

GET /openid/login

第三方站点构造授权地址，并将用户浏览器跳转到该地址。

请求：

请求示例：

https://fishpi.cn/openid/login?openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0&openid.mode=checkid_setup&openid.return_to=https%3A%2F%2Fexample.com%2Fcallback&openid.realm=https%3A%2F%2Fexample.com&openid.claimed_id=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0%2Fidentifier_select&openid.identity=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0%2Fidentifier_select&fishpi.scope=profile.read+points.read

注意：

• URL 参数需要按规范编码。
• openid.realm 必须是 openid.return_to 的前缀。
• 生产环境回调地址建议使用 HTTPS；本地开发可使用 localhost 或 127.0.0.1。

4.2 接收授权回跳

用户确认授权后，摸鱼派会重定向到 openid.return_to，并在 URL 中携带 OpenID 参数。

常见回跳参数：

openid.claimed_id / openid.identity 末尾通常包含用户 oId，例如：

https://fishpi.cn/openid/id/1659430635383

回跳参数不能直接作为可信登录结果，必须先调用 /openid/verify 校验。

4.3 校验回跳参数

POST /openid/verify

第三方站点服务端必须调用该接口校验回跳参数真实性。

请求：

请求示例：

curl --location --request POST 'https://fishpi.cn/openid/verify' \
--header 'Content-Type: application/json' \
--data-raw '{
  "openid.ns": "http://specs.openid.net/auth/2.0",
  "openid.mode": "check_authentication",
  "openid.op_endpoint": "https://fishpi.cn/openid",
  "openid.claimed_id": "https://fishpi.cn/openid/id/1659430635383",
  "openid.identity": "https://fishpi.cn/openid/id/1659430635383",
  "openid.return_to": "https://example.com/callback",
  "openid.response_nonce": "2026-06-22T00:00:00Zxxxxxxxxxx",
  "openid.assoc_handle": "1234567890",
  "openid.sig": "xxx"
}'

成功响应为纯文本：

ns:http://specs.openid.net/auth/2.0
is_valid:true
scope:profile.read points.read
token_type:Bearer
access_token:xxx
expires_in:604800
refresh_token:xxx
refresh_expires_in:31104000

失败响应为纯文本：

ns:http://specs.openid.net/auth/2.0
is_valid:false

响应字段：

安全要求：

• openid.response_nonce 是一次性参数，成功或失败校验后都不应重复使用。
• openid.response_nonce 有效期为 5 分钟。
• access_token 默认有效期为 7 天。
• refresh_token 默认空闲有效期为 360 天，最长不超过首次授权后 720 天。
• refresh_token 不应暴露到前端页面、浏览器存储、URL 或日志中。

4.4 续签访问令牌

POST /openid/token

使用 refresh_token 续签 access_token。该接口不使用登录态，不接收 apiKey。

请求：

请求示例：

curl --location --request POST 'https://fishpi.cn/openid/token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "grant_type": "refresh_token",
  "refresh_token": "xxx"
}'

成功响应：

{
  "code": 0,
  "msg": "",
  "data": {
    "token_type": "Bearer",
    "access_token": "xxx",
    "expires_in": 604800,
    "refresh_token": "xxx",
    "refresh_expires_in": 31104000,
    "scope": "profile.read points.read"
  }
}

失败响应：

{
  "code": -1,
  "msg": "无权限",
  "data": {}
}

说明：

• 每次续签成功都会返回新的 refresh_token。
• 旧 refresh_token 会立即失效。
• 如果已失效的旧 refresh_token 被重复使用，同一授权链路下的有效续签令牌会被撤销。
• 续签不会扩大权限范围，新的 access_token 沿用原授权范围。

5. 用户资源接口

用户资源接口统一使用：

Authorization: Bearer <access_token>

资源接口不接收 apiKey，不支持传 userId 代查其他用户。

5.1 查询用户基础信息

GET /openid/user/profile

需要授权范围：profile.read

请求示例：

curl --location --request GET 'https://fishpi.cn/openid/user/profile' \
--header 'Authorization: Bearer xxx'

响应字段：

5.2 查询用户积分记录

GET /openid/user/points

需要授权范围：points.read

请求参数：

请求示例：

curl --location --request GET 'https://fishpi.cn/openid/user/points?p=1&size=20' \
--header 'Authorization: Bearer xxx'

响应字段：

5.3 查询用户发帖记录

GET /openid/user/articles

需要授权范围：articles.read

请求参数：

请求示例：

curl --location --request GET 'https://fishpi.cn/openid/user/articles?p=1&size=20' \
--header 'Authorization: Bearer xxx'

响应字段：

说明：

• 仅返回公开、非匿名、未删除的发帖记录。
• 不返回正文、草稿、IP、UA 等敏感信息。

6. 错误处理

6.1 /openid/verify

/openid/verify 返回纯文本。只要 is_valid 不是 true，第三方站点都应视为登录失败。

常见原因：

• openid.response_nonce 已使用或过期
• openid.sig 签名不匹配
• openid.return_to 与 openid.realm 不匹配
• openid.mode 没有改为 check_authentication
• 回跳参数不完整

6.2 /openid/token 与资源接口

JSON 接口通常返回：

{
  "code": -1,
  "msg": "无权限",
  "data": {}
}

常见原因：

• access_token 缺失、伪造或过期
• refresh_token 缺失、伪造、过期或已轮换
• 当前 token 不包含目标资源所需授权范围
• 用户状态无效

7. 接入建议

• 第三方服务端保存 refresh_token，不要交给前端长期保存。
• access_token 可以按 expires_in 做本地过期判断。
• 调用资源接口返回无权限时，可先尝试使用 refresh_token 续签一次。
• 续签成功后必须替换本地保存的旧 refresh_token。
• 日志中应脱敏 access_token、refresh_token、openid.sig。
• 不要跳过 /openid/verify，也不要直接信任回跳 URL 中的用户 ID。

8. 流程总结

1. 第三方站点跳转用户到 /openid/login。
2. 用户在摸鱼派确认授权。
3. 摸鱼派回跳到 openid.return_to。
4. 第三方站点调用 /openid/verify。
5. is_valid:true 后保存用户标识、授权范围和令牌。
6. 使用 access_token 调用 /openid/user/*。
7. 使用 refresh_token 调用 /openid/token 续签。