mirror of
https://github.com/RaisFast/raisfast.git
synced 2026-09-23 16:02:25 +00:00
38 KiB
38 KiB
OAuth2 用户注册/登录流程图
整体时序图
┌────────┐ ┌────────────┐ ┌──────────────┐ ┌──────────────────┐
│ 前端 │ │ raisfast │ │ GitHub OAuth │ │ SQLite DB │
│ 浏览器 │ │ 后端 API │ │ Provider │ │ │
└───┬────┘ └─────┬──────┘ └──────┬───────┘ └────────┬─────────┘
│ │ │ │
│ 1. GET /api/v1/auth/oauth/github │ │
│───────────────>│ │ │
│ │ │ │
│ │ 2. 检查 OAuth 是否启用 │
│ │ 3. 检查 GitHub Provider 是否已配置 │
│ │ │ │
│ │ 4. 生成 state (32字节随机hex) │
│ │ 5. 生成 code_verifier (43字符随机串) │
│ │ 6. 计算 code_challenge = BASE64URL(SHA256(code_verifier))
│ │ │ │
│ │ 7. INSERT INTO oauth_states │
│ │ (state, provider, code_verifier, │
│ │ expires_at = now + 10min) │
│ │───────────────────────────────────────────>│
│ │ │ │
│ │ 8. 构建 GitHub 授权 URL │
│ │ https://github.com/login/oauth/authorize
│ │ ?client_id=xxx │
│ │ &state=xxx │
│ │ &code_challenge=xxx │
│ │ &code_challenge_method=S256 │
│ │ &scope=user:email │
│ │ │ │
│ 9. 302 重定向到 GitHub 授权页 │ │
│<───────────────│ │ │
│ │ │ │
│ 10. 用户在 GitHub 页面登录并授权 │ │
│────────────────────────────────────>│ │
│ │ │ │
│ 11. GitHub 回调带 code + state │ │
│<────────────────────────────────────│ │
│ │ │ │
│ 12. GET /api/v1/auth/oauth/github/callback?code=xxx&state=xxx
│───────────────>│ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────┐ │
│ │ │ 回调处理核心流程 │ │
│ │ │ (见下方详细流程图) │ │
│ │ └─────────────────────────────────────┘ │
│ │ │ │
│ 13. 302 重定向到前端回调页 │ │
│ ?access_token=xxx │ │
│ &refresh_token=xxx │ │
│ &expires_in=900 │ │
│<───────────────│ │ │
│ │ │ │
│ 14. 前端提取 URL 参数，存入 localStorage，跳转首页 │
│ │ │ │
回调处理核心流程
┌─────────────────────┐
│ 收到 callback 请求 │
│ provider + code │
│ + state │
└──────────┬──────────┘
│
▼
┌─────────────────────────────────┐
│ 1. 检查 OAuth 是否启用 │
│ config.oauth.enabled == true │
└──────────────┬──────────────────┘
│
No ───┴─── Yes
│ │
▼ ▼
┌──────────┐ ┌──────────────────────────┐
│ 返回 400 │ │ 2. 从 DB 查找并消费 state │
│ OAuth │ │ SELECT * FROM │
│ 未启用 │ │ oauth_states │
└──────────┘ │ WHERE id = ? │
│ AND expires_at > now() │
│ 然后 DELETE (一次性使用) │
└────────────┬───────────────┘
│
┌─────────┴─────────┐
│ │
未找到/已过期 找到 state
│ │
▼ ▼
┌──────────┐ ┌──────────────────────┐
│ 返回 400 │ │ 3. 校验 provider 匹配 │
│ 无效或 │ │ state.provider == │
│ 过期的 │ │ 请求的 provider │
│ state │ └──────────┬───────────┘
└──────────┘ │
不匹配 │ 匹配
│ │
▼ ▼
┌────────┐ ┌──────────────────────────┐
│ 400 │ │ 4. 用 code 换 access_token │
│ │ │ POST github.com/ │
└────────┘ │ login/oauth/ │
│ access_token │
│ ┌──────────────────┐ │
│ │ client_id │ │
│ │ client_secret │ │
│ │ code │ │
│ │ code_verifier │ │
│ └──────────────────┘ │
└──────────┬───────────────┘
│
▼
┌──────────────────────┐
│ 5. 获取 GitHub 用户信息│
│ GET api.github.com/ │
│ user │
│ Header: Bearer token│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 6. 检查邮箱是否返回 │
│ profile.email ? │
└──────────┬───────────┘
│
有邮箱 │ 无邮箱
直接用 │ 或为空
│ │ │
│ │ ▼
│ │ ┌─────────────────────┐
│ │ │ 额外调用 │
│ │ │ GET /user/emails │
│ │ │ 找 primary+verified │
│ │ │ 的邮箱 │
│ │ └──────────┬──────────┘
│ │ │
▼ ▼ ▼
┌──────────────────────────────┐
│ 得到 OAuthUserInfo: │
│ - provider_user_id (GitHub ID)│
│ - email │
│ - display_name (login) │
│ - avatar_url │
│ - raw_profile (完整 JSON) │
└──────────────┬───────────────┘
│
▼
用户查找/创建决策树
┌──────────────────────────┐
│ 拿到 OAuthUserInfo │
│ (provider + user_id + │
│ email + name + avatar) │
└────────────┬─────────────┘
│
▼
┌────────────────────────────────────┐
│ A. 查找已有 OAuth 绑定 │
│ SELECT * FROM oauth_accounts │
│ WHERE provider = ? │
│ AND provider_user_id = ? │
└──────────────┬─────────────────────┘
│
┌───────┴───────┐
│ │
找到绑定 未找到绑定
│ │
▼ ▼
┌─────────────────┐ ┌──────────────────────────────┐
│ 已绑定用户！ │ │ B. 检查 state.user_id │
│ │ │ (发起时已登录用户传入) │
│ 1. 查找本地用户 │ │ → 表示"绑定"操作 │
│ 2. 更新 OAuth │ └──────────────┬───────────────┘
│ 绑定信息 │ │
│ (token/profile│ ┌──────┴──────┐
│ 等刷新) │ │ │
│ 3. 签发 JWT + │ 有 user_id 无 user_id
│ refresh_token│ │ │
│ 4. 302 重定向 │ ▼ ▼
│ 到前端 │ ┌─────────────┐ ┌──────────────────┐
└─────────────────┘ │ C. 绑定模式 │ │ D. 检查邮箱匹配 │
│ │ │ │
│ 1. 绑定到 │ │ 有 email 且 │
│ 当前用户 │ │ 能在 users 表 │
│ 2. 签发 JWT │ │ 找到匹配邮箱？ │
│ 3. 重定向 │ └────────┬─────────┘
└──────┬──────┘ │
│ ┌──────┴──────┐
│ │ │
│ 找到匹配用户 无匹配用户
│ │ │
│ ▼ ▼
│ ┌──────────────┐ ┌──────────────────────┐
│ │ E. 自动绑定 │ │ F. 自动注册新用户 │
│ │ │ │ │
│ │ 1. 将 OAuth │ │ 1. 生成唯一 username │
│ │ 绑定到 │ │ base = login 名 │
│ │ 匹配用户 │ │ sanitize 清理 │
│ │ 2. 签发 JWT │ │ 冲突→加前缀/后缀 │
│ │ 3. 重定向 │ │ │
│ └──────┬───────┘ │ 2. 生成占位密码 │
│ │ │ "!oauth:github:xxx"│
│ │ │ │
│ │ │ 3. INSERT INTO users │
│ │ │ role = 'reader' │
│ │ │ │
│ │ │ 4. UPDATE users SET │
│ │ │ avatar = 头像URL │
│ │ │ email_verified = 1 │
│ │ │ │
│ │ │ 5. 发射 UserRegistered│
│ │ │ 事件 │
│ │ │ │
│ │ │ 6. 创建 OAuth 绑定 │
│ │ └──────────┬───────────┘
│ │ │
▼ ▼ ▼
┌──────────────────────────────────┐
│ 签发 JWT + refresh_token │
│ │
│ 1. generate_access_token_internal│
│ (user_id, role, tenant_id, │
│ jwt_secret, expires_in) │
│ │
│ 2. generate_refresh_token_string │
│ (32字节随机 hex) │
│ │
│ 3. INSERT INTO refresh_tokens │
│ │
│ 4. 302 重定向到前端: │
│ {redirect_url} │
│ ?access_token=xxx │
│ &refresh_token=xxx │
│ &expires_in=900 │
└──────────────────────────────────┘
用户名自动生成策略
输入: display_name = "octocat"
│
▼
┌─────────────────────┐
│ sanitize_username() │
│ 只保留 a-z A-Z 0-9 _ │
│ 去除首尾下划线 │
└──────────┬──────────┘
│
▼
username = "octocat"
│
▼
┌─────────────────────────────┐
│ SELECT * FROM users │
│ WHERE username = 'octocat' │
└──────────────┬──────────────┘
│
┌──────┴──────┐
│ │
不存在(OK) 已存在
│ │
▼ ▼
返回 "octocat" ┌────────────────────────────────┐
│ 尝试加 GitHub 前缀 │
│ username = "github_octocat" │
│ SELECT ... WHERE username = ? │
└──────────────┬─────────────────┘
│
┌──────┴──────┐
│ │
不存在(OK) 已存在
│ │
▼ ▼
返回 ┌──────────────────────────┐
"github_octocat" │ 追加 4 位随机 hex 后缀 │
│ suffix = random_hex(2) │
│ "github_octocat_a3f8" │
└──────────────────────────┘
安全机制
┌──────────────────────────────────────────────────────────────────┐
│ 安全防护层 │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────── PKCE (Proof Key for Code Exchange) ────────────┐ │
│ │ │ │
│ │ 客户端(后端) GitHub │ │
│ │ ┌─────────────┐ ┌──────────┐ │ │
│ │ │ 生成随机 │ │ │ │ │
│ │ │ code_verifier│────────>│ 存储 │ │ │
│ │ │ (43 字符) │ │ code_ │ │ │
│ │ └──────┬──────┘ │ challenge│ │ │
│ │ │ │ │ │ │
│ │ ▼ │ │ │ │
│ │ SHA256(code_verifier) │ │ │ │
│ │ │ │ │ │ │
│ │ ▼ │ │ │ │
│ │ BASE64URL(hash) │ │ │ │
│ │ = code_challenge │ │ │ │
│ │ │ │ │ │
│ │ 授权请求 ───────────────>│ 校验 │ │ │
│ │ 带 code_challenge │ challenge│ │ │
│ │ │ │ │ │
│ │ 回调时 ─────────────────>│ 用 │ │ │
│ │ 带 code_verifier │ verifier │ │ │
│ │ │ 重新计算 │ │ │
│ │ │ 验证匹配 │ │ │
│ │ └──────────┘ │ │
│ │ │ │
│ │ 防止：authorization code 被截获后无法使用 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────── State 参数 (CSRF 防护) ────────────────────────┐ │
│ │ │ │
│ │ 发起时: │ │
│ │ state = random_hex(32) → 64 字符随机串 │ │
│ │ INSERT INTO oauth_states (id=state, ..., expires_at) │ │
│ │ │ │
│ │ 回调时: │ │
│ │ SELECT * FROM oauth_states WHERE id = ? │ │
│ │ AND expires_at > datetime('now') │ │
│ │ DELETE FROM oauth_states WHERE id = ? ← 一次性使用 │ │
│ │ │ │
│ │ 防止：CSRF 攻击（伪造回调请求） │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────── Rate Limiting ─────────────────────────────────┐ │
│ │ │ │
│ │ OAuth 端点受全局 rate_limit 保护 │ │
│ │ 默认 60 次/分钟/IP │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────── 解绑安全 ──────────────────────────────────────┐ │
│ │ │ │
│ │ 解绑前检查: │ │
│ │ if user.password_hash 是占位值 (以 "!oauth:" 开头) │ │
│ │ AND oauth 绑定数量 <= 1 │ │
│ │ then 拒绝解绑 │ │
│ │ → 防止用户无法登录 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
数据库表关系
┌──────────────────────┐ ┌──────────────────────────┐
│ users │ │ oauth_accounts │
├──────────────────────┤ ├──────────────────────────┤
│ id TEXT PK │◄──┐ │ id TEXT PK │
│ tenant_id TEXT │ │ │ user_id TEXT FK ─────────┤──┘
│ email TEXT UNIQUE │ │ │ provider TEXT │ 一个用户可绑定
│ username TEXT UNIQUE │ │ │ provider_user_id TEXT │ 多个 Provider
│ password_hash TEXT │ │ │ email TEXT │
│ role TEXT │ │ │ display_name TEXT │
│ avatar TEXT │ │ │ avatar_url TEXT │
│ bio TEXT │ │ │ access_token TEXT │
│ website TEXT │ │ │ refresh_token TEXT │
│ email_verified INT │ │ │ token_expires_at TEXT │
│ created_at TEXT │ │ │ profile TEXT (JSON) │
│ updated_at TEXT │ │ │ created_at TEXT │
└──────────────────────┘ │ │ updated_at TEXT │
│ └──────────────────────────┘
│
│ UNIQUE(provider, provider_user_id)
│
│ ┌──────────────────────────┐
│ │ oauth_states │
│ ├──────────────────────────┤
│ │ id TEXT PK (= state 值) │
│ │ provider TEXT │
└───│ user_id TEXT FK (可空) │ ← 绑定模式传入
│ code_verifier TEXT │
│ created_at TEXT │
│ expires_at TEXT │
│ │
│ 10 分钟后过期 │
│ Worker cron 定期清理 │
└──────────────────────────┘
前端对接示例
┌────────────────────────────────────────────────────────────────┐
│ 登录页 (/login) │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 邮箱: [________________] │ │
│ │ 密码: [________________] │ │
│ │ [ 登 录 ] │ │
│ │ │ │
│ │ ────── 或 ────── │ │
│ │ │ │
│ │ [GitHub 登录] [Google 登录] │ ← 调用 GET /api/v1/ │
│ │ │ auth/oauth/github │
│ └─────────────────────────────────┘ (浏览器直接跳转) │
│ │
├────────────────────────────────────────────────────────────────┤
│ 回调页 (/auth/callback) │
│ │
│ useEffect(() => { │
│ const params = new URLSearchParams(location.search); │
│ const accessToken = params.get('access_token'); │
│ const refreshToken = params.get('refresh_token'); │
│ const expiresIn = params.get('expires_in'); │
│ │
│ if (accessToken) { │
│ localStorage.setItem('access_token', accessToken); │
│ localStorage.setItem('refresh_token', refreshToken); │
│ navigate('/'); │
│ } else { │
│ // 显示错误 │
│ const error = params.get('error'); │
│ showToast(error || 'OAuth login failed'); │
│ navigate('/login'); │
│ } │
│ }, []); │
│ │
├────────────────────────────────────────────────────────────────┤
│ 账号设置页 (/settings/account) │
│ │
│ 已绑定的社交账号: │
│ ┌──────────────────────────────────────┐ │
│ │ 🐙 GitHub octocat [解绑] │ ← DELETE /api/v1/ │
│ │ 🔵 Google (未绑定) [绑定] │ auth/oauth/ │
│ │ 💬 微信 (未绑定) [绑定] │ github/unbind │
│ └──────────────────────────────────────┘ │
│ │
│ [设置密码] ← OAuth 用户首次设置密码后成为"混合登录"用户 │
│ │
└────────────────────────────────────────────────────────────────┘
JWT Token 签发流程（OAuth 和普通登录共用）
┌─────────────────────┐
│ 确认用户身份 │
│ user_id + role │
│ + tenant_id │
└──────────┬──────────┘
│
▼
┌──────────────────────────────────────┐
│ 生成 Access Token (JWT HS256) │
│ │
│ Claims: │
│ { │
│ "sub": "0192a3b4-user-id", │
│ "role": "reader", │
│ "tenant_id": "default", │
│ "exp": 1713980000, │
│ "iat": 1713979100 │
│ } │
│ │
│ 签名: HMAC-SHA256(jwt_secret) │
│ 有效期: 15 分钟 (可配置) │
└──────────────┬───────────────────────┘
│
▼
┌──────────────────────────────────────┐
│ 生成 Refresh Token │
│ │
│ 32 字节随机 → 64 字符 hex 字符串 │
│ "a3f8b2c1d4e5f6...64chars" │
│ │
│ INSERT INTO refresh_tokens │
│ 有效期: 7 天 (可配置) │
└──────────────┬───────────────────────┘
│
▼
┌──────────────────────────────────────┐
│ 返回给前端 (通过 URL 参数) │
│ │
│ {redirect_url} │
│ ?access_token=eyJhbG... │
│ &refresh_token=a3f8b2c1... │
│ &expires_in=900 │
└──────────────────────────────────────┘