开发指南

1. 准备工作

Ksuser 开放连接基于 OAuth 2.0 authorization_code 模式。

接入前请先在开放平台创建应用并拿到：

• AppID（对应 client_id）
• AppSecret（对应 client_secret，仅创建时展示一次）
• 已登记的 redirect_uri

1.1 应用创建要求

• 账号认证类型需为 personal 或 enterprise
• 单个认证账号最多创建 5 个 OAuth2 应用
• 应用名称长度：2-100 字符
• 联系方式长度：3-120 字符
• 回调地址限制：
  • 支持 https://...
  • 支持 http://localhost...（本地开发）
  • 不允许 URL fragment（#...）
• 当前支持 scope：profile、email

2. 授权流程

第一步：引导用户到授权确认页

第三方网站将用户重定向到：

https://auth.ksuser.cn/oauth/authorize?client_id=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=profile%20email&state=STATE

参数说明

参数	必填	说明
client_id	是	应用 AppID
redirect_uri	是	应用登记的回调地址，必须完全一致
response_type	是	固定为 code
scope	否	申请权限，空格或逗号分隔，支持 profile、email
state	否	原样回传，建议用于 CSRF 防护

授权结果

• 用户同意：跳转到 redirect_uri?code=...&state=...
• 用户拒绝：跳转到 redirect_uri?error=access_denied&error_description=user denied the authorization request&state=...

说明：code 为一次性授权码，默认 300 秒过期，且使用后立即失效。

3. 通过 code 换取 access_token

请求地址

POST https://api.ksuser.cn/oauth2/token

请求方式

使用 application/x-www-form-urlencoded 传参。

curl -X POST 'https://api.ksuser.cn/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=kscode_xxx' \
  --data-urlencode 'client_id=ksapp_xxx' \
  --data-urlencode 'client_secret=kssecret_xxx' \
  --data-urlencode 'redirect_uri=https://example.com/oauth/callback'

参数说明

参数	必填	说明
grant_type	是	固定为 authorization_code
code	是	第一步获取的一次性授权码
client_id	是	应用 AppID
client_secret	是	应用 AppSecret
redirect_uri	是	必须与应用登记值一致

成功返回示例

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "profile email",
  "openid": "oid_xxx",
  "unionid": "uid_xxx"
}

说明：当前实现不提供 refresh_token。

失败返回示例

{
  "error": "invalid_grant",
  "error_description": "授权码无效、已过期或已使用"
}

/oauth2/token 和 /oauth2/userinfo 发生错误时，返回 OAuth 标准错误格式：

• error
• error_description

4. 使用 access_token 获取用户信息

请求地址

GET https://api.ksuser.cn/oauth2/userinfo

支持两种传 token 的方式（优先使用 Header）：

• Header：Authorization: Bearer <ACCESS_TOKEN>
• Query：?access_token=<ACCESS_TOKEN>

curl 'https://api.ksuser.cn/oauth2/userinfo' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

返回字段

• 固定字段：openid、unionid
• 当授权包含 profile：返回 nickname、avatar_url（头像为空时可能不返回）
• 当授权包含 email：返回 email（用户无邮箱时可能不返回）

成功返回示例

{
  "openid": "oid_xxx",
  "unionid": "uid_xxx",
  "nickname": "demo_user",
  "avatar_url": "https://cdn.example.com/avatar.png",
  "email": "demo@example.com"
}

5. Scope 与数据权限映射

scope	可获取字段
（不传 scope）	openid、unionid
profile	openid、unionid、nickname、avatar_url
email	openid、unionid、email
profile email	openid、unionid、nickname、avatar_url、email

6. 认证端开放平台管理接口（应用方后台）

以下接口用于“开发者在 Ksuser 平台内管理自己的 OAuth2 应用”，均走业务统一响应：

{
  "code": 200,
  "msg": "获取成功",
  "data": {}
}

6.1 获取应用列表

• GET /oauth2/apps
• 需要登录态（Bearer 业务 token）

返回 data 包含：

• verificationType、verified
• maxApps、currentCount、canCreate
• apps[]（appId、appName、redirectUri、contactInfo、scopes、createdAt、updatedAt）

6.2 创建应用

• POST /oauth2/apps
• 需要登录态

请求体示例：

{
  "appName": "Demo App",
  "redirectUri": "https://example.com/oauth/callback",
  "contactInfo": "dev@example.com",
  "scopes": ["profile", "email"]
}

成功时返回 201，data 额外包含一次性的 appSecret。

6.3 编辑应用

• PUT /oauth2/apps/{appId}
• 需要登录态
• 仅可修改：appName、redirectUri、contactInfo

6.4 删除应用

• DELETE /oauth2/apps/{appId}
• 需要登录态

7. 常见错误与排查

• invalid_request：参数缺失、格式不对、redirect_uri 不匹配
• invalid_client：client_id 不存在/停用，或 client_secret 错误
• unsupported_response_type：response_type 不是 code
• unsupported_grant_type：grant_type 不是 authorization_code
• invalid_scope：请求了未登记或不支持的 scope
• invalid_grant：授权码无效、过期、已使用，或与应用信息不匹配
• invalid_token：Access Token 无效或过期

8. 安全建议

• client_secret 只能存储在服务端，禁止下发到前端。
• state 必须校验，防止 CSRF。
• code 只能使用一次，回调后应立即换 token。
• 业务登录态请由你自己的服务端维护，不要直接把第三方 access_token 暴露给浏览器长期保存。