OAuth 2.1 API 参考

UserMatrix 官方统一身份标准 — OAuth 2.1 + OIDC 端点完整说明。

本文列举的是云集生态官方统一标准端点：OAuth 2.1 + OIDC。所有对接方式（SDK / 二维码 / REST 兼容）最终都收敛于此标准。通用 OAuth 库（Auth.js / Spring Security / authlib）可通过 OIDC Discovery 直接接入，无需安装 UM SDK。

基础信息

项目值
Issuerhttps://um.yunjii.cn
协议OAuth 2.1 + OpenID Connect
数据格式JSON
令牌类型Bearer
支持的 grant_typeauthorization_code / refresh_token / client_credentials
PKCES256（可选校验，um_config.oauth_force_pkce 开关可强制）
code 有效期5 分钟，单次消费
access_token 有效期168 小时（7 天）
refresh_token 有效期30 天（轮换制，每次刷新签发新 token，旧 token 失效）

端点列表

1. 授权端点

GET https://um.yunjii.cn/oauth/authorize

引导用户跳转到 UM 授权页，用户完成扫码/登录后，携带 code 回调到 redirect_uri。

参数

参数必填说明
response_type是固定 code
client_id是应用 ID（appid）
redirect_uri是回调地址（域名需在控制台应用配置的 domains 中）
state是防 CSRF，随机字符串，原样回传
scope否openid profile（默认）/ openid profile email
code_challenge否PKCE code_challenge（启用 PKCE 时传）
code_challenge_method否S256（启用 PKCE 时传）
timestamp否时间戳（SDK 签名用，标准 OAuth 库可不传）
sign否MD5 签名（SDK 签名用，标准 OAuth 库可不传）

流程

你的应用                    UM 授权页                   用户
  │                            │                         │
  │── GET /oauth/authorize ──→│                         │
  │                            │── 展示扫码/登录页 ─────→│
  │                            │←── 用户扫码/授权 ───────│
  │←── 302 redirect_uri?code= │                         │
  │                            │                         │
  │── POST /oauth/token ─────→│（下一步）                │

code 5 分钟内只能消费一次，重复消费返回 errcode=40163。

2. 令牌端点

POST https://um.yunjii.cn/oauth/token
Content-Type: application/x-www-form-urlencoded

支持三种 grant_type：

2.1 Authorization Code（授权码换 token）

参数

参数必填说明
grant_type是authorization_code
code是回调得到的授权码
client_id是应用 ID
client_secret是应用密钥（appkey）
redirect_uri是必须与授权时一致
code_verifier否PKCE code_verifier（启用 PKCE 时必传）

响应

{
  "code": 0,
  "msg": "succ",
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "rt_a1b2c3d4e5f6...",
  "user": {
    "id": 12345,
    "openid": "um_a1b2c3d4e5f6",
    "nickname": "张三",
    "avatar": "https://thirdwx.qlogo.cn/...",
    "login_type": "wx"
  }
}
字段说明
access_token访问令牌（Bearer），后续 API 调用凭证
refresh_token刷新令牌，用于续期（30 天有效，轮换制）
expires_inaccess_token 有效期（秒），默认 604800（7 天）
user.openid应用内用户唯一 ID（同应用不变）
user.id用户内部 ID
user.login_type登录方式（wx / alipay / qq / douyin / email / self）

2.2 Refresh Token（刷新令牌 · 轮换制）

参数

参数必填说明
grant_type是refresh_token
refresh_token是上一次获取的 refresh_token
client_id是应用 ID
client_secret是应用密钥

响应

{
  "code": 0,
  "msg": "succ",
  "access_token": "eyJhbGciOiJIUzI1NiIs...(新)",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "rt_new_xxx...(新)",
  "scope": "app"
}

Refresh Token 轮换：每次刷新签发新的 refresh_token，旧的立即失效。客户端必须用最新的 refresh_token 进行下次刷新。

2.3 Client Credentials（机器到机器）

用于家族产品互联、无用户上下文的服务间调用。

参数

参数必填说明
grant_type是client_credentials
client_id是应用 ID
client_secret是应用密钥
scope否作用域

响应

{
  "code": 0,
  "msg": "succ",
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 604800,
  "scope": "app"
}

3. UserInfo 端点（OIDC）

GET https://um.yunjii.cn/oauth/userinfo
Authorization: Bearer <access_token>

返回标准 OIDC claims。

响应

{
  "sub": "um_a1b2c3d4e5f6",
  "user_id": 12345,
  "name": "张三",
  "nickname": "张三",
  "preferred_username": "zhangsan",
  "picture": "https://thirdwx.qlogo.cn/...",
  "email": "zhangsan@example.com",
  "email_verified": true,
  "gender": "male",
  "location": "北京",
  "login_type": "wx",
  "updated_at": 1720900000,
  "iss": "https://um.yunjii.cn"
}
字段说明
sub用户唯一标识（UMID，跨应用一致）
name显示名
nickname昵称
picture头像 URL
email邮箱（可能为空）
email_verified邮箱是否已验证
login_type登录方式
issIssuer

