跳到主要内容

第 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。
  • 授权确认页:显示应用、创建者和每一项权限的说明;已经允许过的应用不再询问。
  • 应用与令牌页面(/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)​

  1. 用 API 初始化站点,注册 dev 和 alice;dev 注册一个服务端应用,回调地址指向本站一个不存在的页面,方便看跳转结果。
  2. 浏览器未登录时打开 /oauth/authorize?…&scope=User.Read Player.ReadWrite Closet.ReadWrtie&state=…:先跳到登录页,next 带着完整的授权参数;alice 登录后回到确认页,页面显示"Forum 想要访问你的账号,由 dev 创建"和三项权限,拼错的 scope 显示为 Closet.ReadWrite。
  3. 点"授权",浏览器回到回调地址,带着 code 和原来的 state。
  4. 用 curl 以 HTTP Basic 兑换授权码,得到 slo_ / slr_ 令牌,有效期 86400 秒;同一个授权码再兑换一次返回 invalid_grant。
  5. 用访问令牌:
    • /api/user 返回 BS 格式的用户;
    • 添加角色 Steve 返回 {"code":0,…},列表里有它;
    • 没有 Notification.Read 时读通知返回 403;
    • 空衣柜返回 Laravel 分页格式。
  6. 刷新令牌换到新的一对,旧的访问令牌立即 401。/api 和元数据端点正常。
  7. 再次打开授权地址(只要 User.Read),没有出现确认页,直接带着新的 code 回到应用。
  8. "应用与令牌"页面:已授权的应用里有 Forum 和三项权限;普通用户的权限列表里没有管理类权限。在页面上创建一个只有 Player.Read 的个人访问令牌:读角色 200,读用户和写角色都是 403;列表显示了最近使用时间。服务端日志没有警告或错误。

测试​

  • 服务层(SQLite 与 PostgreSQL):
    • scope 解析、旧拼写、ReadWrite 包含 Read、管理类过滤;
    • 应用的增删改、回调地址校验、只有主人能改、重置密钥后旧密钥失效;
    • 授权请求:不跳转的错误(未知应用、未登记的回调、有多个回调却没指明)与跳回应用的错误(state 保留),已授权时跳过确认,主人被封禁后停用;
    • 授权码:客户端认证、另一个应用拿不到、回调地址不一致、只能用一次、5 个并发兑换只有 1 个成功;PKCE 校验失败后授权码作废,公开客户端不能带密钥;
    • 刷新:轮换、缩小、不能扩大、只能由原应用刷新、过期;
    • 撤销授权、RFC 7009 吊销、个人访问令牌(权限、过期、最近使用、清理)、封禁与注销的账号;
    • 退出其它设备后应用令牌与个人访问令牌全部失效。
  • HTTP:从注册应用、授权、兑换到每个兼容接口、个人访问令牌、撤销、元数据、CORS 预检走一遍。
  • 全量回归:
    • Go:go test ./...(SQLite 与 PostgreSQL)、vet、staticcheck、govulncheck;
    • 生成代码无差异、迁移无漂移;
    • 前端:类型检查、单元测试、生产构建、bun audit。

问题与风险​

  • 没有拿真实的 Blessing Skin 第三方应用(比如论坛插件)实际接一次,只按 Passport 的协议和 BS 的代码对照验证。
  • 资源 API 的限流和登录限流一样在每个实例的内存里。
  • 访问令牌默认 1 天,比 BS 的一年短很多;从不刷新令牌的旧应用会在一天后失效,需要时站长可以调长。

下期计划​

M3 第三部分:兼容 BS 的管理类接口(/api/admin/*);之后是社交登录。