林中通行证 · OAuth 2.0 / OIDC 对接文档

林中通行证是林中科技的统一身份认证（SSO）与开放授权平台。第三方应用通过标准 OAuth 2.0 授权码模式 获取用户授权，通过 OIDC 获取签名的身份令牌（IdToken，RS256）。本文档按客户端类型分为两条对接路线，请先完成选型。

目录

① 客户端选型

创建应用时必须选择客户端类型，两类客户端的对接方式不同。核心判断：你的应用能否在服务端保管一个秘密。

② 接入准备（两种客户端通用）

1. 注册并创建应用

2. 回调地址（redirect_uri）规范

3. scope 说明

③ 机密客户端路线（有服务端）

适用于服务端渲染站点、后端 API 应用。完整流程：构造授权跳转 → 用户授权回调 → 服务端换令牌 → 调 userinfo。

A1 · 构造授权跳转（浏览器 302 跳转）

GET https://passport.lztech.top/oauth/authorize
    ?response_type=code
    &client_id=你的client_id
    &redirect_uri=https%3A%2F%2Fyour.app%2Fcallback
    &scope=openid%20profile%20email
    &state=随机不可预测字符串          ← 防 CSRF，回调时原样带回，必须校验
    &nonce=随机字符串                 ← 可选，会绑定进 IdToken
    &code_challenge=PKCE_S256摘要     ← 可选，建议启用
    &code_challenge_method=S256
    &prompt=select_account             ← 可选，强制弹出账号选择页

• 用户未登录时先进入统一登录页（邮箱验证码 / 密码），登录后自动回到授权确认页
• 首次授权展示中文授权确认页（逐项列出权限）；已授权过的用户直接静默发码，无感跳回
• prompt=select_account：跳过静默发码，先进入账号选择页让用户确认使用哪个账号（支持平台多账号）；选定后按该账号的授权状态走静默或确认页。适合「切换账号登录」类功能
• prompt=consent：跳过静默发码，强制展示授权确认页（用户每次手动确认）
• 用户点「拒绝」或参数非法，按错误码重定向回你的 callback（见 ⑥ 错误码）

A2 · 回调处理（服务端）

GET https://your.app/callback?code=授权码&state=原样返回的state

校验顺序：
1. state 与你发起时保存的完全一致（不一致立即中止，防 CSRF）
2. code 在 5 分钟内且未被使用过（一次性，重放会连带撤销已发令牌对）

A3 · code 换令牌（仅服务端调用）

# 方式一：HTTP Basic（推荐）
curl -X POST https://passport.lztech.top/oauth/token \
  -u "你的client_id:你的client_secret" \
  -d grant_type=authorization_code \
  -d code=收到的code \
  -d redirect_uri=https://your.app/callback

# 方式二：表单字段（client_secret_post）
#   追加 -d client_id=... -d client_secret=...

# 响应
{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 1800,
  "refresh_token": "…",
  "scope": "openid profile email",
  "id_token": "eyJhbGciOiJSUzI1NiIs…"
}

A4 · 刷新令牌（rotation 轮换）

curl -X POST https://passport.lztech.top/oauth/token \
  -u "你的client_id:你的client_secret" \
  -d grant_type=refresh_token \
  -d refresh_token=当前有效的refresh_token

# 响应为全新的一对 access_token + refresh_token；
# 旧 refresh_token 立即作废，请原子性地替换存储（先写新值再删旧值）。
# 使用已作废的旧 token 刷新 → invalid_grant，且该用户此应用全部令牌被撤销。

A5 · 撤销令牌

# 用户解绑 / 登出你的应用时调用；撤销该 token 所在令牌对（access + refresh 一起失效）
curl -X POST https://passport.lztech.top/oauth/revoke \
  -u "你的client_id:你的client_secret" \
  -d token=要撤销的token

# 响应恒为 200 {"ok":true}（RFC 7009，无需区分 token 是否存在）

A6 · 获取用户信息

curl https://passport.lztech.top/oauth/userinfo \
  -H "Authorization: Bearer {access_token}"

# scope=openid                  → { "sub": "lz-1" }
# scope=openid profile          → { "sub": "lz-1", "nickname": "张三" }
# scope=openid profile email    → { "sub": "lz-1", "nickname": "张三", "email": "z@example.com" }
# scope=openid profile avatar   → { "sub": "lz-1", "nickname": "张三", "picture": "https://img.lztech.top/api/img/…" }

A7 · 整户撤销（解绑场景）

# 用户在你的应用解绑账号时调用：撤销该用户在本应用的全部令牌，并删除授权关系
# （用户在通行证「授权管理」中该应用的记录同步消失，下次使用需重新走授权确认页）
curl -X POST https://passport.lztech.top/api/oauth/revoke-user \
  -u "你的client_id:你的client_secret" \
  -d sub=lz-123          ← 该用户的 sub（从 userinfo / IdToken 获取）

# 响应：{ "ok": true, "revoked": 3 }    revoked = 本次吊销的令牌数

