令牌管理

访问令牌用于访问受保护资源，刷新令牌用于在访问令牌过期后获取新的访问令牌。通过探查与吊销端点可以管理令牌生命周期。

访问令牌

访问令牌为 Bearer 类型，在请求头中携带：

GET /api/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

过期时间由 expires_in 字段给出（单位秒，默认 3600，即 1 小时）。这是访问凭证的寿命，不是第三方网站自己的登录会话时长。客户端应当在过期前使用刷新令牌续期，而不是等待过期报错，也不要把 expires_in 或 ID Token 的 exp 直接当成网站登录过期时间。

刷新令牌

授权码换票与刷新令牌换票始终返回 refresh_token，不依赖是否请求 offline_access。offline_access 仍可作为显式范围出现在授权请求中，但不再决定是否签发刷新令牌。

用刷新令牌换发新的访问令牌：

POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=CLIENT_ID

机密客户端需同时提供 client_secret。响应结构与授权码流程一致，并包含新的 refresh_token（轮换）。每次刷新后旧刷新令牌失效；请保存响应中的新值。

刷新令牌默认 30 天有效，每次成功刷新会重新计算过期时间。访问令牌过期后，只要刷新令牌仍有效，即可继续换发。

轮换与宽限

刷新令牌轮换：每次刷新返回新刷新令牌。为避免网络超时重试把整条令牌链吊销，旧令牌在短时间宽限（默认 60 秒）内再次使用，会返回同一组新令牌。宽限结束后再使用旧令牌，将视为重用并吊销该令牌家族。

探查令牌

令牌探查（introspection）用于资源服务器验证访问令牌是否仍然有效：

POST /api/oauth/introspect
Content-Type: application/x-www-form-urlencoded

token=ACCESS_TOKEN
&token_type_hint=access_token
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET

仅机密客户端（持有 client_secret）可调用探查端点。

响应：

{
  "active": true,
  "scope": "openid profile email",
  "client_id": "CLIENT_ID",
  "token_type": "Bearer",
  "sub": "user-123",
  "iss": "https://auth.example.com",
  "exp": 1750000000,
  "iat": 1749996400
}

令牌无效或已过期时 active 为 false。刷新令牌在轮换宽限内仍可能 active 为 true。

吊销令牌

主动使令牌失效（用户登出、账号被移除等场景）：

POST /api/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=TOKEN
&token_type_hint=refresh_token
&client_id=CLIENT_ID

无论令牌是否存在，均返回成功（HTTP 200），避免攻击者借此枚举有效令牌。建议先吊销刷新令牌，再吊销其派生的访问令牌。

最佳实践

• 访问令牌短期有效（默认 1 小时）；使用刷新令牌持续换发，降低泄漏窗口。
• 第三方应用应维护自己的登录会话，并用刷新令牌在服务端续期；不要把访问令牌寿命当成网站登录寿命。
• 刷新令牌轮换：每次刷新返回新刷新令牌；宽限期内的重复请求是安全的，请始终保存最新的 refresh_token。
• 访问令牌仅存在于后端，不要暴露给浏览器或移动端存储。
• 检测到异常时通过吊销端点使令牌立即失效。
• 用户注销、管理员删除用户、合并账号或设置临时密码后，该用户全部访问/刷新令牌立即失效。
• 禁用或删除应用后，该应用全部令牌立即失效；探查将返回 active: false。
• 账号被封禁或删除后，既有访问令牌在探查与 UserInfo 中视为无效。