使用 Nanako 账号登录
Nanako 是一个 OAuth 2.0 授权服务器。你的应用把用户带到 Nanako,用户确认你申请的 权限,你拿到一个能标识这个用户的 access token。
这就是给你的产品加一个使用 Nanako 账号登录按钮所需要的东西。它不是通用的 API key 机制 —— 目前 access token 唯一能读到的,是已登录用户的个人资料。
你能做什么
| 服务端 Web 应用 | ✅ 支持,而且是唯一完整支持的形态 |
| 命令行工具或带回调的后端服务 | ✅ 支持 |
| 纯浏览器单页应用 | ⚠️ 需要运营方把你的来源加入白名单 —— 见客户端类型 |
| 原生移动端或桌面应用 | ❌ 暂不支持 —— 无法注册 myapp://callback 这类自定义 scheme 回调 |
| 无用户参与的机器对机器调用 | ❌ 暂不支持 —— 没有 client credentials 模式 |
流程
Nanako 实现的是授权码模式(RFC 6749 §4.1),可选 PKCE(RFC 7636),支持 refresh token。
你的应用 Nanako 用户
│ │ │
│ 1. 重定向到 /oauth/authorize ─────────────────────────►│
│ │ 2. 登录、确认权限、同意 │
│◄─ 3. 带 ?code=… 重定向回你的回调地址 ──────────────────│
│ │ │
│ 4. POST /oauth/token(code + 凭证)──────────►│ │
│◄─ 5. access_token + refresh_token ──────────│ │
│ │ │
│ 6. GET /oauth/userinfo(Bearer access_token)►│ │
│◄─ 7. 用户资料 ──────────────────────────────│ │
逐步操作、可直接运行的命令:授权码流程。
端点
所有 OAuth 端点都挂在 API 主机的根路径下 —— 不在 /api/v1 下面。
| 用途 | 端点 |
|---|---|
| 授权 | GET https://api.nanako.org/oauth/authorize |
| 令牌 | POST https://api.nanako.org/oauth/token |
| 用户信息 | GET https://api.nanako.org/oauth/userinfo |
| 撤销 | POST https://api.nanako.org/oauth/revoke |
同样这四个路径在 https://www.nanako.org 上也可用。两个主机都行,选一个用到底。
/.well-known/openid-configuration 上确实有一份文档,但它列出的
token_endpoint、userinfo_endpoint 和 revocation_endpoint 是错的 ——
它们带了一个 /api/v1 前缀,访问会返回 404。把 OIDC 客户端库指向这份文档,
会在换取 token 那一步失败。
在本页面另行说明之前,请手动配置上面这四个端点。
客户端类型
机密客户端(confidential client) 跑在你自己控制的服务器上,能把
client_secret 保密。本文档所有内容都是围绕这种形态设计的。你用
client_id + client_secret 向 token 端点认证。
公开客户端(public client) 无法保存密钥,改用 PKCE:授权请求带上
code_challenge,换取 token 时带上对应的 code_verifier。Nanako 支持这种方式,
但有两个限制需要提前规划:
- 刷新和撤销始终需要
client_secret。公开客户端会收到一个它永远无法使用的refresh_token,也无法调用撤销端点。实际效果是:公开客户端的会话在 access token 两小时后过期时结束。 - 浏览器应用还要过 CORS 这一关。Nanako 的白名单由运营方配置,没有通配符,第三方 网页来源默认被拦截。要做这类应用请先联系我们。
只要你能跑任何服务端组件,就把它做成机密客户端。
限制与有效期
| 授权码有效期 | 10 分钟,只能使用一次 |
| Access token 有效期 | 2 小时(expires_in: 7200) |
| Refresh token 有效期 | 自首次授权起 30 天 |
| Refresh token 轮换 | 每次使用都会返回新的 refresh token,旧的立即失效 |
| 令牌格式 | 不透明字符串,44 个字符,base64url,带一个 = 填充 |
| 客户端认证 | 仅 client_secret_post —— 表单字段,不支持 HTTP Basic |
| 请求编码 | /oauth/token 与 /oauth/revoke 使用 application/x-www-form-urlencoded |
刷新不会延长那 30 天。用户首次授权你的应用满 30 天后,整条 refresh 链过期, 必须重新走一遍授权流程。
不支持的能力
Nanako 借用了 OpenID Connect 的词汇 —— openid scope、sub claim、userinfo
端点 —— 但它不是一个 OIDC 提供方。
- 没有
id_token。 token 响应里只有 access token。 - 不支持
nonce。 你的库会发这个参数,服务端静默丢弃。 - 没有令牌自省(introspection)端点。 要检查令牌是否仍然有效,调用
/oauth/userinfo—— 任何未过期、未撤销的令牌至少会返回sub。 - 不支持 client credentials、implicit、device code 模式。
- 不支持动态客户端注册。 应用需要人工注册,见注册应用。