跳到主要内容

注册应用

没有自助式的即时注册。从一个 Nanako 账号到一个可用的 client_id,中间隔着两步: 开发者审核,然后创建应用。

1. 申请开发者资格​

在 nanako.org 登录,打开开发者应用,提交申请。你需要填写 申请理由 —— 不少于 10 个字符,不超过 500 个字符,说明你打算做什么。这一步由人工审核。

同一时间只能有一份申请。已有待审核申请时无法再提交,已通过审核的账号也不能重复申请。

审核通过之前,创建应用会被拒绝。本页后面的内容默认你已经通过审核。

2. 创建应用​

在同一个开发者页面创建应用:

字段必填规则
名称是2–100 个字符
描述否最多 500 个字符
主页地址否会在授权页展示给用户
回调地址是至少一个;每个都必须以 http:// 或 https:// 开头
Scope否一个都不勾选时默认为 openid profile

名称和描述会展示给每一个被请求授权的用户,请按面向用户的口径来写。

回调地址规则​

回调地址会被逐字节比对已注册的列表 —— 授权请求到达时比一次,换取 token 时再比 一次。没有任何归一化处理:多一个斜杠、主机名大小写不同、多带一个参数,都是不同的 地址。

把你会用到的地址全部注册进去(开发环境和生产环境),并且原样回传你注册的那个字符串。

不要注册带查询字符串的回调地址

回调地址是通过追加 ?code=… 拼出来的。如果你的回调地址本身就带 ?,拼出来的 URL 是坏的,你的客户端根本取不到 code 参数。

注册 https://app.example.com/callback,不要注册 https://app.example.com/callback?source=nanako。要携带自己的状态,请用 state 参数。

myapp://callback 这类自定义 scheme 在注册时会被拒绝,所以 RFC 8252 的原生应用 方案目前还用不了。

3. 保存凭证​

创建成功后会返回凭证:

{
  "app": {
    "client_id": "8f14e45fceea167a5a36dedd4bea2543",
    "name": "Example App",
    "redirect_uris": ["https://app.example.com/callback"],
    "scopes": ["profile", "email"]
  },
  "client_secret": "kZ8mQ2vX7pL4nR9tY6wA3sD1fG5hJ0cV8bN2mK4xQ7E="
}
client_id32 位小写十六进制字符。公开信息 —— 它会出现在浏览器 URL 里。
client_secret44 个字符的 base64url,以 = 结尾。只显示一次,之后无法再取回。

立刻把它存进服务端的密钥管理系统。丢了只能重新生成 —— 而重新生成会让旧的立即失效。

结尾的 = 是密钥的一部分

client secret、授权码和两种 token 都以字面量 = 结尾。把它们放进表单编码的请求体 时必须做百分号编码(%3D)。直接字符串拼接会静默截断取值,然后你收到一个 invalid_client 或 invalid_grant,却没有任何可查的线索。

只要你把请求体作为参数字典交给 HTTP 库,而不是自己拼字符串,这件事库会替你做好。

注册时选择 scope​

你在注册时勾选的 scope,就是这个应用的允许集合。授权请求里出现集合之外的 scope 会被 invalid_scope 拒绝 —— 用户连授权页都看不到。

注册表单提供 profile、email 和 phone 三项。它不提供 openid,而 openid 恰恰是默认授权请求里的第一个 scope。所以:

每次都显式传 scope

授权请求里省略 scope 时,Nanako 默认按 openid profile 处理。通过网页表单注册的 应用,允许集合里没有 openid,于是这个默认值会失败:

{"error": "invalid_scope", "error_description": "scope 'openid' 不被允许"}

每次请求都显式传你实际注册过的那些 scope。见 Scope。

管理应用​

在开发者页面可以随时修改名称、描述、回调地址和 scope,重新生成 client secret, 以及删除应用。

重新生成密钥立即生效。任何还持有旧密钥的服务会在 token 端点收到 401 invalid_client —— 先把新密钥部署上去,否则要接受一段登录失败的窗口期。

删除应用对所有人生效:已有授权全部作废,用户无法再通过它登录。

查看活动记录​

两个只读视图可以帮你确认对接是否正常:

  • 已授权应用 —— 用户批准过哪些应用,以及撤销其中任意一个的入口。
  • 授权日志 —— authorize、token、userinfo 事件,含时间、IP、设备类型和结果。

两者都在 Nanako 账号界面里,而且都是按用户维度的:你看到的是你自己的活动,不是你 用户的。

注意只有首次换取 token 会被记录。之后 30 天里的静默刷新不会出现在日志里,所以 日志安静并不代表对接不活跃。

最后于 更新