Authentication Flows

Authentication Flows

标准 Logo 验证

主页登录、Management 二次验证和 OAuth 授权都使用同一个浏览器验证实现：

GET  /auth/passkey
POST /auth/passkey/options
POST /auth/passkey/verify

options 与 verify 只供标准验证页内部使用。页面加载时会获得一次性 flow token；直接从其他业务页面调用端点会被拒绝。

普通登录只允许回到本站相对路径，避免开放重定向。Management 的 reauth 模式绑定当前管理员，并强制 WebAuthn user verification。

OAuth Authorization Code

业务后端跳转：

GET /oauth/authorize
  ?response_type=code
  &client_id=your-client
  &redirect_uri=https://app.example/callback
  &state=random-state

验证完成后，业务 callback 收到 code 与原始 state。业务后端必须先校验 state，再使用 client secret 换 token：

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

grant_type=authorization_code&
code=...&
client_id=...&
client_secret=...&
redirect_uri=...

Authorization code 一次性使用，并绑定 client_id 与 redirect_uri。稳定用户标识使用响应中的 sub，不要用可修改的 username 作为业务主键。

Hyping 错误回跳

当 callback 路径是 /api/auth/callback 时，Passkey-Auth 会为 Hyping 提供同源 /api/auth/error。用户取消或 Logo 页验证失败后，错误和原 state 会回到 Hyping；Hyping 校验 state 后才在登录页展示错误。

其他 OAuth Client 不会被强制使用该专用错误接口。

Link Challenge

Link Challenge 适合你同时控制发起站点和 Auth 服务的场景：

原站创建 challenge
  -> /oauth/challenge/{id}
  -> Logo Passkey 验证
  -> 原站 callback?challenge_result=...

status=success 只用于展示。原站必须验证签名结果、state、challenge ID、client、用户绑定、过期时间和一次性消费状态。

Server Session Verify

内部后端可验证已有 Auth session：

POST /api/server/session/verify
Authorization: Bearer PASSKEY_SERVER_API_TOKEN
Content-Type: application/json

{"sessionCookie": "session=..."}

这是服务端读取现有登录态的接口，不会发起 Passkey，也不能绕过标准 Logo 验证页。

选择建议

• 独立网站：OAuth Authorization Code
• 同组织、轻量跳转：Link Challenge
• 已持有 Auth session cookie 的可信后端：Server Session Verify
• 不要让普通浏览器页面直接调用内部 WebAuthn endpoints