错误响应

HTTPerrcode说明
401401未提供 / 无效 / 过期的 access_token

除 OIDC 只读的 /oauth/userinfo 外，登录后的应用如需读写全量资料（昵称/性别/所在地/手机/邮箱/用户名，含 balance/score 等扩展字段），使用统一的 用户资料 API（/user）。

4. 令牌撤销端点（RFC 7009）

POST https://um.yunjii.cn/oauth/revoke
Content-Type: application/x-www-form-urlencoded

参数

参数必填说明
token是要撤销的 access_token 或 refresh_token
token_type_hint否access_token / refresh_token
client_id是应用 ID
client_secret是应用密钥

响应：HTTP 200（成功撤销，RFC 7009 规定始终返回 200）

5. OIDC Discovery

GET https://um.yunjii.cn/.well-known/openid-configuration

返回标准 OIDC Discovery JSON，通用 OAuth 库自动读取。

响应

{
  "issuer": "https://um.yunjii.cn",
  "authorization_endpoint": "https://um.yunjii.cn/oauth/authorize.php",
  "token_endpoint": "https://um.yunjii.cn/oauth/token.php",
  "userinfo_endpoint": "https://um.yunjii.cn/oauth/userinfo.php",
  "revocation_endpoint": "https://um.yunjii.cn/oauth/revoke.php",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token", "client_credentials"],
  "scopes_supported": ["openid", "profile", "email"],
  "token_endpoint_auth_methods_supported": ["client_secret_post"],
  "code_challenge_methods_supported": ["S256", "plain"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["HS256"],
  "claims_supported": [
    "sub", "name", "nickname", "preferred_username", "picture",
    "email", "email_verified", "gender", "location", "login_type", "updated_at"
  ]
}

Auth.js / NextAuth.js / Spring Security / authlib 等通用库只需配置此 discovery URL 即可自动接入，无需安装 UM 专属 SDK。

PKCE（Proof Key for Code Exchange）

OAuth 2.1 核心安全机制，防止授权码被中间人劫持。公开客户端（SPA / 小程序 / APP）强烈推荐启用。

流程

1. 客户端生成 code_verifier（43-128 字符随机串）
2. 计算 code_challenge = base64url(SHA256(code_verifier))
3. 授权请求携带 code_challenge + code_challenge_method=S256
4. 换 token 时携带 code_verifier
5. 服务端校验 base64url(SHA256(code_verifier)) == code_challenge

强制开关

um_config.oauth_force_pkce：

  • 0（默认）：可选校验（向后兼容）
  • 1：强制校验（OAuth 2.1 合规，迁移窗口结束后开启）

观察期结束后将开启强制 PKCE。新接入应直接使用 PKCE，避免后续迁移。

签名算法（SDK 兼容用）

标准 OAuth 2.1 端点使用 client_secret 鉴权（无需签名）。UM SDK 额外携带 timestamp + sign 参数以兼容旧版防重放机制，标准 OAuth 库无需传这两个参数。

如需手动构造签名（旧版 REST 接口）：

// 1. 收集所有参数（除 sign 外），按 key 字典序排列
ksort($params);

// 2. 拼接成字符串，末尾加 appkey
$signStr = '';
foreach ($params as $k => $v) $signStr .= "$k=$v&";
$signStr .= "appkey=$appkey";

// 3. MD5
$sign = md5($signStr);

timestamp 必须在当前时间 ±5 分钟内，否则返回 errcode=105。

兼容接口（Legacy REST）

以下旧版 REST 端点保留以兼容老应用，新接入请使用上述 OAuth 2.1 标准端点。

端点说明替代方案
GET /connect.php?act=login生成登录跳转 URLGET /oauth/authorize
GET /connect.php?act=callbackcode 换用户信息POST /oauth/token + GET /oauth/userinfo
GET /connect.php?act=querysocial_uid 二次查询GET /oauth/userinfo
GET /connect.php?act=check_ssoSSO 状态检查OAuth 2.1 SSO（session-based）
GET /check_token.phpToken 验证GET /oauth/userinfo（Bearer 验证）

旧版 REST 接口使用 code: 1 表示成功；OAuth 2.1 标准端点使用 code: 0 表示成功。迁移时注意判断条件。

限流规则

  • IP 限流：单 IP 60 次/分钟
  • 登录失败：单 IP 5 分钟内失败 10 次锁定 15 分钟
  • code 消费：单 code 只能消费一次，5 分钟过期
  • refresh_token 轮换：旧 refresh_token 刷新后立即失效

HTTP 状态码

HTTP含义
200请求成功（业务 code 可能非 0）
400参数错误
401鉴权失败
403权限不足
404资源不存在
429限流
500服务器错误

完整错误码见 错误码参考。

相关文档

云集防红系统

活码/防封链接与渠道统计，支持 UM 账号快捷登录（同时保留自有账号体系）。

用户资料 API（/user 身份能力域）

全量用户资料读写 JSON API — "数据在 UM，UI 在各应用" 的统一契约。