1. 背景说明

随着摸鱼派社区生态的不断扩展，越来越多第三方应用希望接入摸鱼派账号体系，以便用户能够使用摸鱼派账号在不同应用间快捷登录并复用身份信息。
为满足该需求，摸鱼派提供了一套类 OAuth / OpenID 的第三方登录能力：第三方应用可引导用户跳转至摸鱼派完成认证，并在认证通过后获得用户唯一标识，随后可据此调用接口获取基础用户信息，从而避免重复注册与多账号割裂问题。

2. 能力概览

本登录能力支持以下流程与功能：

• 第三方应用发起登录请求后，跳转至摸鱼派统一认证页面；
• 用户确认授权后，摸鱼派将重定向回第三方应用并携带用户唯一标识等参数；
• 第三方应用可通过签名校验接口验证返回参数的真实性；
• 校验通过后，可根据用户 ID 调用接口获取用户基础信息（如用户名、昵称、头像等）。

3. 接入流程

3.1 发起登录：获取授权链接（GET）

第三方应用应构造如下地址并发起 GET 请求（请自行补全域名）：

/openid/login?openid.ns=...&openid.mode=...&...

请求参数

示例

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%2Ftest.sszsj.com%2Flogin.html&openid.realm=https%3A%2F%2Ftest.sszsj.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

注意事项：

1. 参数错误可能导致服务端返回 500，请优先检查参数拼写与取值。
2. URL 参数请按规范进行编码（encode）。

3.2 用户确认授权后回跳：接收回调参数（Redirect）

用户在摸鱼派认证页确认后，摸鱼派将重定向回 openid.return_to 指定地址，并在 URL 中携带一组参数。常见参数如下：

3.3 签名校验：验证返回参数真实性（POST）

第三方应用必须对回跳参数进行签名校验，以确认该结果确由摸鱼派生成，且未被篡改。

接口

POST /openid/verify

请求说明

• 将回跳收到的参数原样放入请求 body；
• 将 openid.mode 改为 check_authentication；
• Content-Type: application/json

示例请求体

{
  "openid.ns": "http://specs.openid.net/auth/2.0",
  "openid.mode": "check_authentication",
  "openid.op_endpoint": "op_endpoint",
  "openid.return_to": "return_to",
  "openid.identity": "identity",
  "openid.claimed_id": "claimed_id",
  "openid.response_nonce": "response_nonce",
  "openid.assoc_handle": "assoc_handle",
  "openid.sig": "sig"
}

返回结果

返回内容为纯文本（非 JSON），示例：

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

当 is_valid:true 时表示校验通过；否则应视为无效登录结果，不应使用其中的用户标识。

安全提示：

• openid.response_nonce 为一次性参数，使用后即失效。
• openid.response_nonce 有效期为 5 分钟，过期应拒绝接受并重新发起登录。

3.4 获取用户信息（GET）

在签名校验通过后，可使用用户 ID 获取用户基础信息。

接口

GET /api/user/getInfoById?userId=123456

返回内容为该用户的基础资料（如用户名、昵称、头像等）。具体字段以接口实际返回为准，建议在接入联调阶段完成字段映射与兼容处理。

4. 常见问题（FAQ）

Q1：登录失败并返回 500，是服务异常吗？
A：多数情况为请求参数不符合要求。请重点检查 openid.realm 与 openid.return_to：必须为 HTTPS，且 realm 必须为 return_to 的前缀。

Q2：签名如何验证？
A：回跳参数中 openid.signed 指明参与签名的字段集合。验证方式为将参数回传至 /openid/verify 并将 openid.mode 设置为 check_authentication。

Q3：可以不做签名校验吗？
A：不建议。跳过签名校验将导致身份结果可被伪造或篡改，存在严重安全风险。

Q4：是否可以直接使用回跳中的 ID 作为登录凭证？
A：必须在 /openid/verify 校验通过后，才能将该 ID 视为可信用户标识并进行登录绑定。

5. 流程总结

1. 第三方构造 /openid/login 链接并跳转至摸鱼派；
2. 用户在摸鱼派完成确认后回跳至 return_to；
3. 第三方调用 /openid/verify 校验返回参数签名；
4. 校验通过后使用用户 ID 调用 /api/user/getInfoById 获取用户资料并完成登录态建立。