OAuth 2.0 开放平台

适用场景

OAuth 2.0 开放平台用于第三方网站接入本站账号登录。用户在本站授权后，第三方后端可以换取 access_token，再读取用户 ID、昵称、头像、邮箱或手机号。

> 邮箱和手机号需要用户在授权页主动勾选。未授权时，userinfo 不返回对应字段。

接入入口

开放平台：`/open`
创建应用：`/open/apps`
运行 Demo：`/open/demo`
统一 OAuth 入口：`/open/oauth`

第一步：创建应用

进入「开放平台」后点击「创建应用」。填写应用名称、应用域名和回调地址。

创建成功后会生成：

`Client ID`：公开应用标识，用于授权 URL。
`Client Secret`：服务端密钥，只显示一次，请保存在第三方后端。

> redirect_uri 必须和创建应用时登记的回调地址完全一致，包括协议、域名、路径和末尾斜杠。

第二步：跳转授权

第三方网站登录按钮跳转到授权地址：

https://pan.yunxzi.cn/open/oauth?endpoint=authorize&response_type=code&client_id=你的 Client ID&redirect_uri=你的回调地址&scope=profile email phone&state=随机字符串

参数说明：

`endpoint`：固定为 `authorize`。
`response_type`：固定为 `code`。
`client_id`：应用的 `Client ID`。
`redirect_uri`：应用登记过的回调地址。
`scope`：授权范围，支持 `profile`、`email`、`phone`。
`state`：第三方生成的随机字符串，回调时必须校验。

第三步：处理回调

用户授权后，本站会跳转到你的回调地址，并携带：

?code=授权码&state=原样返回的 state

第三方服务端必须校验 state。校验通过后，用 code 换取 access_token。

第四步：用 code 换 Token

curl -X POST "https://pan.yunxzi.cn/open/oauth" \
  -d "endpoint=token" \
  -d "grant_type=authorization_code" \
  -d "code=回调收到的 code" \
  -d "client_id=你的 Client ID" \
  -d "client_secret=你的 Client Secret" \
  -d "redirect_uri=你的回调地址"

成功响应：

{
  "access_token": "ot_xxx",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "profile email"
}

第五步：获取用户资料

curl -H "Authorization: Bearer ot_xxx" "https://pan.yunxzi.cn/open/oauth?endpoint=userinfo"

响应示例：

{
  "id": 3,
  "username": "demo",
  "nickname": "Demo User",
  "avatar_url": "https://pan.yunxzi.cn/avatar.png",
  "email": "user@example.com",
  "phone": "13800000000"
}

Scope 说明

`profile`：默认授权，包含用户 ID、昵称、头像等基础资料。
`email`：用户勾选后返回邮箱。
`phone`：用户勾选后返回手机号。

常见错误

`invalid_request`：缺少必填参数，或请求方法错误。
`invalid_client`：`Client ID` 或 `Client Secret` 无效。
`invalid_grant`：授权码过期、已使用，或 `redirect_uri` 不匹配。
`invalid_token`：`access_token` 缺失、过期或已撤销。
`access_denied`：用户拒绝授权。

调试建议

先使用 `/open/demo` 跑通完整流程。
`Client Secret` 只能放在第三方服务端，不能放在前端页面。
`state` 必须在发起授权和回调处理时校验。
`access_token` 有效期为 7200 秒，过期后重新发起授权。

文档中心