鉴权与登录笔记
原 旧稿(JWT 概念)+ 旧稿(OAuth2 + GitHub 第三方登录)的合并重写。 原笔记是概念罗列,本笔记在此基础上补全 4 种主流登录方式的完整流程、JWT 生产级实践(双 Token / 撤销 / 攻击防御)、扫码登录的时序设计。
权限模型(RBAC / ReBAC / Casbin)见
[[权限模型与Casbin实践笔记]]。 API 网关与鉴权中间件见[[API网关原理与选型笔记]]。
目录
- 登录方式全景对比
- 账号密码 + JWT(最常用)
- OAuth2 第三方登录(含 GitHub 完整流程)
- 扫码登录(PC + 移动 App)
- 手机号验证码登录
- Token 存储位置安全对比
- JWT 安全攻击与防御(RFC 8725)
- Token 撤销 / 黑名单
- JWT 完整代码示例 + 选型
1. 登录方式全景对比
| 方式 | 用户体验 | 安全性 | 适用场景 | 关键技术 |
|---|---|---|---|---|
| 账号密码 + JWT | 中(要注册) | 中(密码泄漏风险) | 通用 Web / App | bcrypt + JWT 双 Token |
| 手机号验证码 | 好(无需密码) | 中(短信劫持) | 国内移动端 | 短信网关 + 验证码缓存 |
| OAuth2 第三方登录 | 最好(点一下) | 高(委托给第三方) | 通用 Web / App | 授权码模式 |
| 扫码登录 | 好(无需输入) | 高(依赖 App 端鉴权) | PC 端 + 已装 App | 二维码 + 轮询 / WebSocket |
| SSO 单点登录 | 好(一次登录多处用) | 高(统一 IdP) | 企业内部 / 跨产品 | SAML / OIDC / CAS |
| 密钥 / Passkey | 最好(指纹 / 面部) | 最高 | 高安全场景 | WebAuthn / FIDO2 |
选型原则:
- 通用 Web → 账号密码 + JWT,第三方登录作为补充(降低注册门槛)
- 国内移动 App → 手机号验证码是主流
- PC + 移动 App 联动 → 扫码登录
- 企业内多产品 → SSO
- 高安全 / 支付 → Passkey 补充
2. 账号密码 + JWT(最常用)
2.1 完整流程时序图
用户 前端 网关 用户服务 Redis
│ 输入密码 │ │ │ │
│ ──────────────► │ │ │ │
│ │ POST /login │ │ │
│ │ ────────────────► │ 转发 │ │
│ │ │ ────────────────►│ │
│ │ │ │ 查 user + bcrypt │
│ │ │ │ 校验密码 │
│ │ │ │ 生成 access+refresh│
│ │ │ │ save refresh ───►│
│ │ │ ◄────────────────│ │
│ │ ◄────────────────│ 返回 tokens │ │
│ 存 token │ │ │ │
│ ──────────────► │ │ │ │
│ │ │ │ │
│ 访问受保护资源 │ │ │ │
│ ──────────────► │ GET /api/orders │ │ │
│ │ Authorization: │ │ │
│ │ Bearer eyJhbG... │ │ │
│ │ ────────────────► │ 校验 JWT 签名 │ │
│ │ │ 转发 + X-User-Id │ │
│ │ │ ────────────────►│ │
│ │ │ ◄────────────────│ │
│ │ ◄────────────────│ 返回数据 │ │
2.2 JWT 三段结构
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9. ← Header (Base64Url)
eyJzdWIiOiIxMjM0NSIsIm5hbWUiOiJBbGljZSIsImlhdCI6MTUxMjIzOTAyMn0. ← Payload
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c ← Signature
Header:
{ "alg": "HS256", "typ": "JWT" }
Payload(claims):
| claim | 含义 | 必填? |
|---|---|---|
sub | subject(用户 ID) | ✅ |
iat | issued at(签发时间) | 推荐 |
exp | expiration time(过期时间) | ✅ |
iss | issuer(签发方) | 推荐 |
aud | audience(接收方) | 推荐 |
jti | JWT ID(唯一标识,用于黑名单) | 推荐 |
nbf | not before(生效时间) | 可选 |
| 自定义 | user_id / roles / tenant_id | 视业务 |
⚠️ JWT payload 是明文 Base64Url 编码,不是加密!禁止放密码等敏感信息。需要加密用 JWE(RFC 7516)。
Signature:
HMACSHA256(
base64UrlEncode(header) + "." + base64UrlEncode(payload),
secret
)
服务端用相同算法 + secret 重算,对比签名 → 验签通过 = 数据未被篡改。
2.3 生产实践:双 Token 模式
单 Token 模式有死结:短过期 → 用户频繁登录;长过期 → token 泄露后无法撤销。
Access Token + Refresh Token 双 Token:
| Access Token | Refresh Token | |
|---|---|---|
| 过期时间 | 15 分钟 ~ 2 小时 | 7 ~ 30 天 |
| 用途 | 访问受保护 API | 换新的 Access Token |
| 存储 | 内存 / httpOnly cookie | httpOnly cookie / 加密存储 |
| 泄露后影响 | 时间窗有限(短过期) | 可撤销(jti 黑名单) |
Refresh Token 轮换(rotation):
客户端 → /token/refresh (refresh_token)
← { access_token: new1, refresh_token: new2 } ← 同时返回新的 refresh
← 旧 refresh_token 立即失效
每次刷新都换新的 refresh,旧 refresh 入黑名单 → 即使被窃也只能用一次。
2.4 密码安全
必须用 bcrypt / argon2 哈希,不能用 MD5/SHA1:
import bcrypt
# 注册
password_bytes = password.encode()
salt = bcrypt.gensalt(rounds=12) # cost factor 12~14
hashed = bcrypt.hashpw(password_bytes, salt)
db.save(user.password_hash=hashed)
# 登录
if bcrypt.checkpw(input_password.encode(), stored_hash):
# 正确
bcrypt 哈希里包含 salt,无需单独存。cost factor 12 大约 250ms,够慢且安全。
3. OAuth2 第三方登录
3.1 OAuth2 四种授权模式
| 模式 | 令牌存放位置 | 适用 | 推荐度 |
|---|---|---|---|
| 授权码 (authorization_code) | 后端 | 有后端的 Web 应用(首选) | ⭐⭐⭐⭐⭐ |
| 隐藏式 (implicit) | 前端 URL fragment | 纯前端 SPA(已不推荐,OAuth2.1 已废弃) | ⭐ |
| 密码式 (password) | — | 高度信任的自家应用(同公司产品) | ⭐⭐ |
| 客户端凭证 (client_credentials) | — | 服务对服务(无用户参与) | ⭐⭐⭐⭐ |
现代实践:Authorization Code + PKCE(防止拦截攻击,前端 SPA 也能用)。
3.2 GitHub OAuth 第三方登录完整流程(5 步)
基于由旧稿内容补全与校正。
前置:注册应用
到 GitHub → Settings → Developer settings → OAuth Apps → New OAuth App:
| 字段 | 填什么 |
|---|---|
| Homepage URL | https://yourapp.com |
| Authorization Callback URL | https://yourapp.com/oauth/callback |
提交后获得 client_id(公开)和 client_secret(必须保密,只放服务端)。
第 1 步:用户点击"GitHub 登录"
前端跳转:
https://github.com/login/oauth/authorize
?client_id=Iv1.abc123
&redirect_uri=https://yourapp.com/oauth/callback
&scope=read:user user:email
&state=random_csrf_token ← 防 CSRF,必带
第 2 步:用户在 GitHub 上同意授权
GitHub 显示应用名 + 申请的 scope,用户点 Authorize。
第 3 步:GitHub 回调到 redirect_uri
https://yourapp.com/oauth/callback
?code=859310e7cecc9196f4af ← 一次性授权码(10 分钟过期)
&state=random_csrf_token ← 必须校验等于第 1 步的 state
第 4 步:服务端用 code 换 token
POST https://github.com/login/oauth/access_token
Headers:
Accept: application/json
Body:
client_id=Iv1.abc123
&client_secret=<your_secret>
&code=859310e7cecc9196f4af
&redirect_uri=https://yourapp.com/oauth/callback
Response:
{
"access_token": "gho_xxxxxxxxxxxxxxxxxxxx",
"scope": "read:user,user:email",
"token_type": "bearer"
}
第 5 步:服务端用 access_token 拉用户信息
GET https://api.github.com/user
Headers:
Authorization: Bearer gho_xxxxxxxxxxxxxxxxxxxx
Response:
{ "id": 12345, "login": "alice", "name": "Alice", "email": "..." }
服务端据此自动注册 / 登录本地账户,签发自己的 access + refresh token 给前端。
3.3 OAuth2 关键安全点
| 风险 | 防御 |
|---|---|
client_secret 泄露 | 只在服务端用,前端绝不能出现 |
redirect_uri 被劫持 | 必须预注册且严格匹配(GitHub 不允许 query string 差异) |
| CSRF 攻击 | 用 state 参数(随机字符串,登录后校验一致) |
| 授权码被重用 | 授权码 10 分钟过期 + 一次性 |
| scope 越权 | 只申请必要的 scope(如 read:user 而非全部) |
3.4 OAuth2 / OIDC / JWT 关系
OAuth 2.0 = 授权框架("你能做什么") → RFC 6749
OIDC = OAuth 2.0 之上的身份层("你是谁") → OpenID Connect Core 1.0
JWT = Token 格式(OAuth2 不限定 Token 格式,OIDC 用 JWT 标准化 ID Token)
第三方登录走的是 OAuth2 流程;最终给用户签发的 token 通常是 JWT。
4. 扫码登录(PC + 移动 App)
4.1 核心思想
PC 端显示二维码 → 手机 App 扫码 → App 已登录态自动确认 → PC 端登录成功。
不需要 PC 端输入账号密码——App 已经登录,凭 App 端身份为 PC 授权。
4.2 5 步时序图
PC 浏览器 后端 手机 App Redis / DB
│ │ │ │
│ 1. 生成二维码 │ │ │
│ GET /qr/gen │ │ │
│ ────────────►│ │ │
│ │ 生成 qr_id │ │
│ │ 存 status=等待扫码 │
│ │ ────────────────────────────────► │
│ ◄────────────│ 返回 {qr_id, qr_token (含临时密钥)}│
│ 显示二维码 │ │ │
│ │ │ │
│ │ │ 扫码(解码出 URL │
│ │ │ + qr_token) │
│ │ │ │
│ │ 2. App 上确认登录 │ │
│ │ POST /qr/scan │ │
│ │ + qr_token │ │
│ │ + App 用户身份 │ │
│ │ ◄────────────────│ │
│ │ 校验 qr_token │ │
│ │ 存 status=已确认 │
│ │ + 临时 login_code │
│ │ ────────────────────────────────► │
│ │ │ │
│ 3. PC 轮询状态 │ │ │
│ GET /qr/status/{qr_id} │ │
│ ────────────►│ │ │
│ │ ◄────查 status ──┼──────────────────│
│ ◄────────────│ {status:已确认, │ │
│ │ login_code} │ │
│ 4. 用 login_code 换 token │ │
│ POST /qr/login {login_code} │ │
│ ────────────►│ │ │
│ │ 校验 login_code │ │
│ │ 返回 access+refresh │
│ ◄────────────│ │ │
│ │ │ │
4.3 关键设计点
| 步骤 | 关键点 |
|---|---|
| 生成二维码 | qr_id 唯一 + qr_token 含临时密钥(HMAC 签名,防伪造) |
| 二维码内容 | 通常是 URL:https://yourapp.com/qr/scan?qr_id=xxx&sig=xxx |
| PC 轮询 vs 长连接 | 简单场景用 2s 轮询;体验好场景用 WebSocket 推送(见 [[websocket笔记]]) |
| 扫码过期 | 二维码 60~120 秒过期,防恶意截屏 |
| login_code | 一次性,使用后立即失效 |
| 已扫码未确认 vs 已确认 | 两个状态,前端 UI 要区分("已扫码,请在手机上确认") |
4.4 防伪关键
qr_token 必须服务端签发 + App 端校验签名:
qr_token = jwt.encode(
{"qr_id": qr_id, "exp": now + 90},
SECRET,
algorithm="HS256",
)
App 端不信任二维码内容(因为可以伪造截图),但信任服务端签名。
5. 手机号验证码登录
5.1 流程
前端 后端 短信网关 Redis
│ POST /sms/send │ │ │
│ {phone: 138...} │ │ │
│ ────────────────►│ │ │
│ │ 检查 60s 间隔 │ │
│ │ 检查单日上限 │ │
│ │ 生成 6 位验证码 │ │
│ │ 存 redis ────────┼─────────────────►│
│ │ 调用短信网关 │ │
│ │ ────────────────►│ │
│ │ │ 发短信 │
│ ◄────────────────│ 返回 ok │ │
│ │ │ │
│ POST /login │ │ │
│ {phone, code} │ │ │
│ ────────────────►│ │ │
│ │ 查 redis 验证码 │ │
│ │ 校验 + 删除 │ │
│ │ 自动注册/登录 │ │
│ ◄────────────────│ 返回 tokens │ │
5.2 防刷要点
- 图形验证码:调
/sms/send前必须通过滑块 / 点选验证 - 60 秒间隔:同一手机号 60 秒内只能发一次
- 单日上限:同一手机号每天最多 5~10 条
- IP 限流:同一 IP 每小时最多 20 条
- 验证码 5 分钟过期,且只能用一次
- 错误次数限制:连续 3 次错误验证码 → 该手机号当日锁定
6. Token 存储位置安全对比
| 位置 | XSS 风险 | CSRF 风险 | 适用 | 推荐度 |
|---|---|---|---|---|
| localStorage | ❌ 高(JS 可读) | ✅ 低 | — | ❌ 不推荐 |
| sessionStorage | ❌ 高(JS 可读) | ✅ 低 | 短期敏感操作 | ⚠️ 一般 |
| httpOnly Cookie | ✅ 低(JS 读不到) | ❌ 高(自动携带) | Web 主流方案 | ⭐⭐⭐⭐ |
| 内存(React state) | ✅ 低 | ✅ 低 | 高安全 SPA | ⭐⭐⭐⭐ |
推荐方案:httpOnly + Secure + SameSite=Lax Cookie 存 Refresh Token,Access Token 存内存。
# 后端 Set-Cookie
response.set_cookie(
key="refresh_token",
value=refresh_token,
httponly=True,
secure=True, # 仅 HTTPS
samesite="lax",
max_age=7 * 24 * 3600,
)
Access Token 放内存(React state / Pinia):刷新页面就丢,重新用 refresh 换。XSS 拿不到,安全性高。
7. JWT 安全攻击与防御(RFC 8725)
| 攻击 | 原理 | 防御 |
|---|---|---|
alg=none 绕过 | 攻击者改 header alg: none,服务器若没校验就直接放过 | 强制算法白名单 algorithms=["HS256"] |
| RS256 → HS256 密钥混淆 | 服务端用公钥验签,攻击者把 alg 改成 HS256、用公钥作 HMAC secret | 强制密钥与算法绑定(pyjwt 自动) |
| 弱对称密钥 | 短 secret 被暴力破解 | enforce_minimum_key_length=True(HS256 ≥ 256 bit) |
| 嵌套 JWT 漏验 | 内层 JWT 没递归验签 | 库实现需逐层验签 |
kid 注入 | kid 字段指向攻击者控制的路径 / SQL | kid 白名单 / 不解析为路径 |
jku / x5u SSRF | 指向恶意 JWKS endpoint | 不支持这些 header / 严格白名单 |
| 跨 JWT 替代 | 同一 secret 签发不同用途 JWT 互相替代 | 用不同 aud / typ / iss 隔离 |
pyjwt 防御示例:
jwt.decode(
token,
SECRET,
algorithms=["HS256"], # 强制白名单(关键!)
audience="myapp",
issuer="my-auth-server",
options={"require": ["exp", "sub"]},
)
8. Token 撤销 / 黑名单
JWT 本身无状态,签发后无法主动失效。生产必须做撤销机制。
8.1 撤销策略(按效果递减)
| 策略 | 实现 | 适用 |
|---|---|---|
| 短 Access + Refresh 轮换 | access 15min,refresh 每次换新 | 所有生产 |
| jti 黑名单(Redis) | 登出时 SET jwt:blacklist:{jti} 1 EX <剩余exp> | 主动登出 / 改密 |
| Refresh Token 撤销表 | DB 存有效 refresh,校验时查 | 高安全场景 |
| 全局密钥轮换 | 紧急事件立刻换 secret(所有 token 失效) | 极端情况 |
8.2 实现:jti 黑名单
import jwt
import redis
import uuid
r = redis.Redis()
def issue_access(sub: str) -> str:
return jwt.encode({
"sub": sub,
"jti": str(uuid.uuid4()),
"exp": datetime.now(tz=timezone.utc) + timedelta(minutes=15),
"type": "access",
}, SECRET, algorithm="HS256")
def issue_refresh(sub: str) -> str:
jti = str(uuid.uuid4())
r.setex(f"jwt:active:{jti}", 7 * 24 * 3600, sub) # 存 7 天
return jwt.encode({
"sub": sub, "jti": jti,
"exp": datetime.now(tz=timezone.utc) + timedelta(days=7),
"type": "refresh",
}, SECRET, algorithm="HS256")
def revoke(jti: str):
r.delete(f"jwt:active:{jti}")
def verify_with_blacklist(token: str) -> dict:
payload = jwt.decode(token, SECRET, algorithms=["HS256"])
jti = payload.get("jti")
if jti and not r.exists(f"jwt:active:{jti}"):
raise jwt.InvalidTokenError("revoked")
return payload
9. JWT 完整代码示例 + 选型
9.1 算法选型
| 算法 | 类型 | 密钥 | 适用 |
|---|---|---|---|
| HS256 | HMAC 对称 | 单一密钥 | 单服务 / 内部系统 |
| RS256 | RSA 非对称 | 私钥签 / 公钥验 | 多服务 / 对外提供 SSO |
| ES256 | ECDSA | 更短 | 移动端 / 高性能 |
| EdDSA | Ed25519 | 现代高性能 | 新系统 |
原则:单服务用 HS256,多服务 / 对外交互用 RS256(公钥可对外发布验签)。
9.2 pyjwt 双 Token 完整示例
import jwt
import uuid
import redis
from datetime import datetime, timezone, timedelta
SECRET = "your-256-bit-secret-from-env" # ≥ 32 字节
ALG = "HS256"
ACCESS_TTL = timedelta(minutes=15)
REFRESH_TTL = timedelta(days=7)
r = redis.Redis()
def _now() -> datetime:
return datetime.now(tz=timezone.utc)
def issue_tokens(sub: str, extra: dict | None = None) -> dict:
"""签发 access + refresh 双 token。"""
base = {"sub": sub, "iat": _now()}
if extra:
base.update(extra)
access_jti = str(uuid.uuid4())
access = jwt.encode(
{**base, "jti": access_jti,
"exp": _now() + ACCESS_TTL, "type": "access"},
SECRET, algorithm=ALG,
)
refresh_jti = str(uuid.uuid4())
refresh = jwt.encode(
{**base, "jti": refresh_jti,
"exp": _now() + REFRESH_TTL, "type": "refresh"},
SECRET, algorithm=ALG,
)
r.setex(f"jwt:active:{refresh_jti}", int(REFRESH_TTL.total_seconds()), sub)
return {"access_token": access, "refresh_token": refresh, "token_type": "bearer"}
def refresh(refresh_token: str) -> dict:
"""用 refresh 换新的双 token(旧 refresh 立即失效)。"""
payload = jwt.decode(refresh_token, SECRET, algorithms=[ALG])
if payload.get("type") != "refresh":
raise jwt.InvalidTokenError("not a refresh token")
jti = payload["jti"]
if not r.exists(f"jwt:active:{jti}"):
raise jwt.InvalidTokenError("refresh token revoked or expired")
# 撤销旧 refresh + 颁发新双 token
r.delete(f"jwt:active:{jti}")
return issue_tokens(payload["sub"], {k: v for k, v in payload.items()
if k not in ("exp", "iat", "jti", "type")})
def verify_access(token: str) -> dict:
"""校验 access token(不做黑名单校验,因为 access TTL 短)。"""
return jwt.decode(
token, SECRET, algorithms=[ALG],
options={"require": ["exp", "sub"]},
)
9.3 与 OAuth2 / OIDC 的边界
- 自己的账号系统(账号密码 / 手机号 / 扫码登录)→ 直接发 JWT
- 第三方登录 → 走 OAuth2 流程(让用户授权),最终仍发自己的 JWT
- 对外提供登录能力(SSO) → 自己是 OAuth2 Server + OIDC(返回标准 ID Token / UserInfo)
关联笔记
- 权限模型(拿到 token 后能做什么):
[[权限模型与Casbin实践笔记]] - API 网关(鉴权中间件放在哪):
[[API网关原理与选型笔记]] - WebSocket 扫码登录长连接:
[[websocket笔记]] - 网络安全(TLS / HTTPS):
[[TCP_IP四层网络模型笔记]]
Demo
完整代码(JWT + 扫码登录 + Casbin 鉴权):
标签:#fastapi #redis