第 15 期 · M3 第二部分:OAuth 2.0 与开放 API
· 阅读需 6 分钟
M3 第二部分让其它网站和程序可以"用云织账号登录":云织现在是一个 OAuth 2.0 授权服务器,资源接口与 Blessing Skin 相同,为 BS 写的应用换个地址就能用。用户也可以创建个人访问令牌,给自己的脚本使用。
本期完成
- 授权服务器(
internal/oauth):- 授权码流程,支持 PKCE(
S256、plain)、刷新令牌(每次使用都换新的)、吊销(RFC 7009)、服务器元数据(RFC 8414); - 令牌端点接受表单或 JSON,客户端凭据放 HTTP Basic 或表单都行;错误是 RFC 6749 的格式,再加 Passport 客户端读的
message。
- 授权码流程,支持 PKCE(
- 授权确认页:显示应用、创建者和每一项权限的说明;已经允许过的应用不再询问。
- 应用与令牌页面(
/user/oauth/manage,BS 的同名页面):- 我的应用:服务端应用(密钥只显示一次,可以重置)或公开客户端(必须用 PKCE);
- 已授权的应用:查看、撤销;
- 个人访问令牌:选权限和有效期,显示最近使用时间。
- 兼容 BS 的资源 API:
/api、/api/user、通知、角色、衣柜的读写,模型字段、{code, message, data}、Laravel 的 422 格式都与 BS 一致。 - 改密码、找回密码、封禁、注销、退出其它设备时,应用的令牌和个人访问令牌一起失效。
- 设计记录:ADR 0023;文档站新增开放平台。
为什么没有用 OIDC 库
设计文档原本选了 zitadel/oidc。真正需要的只是授权码 + PKCE、刷新、吊销,状态全在自己的四张表里,还要和网页会话在同一个事务里吊销。这个库以 OIDC 为中心,要实现一整套存储接口,还会带进不少依赖。所以先自己实现这一小块,等做 Yggdrasil Connect(OIDC)时再决定是在这套表上加 ID Token,还是引入库。
修掉的 BS 问题
- 应用密钥明文保存,并一直显示在页面上;访问令牌默认一年。
- 衣柜写权限注册成了拼错的
Closet.ReadWrtie,路由却要Closet.ReadWrite,第三方应用永远拿不到;现在两种写法都接受。 - 改密码、找回密码不吊销 OAuth 令牌;删除用户留下孤儿令牌。
- 读不存在的通知报 500;衣柜分页
perPage没有上限。
开发中发现的问题
- PostgreSQL 事务里的唯一冲突:最早的写法是在一个事务里先
SELECT … FOR UPDATE授权记录,没有就插入、冲突了当作已存在,然后写授权码。编译时发现这一版 ent 没有开行锁;而且这个写法在 PostgreSQL 上本来就不成立:事务里一旦有语句出错,整个事务作废,后面写授权码也会失败。改成先写授权记录(不放事务里,冲突时重读再合并),再单独写授权码。 - Huma 不展开请求体里的嵌入结构体:确认授权的请求体复用了查询参数的结构体,结果每个字段都被报"unexpected property"。改为把字段逐个写出来。
- 兼容接口里的 HTML:Go 的 JSON 默认把
<转义成<。通知正文是 HTML,PHP 的json_encode不会这样转义,兼容接口里关掉了。
本地实测(skinloom up --dev)
- 用 API 初始化站点,注册 dev 和 alice;dev 注册一个服务端应用,回调地址指向本站一个不存在的页面,方便看跳转结果。
- 浏览器未登录时打开
/oauth/authorize?…&scope=User.Read Player.ReadWrite Closet.ReadWrtie&state=…:先跳到登录页,next带着完整的授权参数;alice 登录后回到确认页,页面显示"Forum 想要访问你的账号,由 dev 创建"和三项权限,拼错的 scope 显示为Closet.ReadWrite。 - 点"授权",浏览器回到回调地址,带着
code和原来的state。 - 用 curl 以 HTTP Basic 兑换授权码,得到
slo_/slr_令牌,有效期 86400 秒;同一个授权码再兑换一次返回invalid_grant。 - 用访问令牌:
/api/user返回 BS 格式的用户;- 添加角色 Steve 返回
{"code":0,…},列表里有它; - 没有
Notification.Read时读通知返回 403; - 空衣柜返回 Laravel 分页格式。
- 刷新令牌换到新的一对,旧的访问令牌立即 401。
/api和元数据端点正常。 - 再次打开授权地址(只要
User.Read),没有出现确认页,直接带着新的code回到应用。 - "应用与令牌"页面:已授权的应用里有 Forum 和三项权限;普通用户的权限列表里没有管理类权限。在页面上创建一个只有
Player.Read的个人访问令牌:读角色 200,读用户和写角色都是 403;列表显示了最近使用时间。服务端日志没有警告或错误。
测试
- 服务层(SQLite 与 PostgreSQL):
- scope 解析、旧拼写、
ReadWrite包含Read、管理类过滤; - 应用的增删改、回调地址校验、只有主人能改、重置密钥后旧密钥失效;
- 授权请求:不跳转的错误(未知应用、未登记的回调、有多个回调却没指明)与跳回应用的错误(
state保留),已授权时跳过确认,主人被封禁后停用; - 授权码:客户端认证、另一个应用拿不到、回调地址不一致、只能用一次、5 个并发兑换只有 1 个成功;PKCE 校验失败后授权码作废,公开客户端不能带密钥;
- 刷新:轮换、缩小、不能扩大、只能由原应用刷新、过期;
- 撤销授权、RFC 7009 吊销、个人访问令牌(权限、过期、最近使用、清理)、封禁与注销的账号;
- 退出其它设备后应用令牌与个人访问令牌全部失效。
- scope 解析、旧拼写、
- HTTP:从注册应用、授权、兑换到每个兼容接口、个人访问令牌、撤销、元数据、CORS 预检走一遍。
- 全量回归:
- Go:
go test ./...(SQLite 与 PostgreSQL)、vet、staticcheck、govulncheck; - 生成代码无差异、迁移无漂移;
- 前端:类型检查、单元测试、生产构建、
bun audit。
- Go:
问题与风险
- 没有拿真实的 Blessing Skin 第三方应用(比如论坛插件)实际接一次,只按 Passport 的协议和 BS 的代码对照验证。
- 资源 API 的限流和登录限流一样在每个实例的内存里。
- 访问令牌默认 1 天,比 BS 的一年短很多;从不刷新令牌的旧应用会在一天后失效,需要时站长可以调长。
下期计划
M3 第三部分:兼容 BS 的管理类接口(/api/admin/*);之后是社交登录。