OAuth 与终端接入
本页内容
网页、Vue 和移动端可以在用户同意后访问其选定应用,也可以通过自己的服务端调用 API。使用 OAuth 时,需要完成客户端登记、PKCE 授权和令牌管理。
选择终端接入方式
| 方案 | 适用情况 | 凭据放在哪里 |
|---|---|---|
| 通过自己的服务端调用 | 已有后端,由后端完成认证与业务处理 | 长期 Secret 保存在后端 |
| OAuth 用户授权 | 需要用户明确选择应用并同意第三方访问 | 终端只持有授权令牌,不内置长期 Secret |
下面说明 OAuth 流程。浏览器、Vue 和移动端使用 public 客户端;能保管 Client Secret 的服务端可使用 confidential 客户端。
登记 OAuth 客户端
- 在开发者中心登记用途、客户端类型和精确 HTTPS 回调地址,完成接入申请。
- 从授权服务器元数据读取 issuer、端点、支持的 scope 和认证方法。
- 确定最少需要的动作。终端上传或签名还需对应独立许可,并仅操作用户选定的已有应用。
客户端登记不等于获得用户授权。实际可访问范围以本次用户同意及当前平台授权为准。各端点的完整字段、响应和错误说明见OAuth 接口参考。
取得授权码并换取令牌
- 为每次授权生成随机 state 和 PKCE verifier,并与这次用户会话一起保存。
- 用 verifier 的 SHA-256 原始摘要计算无填充 Base64URL challenge。
- 在系统浏览器打开授权端点,填写 client_id、精确 redirect_uri、response_type=code、scope、state、code_challenge 和 code_challenge_method=S256。
- 回到登记地址后,先核对 state 与 iss,再使用原 verifier 将一次性 code 换为令牌。
import base64
import hashlib
import hmac
import secrets
def new_oauth_attempt():
verifier = secrets.token_urlsafe(32)
challenge = base64.urlsafe_b64encode(
hashlib.sha256(verifier.encode("ascii")).digest()
).rstrip(b"=").decode("ascii")
return {"state": secrets.token_urlsafe(32),
"verifier": verifier, "challenge": challenge}
def validate_oauth_callback(expected_state, state, expected_issuer, issuer):
if not all(isinstance(value, str) and value for value in
(expected_state, state, expected_issuer, issuer)):
raise ValueError("授权响应缺少 state 或 iss")
if not hmac.compare_digest(expected_state.encode(), state.encode()):
raise ValueError("授权 state 不匹配")
if not hmac.compare_digest(expected_issuer.encode(), issuer.encode()):
raise ValueError("授权签发方不匹配")POST /oauth.php?action=token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&client_id=<客户端ID>&redirect_uri=<编码后的原回调地址>&code=<授权码>&code_verifier=<原verifier>scope 中多个动作以空格分隔,作为查询参数时进行 URL 编码。confidential 客户端在受信服务端另传 client_secret;public 客户端不内置此 Secret。用户拒绝授权或回调校验失败时结束本次流程。
使用、刷新与撤销
使用 Authorization: Bearer <access_token> 请求已授权的 API。写入仍需 JSON 和幂等键;浏览器直连还需批准精确 Origin。
根据响应中的 expires_in 管理有效期。刷新时向 Token 端点提交 grant_type=refresh_token、当前 refresh_token 和 client_id,并按客户端类型完成认证。成功后原子替换整组令牌,同一会话不要并发刷新。访问令牌也会随刷新替换;旧刷新令牌再次出现可能使整组授权撤销。
退出或撤权时使用 /oauth.php?action=revoke,它会撤销对应整组授权。令牌和 Secret 不写入 URL、公开日志或跨站共享存储。响应丢失等情况按刷新与恢复说明处理。
确认授权与异常处理
先执行当前身份或一个已选应用的只读查询。401 时核对令牌是否过期、刷新是否已替换旧值;403 或 404 时核对用户同意的动作、应用范围和功能许可。不要通过重新登录跳过用户同意,也不要将 Bearer 与 CS1 请求头一起发送。