# 错误：401 invalid_client（凭证错误）· 400 invalid_request（sub 缺失或格式错误）
#      404 not_found（用户不存在）· 429 rate_limited（30 次/分钟/IP，请退避重试）

④ 公开客户端路线（SPA / App / 小程序）

没有服务端秘密的应用。核心机制是 PKCE：用「验证器—挑战」替代 Secret，授权码即使被拦截也无法换出令牌。

B1 · 生成 PKCE 验证器（首次授权前，本地执行）

• code_verifier：43–128 位随机字符串（大小写字母、数字、-._~），必须用密码学安全随机源生成，不得复用
• code_challenge：BASE64URL(SHA256(code_verifier))，无填充

// 浏览器 / 小程序生成示例
const verifier = b64url(crypto.getRandomValues(new Uint8Array(32))); // 43 字符
const challenge = b64url(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier)));

function b64url(buf) {                     // Buffer → base64url（无 +/= 填充）
  return btoa(String.fromCharCode(...new Uint8Array(buf)))
    .replace(/\+/g,'-').replace(/\//g,'_').replace(/=+$/,'');
}
// ⚠️ verifier 必须保存在内存 / sessionStorage 中，token 交换时要提交原文

B2 · 构造授权跳转（强制 PKCE）

GET https://passport.lztech.top/oauth/authorize
    ?response_type=code
    &client_id=你的client_id
    &redirect_uri=https%3A%2F%2Fyour.app%2Fcallback
    &scope=openid%20profile%20email
    &state=随机不可预测字符串
    &nonce=随机字符串                ← 建议 OIDC 场景必带
    &code_challenge=上一步算出的challenge
    &code_challenge_method=S256      ← 缺失或非 S256 直接被拒绝

B3 · 回调处理（前端）

GET https://your.app/callback#或?code=授权码&state=原样返回的state

校验：state 与发起前保存在 sessionStorage 的值完全一致，不一致立即中止。

B4 · code 换令牌（前端直调，无 Secret）

curl -X POST https://passport.lztech.top/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=你的client_id \
  -d code=收到的code \
  -d redirect_uri=https://your.app/callback \
  -d code_verifier=本地保存的verifier原文

# 响应（注意：没有 refresh_token 字段）
{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 1800,
  "scope": "openid profile email",
  "id_token": "eyJhbGciOiJSUzI1NiIs…"
}

# 若提交 code_verifier 缺失或算出的 challenge 对不上 → invalid_grant (PKCE verification failed)
# 公开客户端提交 client_secret → invalid_client（公开客户端禁止持有 Secret）

B5 · access_token 到期后的续期

B6 · 撤销令牌（登出 / 解绑）

curl -X POST https://passport.lztech.top/oauth/revoke \
  -d client_id=你的client_id \
  -d token=要撤销的access_token

B7 · 获取用户信息与 IdToken 验签

与机密客户端完全一致：携带 Authorization: Bearer 调 userinfo；IdToken 请在前端用验签库（如 jose）配合 jwks.json 校验，见下一节。

⑤ IdToken（OIDC）验签方法

IdToken 是平台用 RS256 私钥签名的 JWT，请求 scope 含 openid 时随 token 响应一并返回。载荷（payload）示例：

{
  "iss": "https://passport.lztech.top",
  "sub": "lz-1",
  "aud": "你的client_id",
  "iat": 1726100000,
  "exp": 1726101800,
  "nonce": "发起授权时传入的nonce",
  "nickname": "张三",      ← scope 含 profile 时
  "email": "z@example.com" ← scope 含 email 时
  "picture": "https://…"   ← scope 含 avatar 且用户已设置头像时
}

⑥ 端点总览

authorize 阶段错误（重定向回 callback）

token / userinfo 阶段错误（HTTP JSON）

⑦ 安全要求（违反即下架）

⑧ 常见问题

Q1：用户第二次登录会再弹授权页吗？

不会。授权关系一旦建立（用户未撤销），后续授权请求直接静默发码；若用户已持有通行证登录态，整个跳转瞬时完成。用户可在「授权管理中心」随时撤销，撤销后恢复弹窗。

Q2：SPA 拿不到 refresh_token，30 分钟后岂不是要用户重新点登录？

不需要。access 到期后重新发起一次授权跳转即可：已授权用户静默发码，只要用户在通行证侧的登录态未过期（7 天），全程无感。这是公开客户端的标准安全模型——不在前端放长期凭据。

Q3：本地开发可以用 http 吗？

可以。回调地址登记为 http://localhost:端口/… 即可调试；平台强制 HTTPS 的规则对 localhost 回调不做要求，但生产环境回调必须 HTTPS。

Q4：code 换 token 报 invalid_grant 怎么排查？

按序检查：code 是否已使用过（一次性）→ 是否超过 5 分钟 → redirect_uri 是否与授权请求及登记完全一致 → 公开客户端 code_verifier 是否为发起时的原文（Challenge 计算方式是否 BASE64URL(SHA256) 无填充）。