跳到主要内容

4 篇博文 含有标签「FastAPI」

查看所有标签

API 网关笔记

· 阅读需 10 分钟

由旧稿重写。原笔记仅有 2 个外部链接,本笔记系统介绍网关的定位、能力、与反向代理的区别,并给出一个可运行的 FastAPI 网关 Demo(4 个中间件 + 路由转发 + 完整流程图)。

鉴权与登录见 [[鉴权与登录笔记]];权限模型(Casbin / RBAC / ReBAC)见 [[权限模型与Casbin实践笔记]]。

目录​

  1. 什么是网关 + 为什么需要
  2. 网关核心能力清单
  3. 网关 vs 反向代理 vs Ingress vs Sidecar
  4. 网关选型(Kong / APISIX / Spring Cloud Gateway / 自研)
  5. Python FastAPI 网关 Demo 流程图
  6. 关键中间件实现要点
  7. 生产部署清单
  8. 网关常见坑
  9. 关联笔记

1. 什么是网关 + 为什么需要​

API 网关(API Gateway) 是系统的唯一对外入口,所有外部流量先经过网关,再到内部的具体服务。

1.1 为什么需要网关​

没有网关时:

[客户端 A] ──┐
[客户端 B] ──┼──► [用户服务] 各自要处理:鉴权、限流、CORS、日志…
[客户端 C] ──┼──► [订单服务] 重复代码散落在每个服务
└──► [商品服务]

有网关后:

[所有客户端] ──► [网关] ──► [用户服务 / 订单服务 / 商品服务]
│
└─ 统一处理:鉴权 / 限流 / 路由 / 日志

核心价值:

  • 统一入口:客户端只需对接网关
  • 集中治理:鉴权、限流、日志、安全策略一处实现
  • 解耦:客户端不感知后端服务的拆分 / 合并 / 替换
  • 安全:隐藏内部服务拓扑、过滤恶意请求

1.2 网关的常见别名​

  • Edge Service(边缘服务)
  • BFF(Backend For Frontend,为特定前端定制的网关层)
  • API Gateway(最常见)
  • Ingress(K8s 术语)

2. 网关核心能力清单​

能力说明
路由按 path / host / header / query 把请求分发到不同下游
鉴权JWT 校验、OAuth2 introspection、API Key 校验
限流按 IP / 用户 / 路径 / 租户维度限流
熔断下游超时或 5xx 比例超阈值时快速失败,避免拖垮
缓存缓存 GET 响应(Redis / 内存)
日志结构化访问日志、请求 ID 链路追踪
监控QPS / 延迟 / 错误率指标暴露(Prometheus)
协议转换HTTP → gRPC / WebSocket / GraphQL
CORS跨域统一处理
请求改写path 重写、header 注入、请求/响应体转换
安全WAF、防 SQL 注入、防爬虫、黑白名单

3. 网关 vs 反向代理 vs Ingress vs Sidecar​

类型定位典型
反向代理转发请求 + 负载均衡,运维层nginx / HAProxy
API 网关反向代理 + 业务层能力(鉴权/限流/灰度)Kong / APISIX / Spring Cloud Gateway
IngressK8s 中的网关抽象(标准 + 多种实现)Ingress-NGINX / Traefik / Contour
服务网格 Sidecar每个服务实例旁的代理(东西向流量)Envoy + Istio / Linkerd

关系:

  • 反向代理 ⊂ API 网关(网关 = 反向代理 + 业务能力)
  • Ingress ⊂ API 网关(Ingress 是 K8s 生态的网关实现)
  • Sidecar ≠ 网关(一个管南北向出口,一个管东西向内部通信,但都用 Envoy)

架构位置:

客户端 ──► [反向代理/LB] ──► [API 网关] ──► [微服务 A, B, C]
│
└──► [鉴权/限流/路由]

网关通常不和反向代理合并(除非追求极致简单):nginx 终止 TLS + 网关做业务, 是生产标配。


4. 网关选型​

场景推荐说明
小团队 / 学习 / 内部工具FastAPI 自研(见本文 demo)灵活、贴合业务、Python 全栈
中大型 / 多语言后端APISIX / KongLua 插件丰富、高性能、社区活跃
Spring 体系Spring Cloud Gateway集成 Spring 全家桶
K8s 流量入口Ingress-NGINX / Traefik标准 Ingress
云原生全功能Envoy + Istio Gateway服务网格统一
ServerlessAWS API Gateway / 阿里云 API 网关托管、免运维

自研网关的边界:流量不大 + 业务简单 + Python 技术栈 → 自研够用。 流量大 + 多团队 + 复杂路由 → 上 APISIX。


5. Python FastAPI 网关 Demo 流程图​

5.1 整体架构​

┌────────────────────┐
│ Client │
└──────────┬─────────┘
│ HTTPS
┌──────────▼─────────┐
│ TLS Termination │ ← nginx / 云 LB
└──────────┬─────────┘
│ HTTP
┌──────────▼─────────────────────────┐
│ Gateway (FastAPI) │
│ │
│ [Middleware 链] │
│ ① TrustedHostMiddleware │ 防 Host 注入
│ ② RequestContextMiddleware │ 生成 X-Request-ID
│ ③ RateLimitMiddleware │ 滑动窗口限流
│ ④ AuthMiddleware │ JWT 校验
│ ⑤ ReverseProxyMiddleware │ 路由转发
│ │
└──────┬──────────┬──────────┬─────────┘
│ │ │
/api/users /api/orders /api/products
│ │ │
┌──────▼──┐ ┌────▼───┐ ┌────▼────┐
│ User │ │ Order │ │Product │
│ Service │ │Service │ │ Service │
│ :9001 │ │ :9002 │ │ :9003 │
└─────────┘ └────────┘ └─────────┘

5.2 中间件顺序为什么重要​

先 add_middleware 的在外层(请求从外到内经过,响应反过来):

请求流: Client → ①TrustedHost → ②RequestContext → ③RateLimit → ④Auth → ⑤ReverseProxy → Downstream
响应流: Downstream → ⑤ → ④ → ③ → ② → ① → Client

错误顺序示例:

  • ❌ Auth 在 RateLimit 内:未鉴权的请求也消耗限流名额
  • ❌ ReverseProxy 在 Auth 内:未鉴权就转发到下游,下游要重复鉴权
  • ✅ 正确:限流在最外(早期丢弃)、鉴权居中(带 user 上下文)、转发在最内

5.3 关键路径​

1. TrustedHostMiddleware
- 检查 Host 头,拒绝恶意构造(如 Host: evil.com)
- 防 Host Header 注入

2. RequestContextMiddleware
- 生成/透传 X-Request-ID(链路追踪)
- 记录访问日志(method, path, status, latency)
- 请求耗时埋点

3. RateLimitMiddleware
- 按 (client_ip, path_prefix) 做滑动窗口
- 超限返回 429 + Retry-After
- 防止恶意刷接口

4. AuthMiddleware
- 解析 Authorization: Bearer xxx
- 校验 JWT 签名 / 过期 / 黑名单
- 把 user 信息挂到 request.state.user

5. ReverseProxyMiddleware
- 根据 path 前缀匹配 ROUTES 表
- 用 httpx 转发到下游
- 透传 X-Request-ID / X-User-Id / X-Forwarded-For

6. 关键中间件实现要点​

完整代码见 example/gateway/gateway.py。

6.1 RequestContextMiddleware(请求上下文)​

class RequestContextMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request, call_next):
request_id = request.headers.get("X-Request-ID") or str(uuid.uuid4())
request.state.request_id = request_id
start = time.perf_counter()
response = await call_next(request)
elapsed_ms = (time.perf_counter() - start) * 1000
response.headers["X-Request-ID"] = request_id
logger.info("[%s] %s %s -> %s (%.1fms)",
request_id, request.method, request.url.path,
response.status_code, elapsed_ms)
return response

6.2 RateLimitMiddleware(滑动窗口限流)​

class RateLimitMiddleware(BaseHTTPMiddleware):
WINDOW_SEC = 60
MAX_REQS = 100
def __init__(self, app):
super().__init__(app)
self.buckets = defaultdict(deque)

async def dispatch(self, request, call_next):
key = (request.client.host, request.url.path.split("/")[1])
now = time.time()
bucket = self.buckets[key]
while bucket and bucket[0] < now - self.WINDOW_SEC:
bucket.popleft()
if len(bucket) >= self.MAX_REQS:
return JSONResponse({"detail": "Too Many Requests"},
status_code=429,
headers={"Retry-After": str(self.WINDOW_SEC)})
bucket.append(now)
return await call_next(request)

⚠️ 这是单进程内存版,多 worker / 多机要换 Redis(用 INCR + EXPIRE 实现)。

6.3 AuthMiddleware(JWT 校验)​

class AuthMiddleware(BaseHTTPMiddleware):
PUBLIC_PATHS = {"/health", "/", "/login"}

async def dispatch(self, request, call_next):
if request.url.path in self.PUBLIC_PATHS:
return await call_next(request)

auth = request.headers.get("Authorization", "")
if not auth.startswith("Bearer "):
return JSONResponse({"detail": "Missing bearer token"},
status_code=401)

try:
payload = jwt.decode(auth[7:], SECRET,
algorithms=["HS256"],
options={"require": ["exp", "sub"]})
request.state.user = payload
except jwt.InvalidTokenError as e:
return JSONResponse({"detail": f"Invalid token: {e}"},
status_code=401)
return await call_next(request)

6.4 ReverseProxyMiddleware(路由转发)​

class ReverseProxyMiddleware(BaseHTTPMiddleware):
def __init__(self, app, routes: dict[str, str]):
super().__init__(app)
self.routes = routes

async def dispatch(self, request, call_next):
upstream = self._match(request.url.path)
if not upstream:
return await call_next(request) # 网关自身路由

headers = dict(request.headers)
headers["X-Real-IP"] = request.client.host
headers["X-Request-ID"] = request.state.request_id
if hasattr(request.state, "user"):
headers["X-User-Id"] = str(request.state.user.get("sub"))

body = await request.body() # body 只能读一次

async with httpx.AsyncClient(timeout=30.0) as client:
try:
upstream_resp = await client.request(
method=request.method,
url=f"{upstream}{request.url.path}",
params=request.query_params,
headers=headers, content=body,
)
except httpx.RequestError as e:
return JSONResponse({"detail": f"Upstream error: {e}"},
status_code=502)

# 过滤 hop-by-hop headers(防双重压缩)
excluded = {"content-encoding", "content-length",
"transfer-encoding", "connection"}
resp_headers = {k: v for k, v in upstream_resp.headers.items()
if k.lower() not in excluded}
return Response(content=upstream_resp.content,
status_code=upstream_resp.status_code,
headers=resp_headers,
media_type=upstream_resp.headers.get("content-type"))

6.5 中间件装配​

app = FastAPI()
ROUTES = {
"/api/users": "http://127.0.0.1:9001",
"/api/orders": "http://127.0.0.1:9002",
}

app.add_middleware(RequestContextMiddleware) # 最外层:request_id
app.add_middleware(RateLimitMiddleware) # 限流
app.add_middleware(AuthMiddleware) # 鉴权
app.add_middleware(ReverseProxyMiddleware, # 转发
routes=ROUTES)

7. 生产部署清单​

7.1 必备​

  • ✅ TLS 终止:nginx / 云 LB
  • ✅ ProxyHeadersMiddleware(在 nginx 后取真实客户端 IP)
    from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware
    app.add_middleware(ProxyHeadersMiddleware, trusted_hosts="*")
  • ✅ 健康检查端点 /health(给 LB / k8s 用)
  • ✅ 优雅关闭(uvicorn 自带 SIGTERM 处理)
  • ✅ 多 worker(uvicorn --workers 4)—— 注意:内存版限流 / ConnectionManager 在 worker 间不共享

7.2 推荐​

  • 限流改 Redis(aioredis + 滑动窗口 Lua)
  • 熔断(tenacity + pybreaker,下游超时 / 5xx 自动隔离)
  • Prometheus 指标暴露(prometheus-fastapi-instrumentator)
  • 链路追踪(opentelemetry-instrumentation-fastapi)
  • 限流 / 鉴权策略热加载(不用重启网关)

7.3 网关也要高可用​

┌─ Gateway 1 ─┐
LB ───► │ │ ──► 下游服务
└─ Gateway 2 ─┘
  • 多实例 + 健康检查
  • 蓝绿 / 灰度发布(按权重切流量)
  • 配置中心统一管理(Consul / Nacos)

8. 网关常见坑​

坑现象修法
中间件顺序写反鉴权在限流前 → 未鉴权请求消耗限流名额按 5.2 顺序调整
没加 ProxyHeadersMiddleware网关看到的 IP 都是 127.0.0.1nginx 后必须加
body 读两次await request.body() 调两次,第二次空转发前缓存到局部变量
没过滤 hop-by-hop headerscontent-encoding 双重压缩 → 客户端解压失败过滤 content-encoding / transfer-encoding / connection
限流是内存版但多 worker单 worker 限流 100,整体可能是 400改 Redis 分布式限流
网关同步调用下游,下游慢拖垮网关网关全在等加超时 + 熔断 + 异步
忘记 CORS浏览器 OPTIONS 预检失败CORSMiddleware
网关无认证 / 公开 health 被攻击/health 等被恶意刷限流 + 只监听内网
路由冲突两个服务都用 /api/v1/userspath 前缀必须唯一
网关自身没限流网关被 DDoS 拖垮网关也要限流 + 入口 LB 抗 DDoS

关联笔记​

  • 鉴权流程(JWT / OAuth2 / 扫码):[[鉴权与登录笔记]]
  • 权限模型(拿到 token 后能做什么):[[权限模型与Casbin实践笔记]]
  • 反向代理 / TLS:[[nginx]](如已收录)
  • 容器编排(Ingress):[[I_Kubernetes基础笔记]]
  • 服务网格(Sidecar 形态的网关):[[DevOps基础与文化笔记]]

Demo​

完整可运行代码(FastAPI 网关 + 2 个模拟下游服务 + JWT 鉴权 + Casbin 权限检查 + 扫码登录):

标签:#fastapi

Django + FastAPI 秒杀系统课程

· 阅读需 1 分钟

由旧稿整理而来,内容未改,仅做结构与排版优化。旧稿目录已清理,当前以本文为准。

本笔记是网课资料汇总:课程观看入口 + 配套课件(语雀文档)+ 课程代码(百度网盘)。


1. 课程观看​

项链接
网易云课堂https://study.163.com/course/courseMain.htm?courseId=1213775829&_trace_c_p_k2_=a0edcec470e944d58a10b7445ae6e84e

2. 配套课件(语雀)​

全部为知了传课 / 知了课堂的语雀文档,对应模块密码见表格。

#模块课件链接文档标题访问密码
1异步 Djangohttps://www.yuque.com/hynever/async-django异步 Django 课件ra32
2微服务https://www.yuque.com/hynever/micro-service知了传课 - 微服务ancc
3FastAPIhttps://www.yuque.com/hynever/wms8gi知了传课 - FastAPIpuvz
4uniapphttps://www.yuque.com/hynever/uniapp知了课堂 - uniapp 课件kri4
5电商秒杀项目实战https://www.yuque.com/hynever/shtqfp知了课堂 - 电商系统实战zy6l

3. 课程代码(百度网盘)​

项内容
链接https://pan.baidu.com/s/19Pg3LWTjoqYhjRl1kWcjpw?pwd=gxem
提取码gxem

标签:#django #fastapi #redis #celery

权限模型笔记

· 阅读需 10 分钟

原 旧稿(RBAC / ABAC / ReBAC 三模型对比)的重写。 原笔记是定性对比,本笔记在此基础上补充 Casbin 库的落地实现(Python 版 PERM 模型、policy 文件、FastAPI 集成、RBAC with Domains、ReBAC 关系建模),让模型能真正用起来。

登录与鉴权流程见 [[鉴权与登录笔记]]。 网关中的鉴权中间件见 [[API网关原理与选型笔记]]。

目录​

  1. 三模型对比(RBAC / ReBAC / ABAC)
  2. RBAC 模型详解
  3. ReBAC 模型详解
  4. ABAC 模型简述
  5. Casbin 库核心(Python 版)
  6. RBAC 最小可运行示例(含角色继承)
  7. RBAC with Domains(多租户)
  8. ReBAC 关系建模(Casbin g2)
  9. RESTful 路径权限检查(keyMatch2)
  10. Casbin 在 FastAPI 中集成
  11. 实战:RBAC + ReBAC 混合

1. 三模型对比(RBAC / ReBAC / ABAC)​

模型一句话典型问题典型场景
RBAC你是什么身份你是不是管理员?后台菜单 / 按钮权限 / 组织架构
ReBAC你和它什么关系你是这个文档的 owner 吗?协作 / 项目 / 社交
ABAC你满足什么条件你是不是这个部门 + 当前是工作时间?数据权限 / 部门隔离 / 时段限制

口诀:

  • RBAC → 身份 / 角色
  • ReBAC → 关系 / 邻居
  • ABAC → 属性 / 规则

现实项目里很少只用一种:

场景组合
企业后台RBAC(菜单/按钮) + ABAC(数据范围)
多租户协作RBAC(平台角色) + ReBAC(项目成员)
复杂 SaaSRBAC + ABAC + ReBAC 三者混合

2. RBAC 模型详解​

2.1 三层结构​

用户 ──绑定──► 角色 ──绑定──► 权限

Alice ──► admin ──► [删除用户, 管理订单, 查看报表]
Bob ──► editor ──► [创建文章, 修改文章]
Tom ──► viewer ──► [查看文章]

2.2 角色继承​

admin ──继承──► user
editor ──继承──► user

admin 自动拥有 user 的所有权限,不必重复配置。

2.3 为什么 RBAC 是后台系统的默认选择​

  • 管理简单:权限挂在角色上,增删用户不动权限
  • 符合直觉:组织架构天然是角色化(部门 / 职位)
  • 实现成本低:一张 user_role 表 + 一张 role_permission 表就够

2.4 RBAC 不擅长什么​

editor 可以修改文章

但具体能改哪些文章?RBAC 答不了:

  • 所有文章?
  • 自己部门的?
  • 自己创建的?

答不了就走 ReBAC 或 ABAC(见下文)。


3. ReBAC 模型详解​

3.1 核心思想​

权限不是由角色或属性决定,而是由"用户和资源之间的关系"决定。

Alice ──[owner]──► doc_123
Bob ──[editor]──► doc_123
Carol ──[viewer]──► doc_123

Alice ──[member]──► team_A
team_A ──[owns]──► project_X
project_X ──[contains]──► doc_123
↓ 推导
Alice ──[viewer (继承)]──► doc_123 (因为她是 team_A 成员)

3.2 ReBAC 的直觉理解​

模型问的问题
RBAC你是谁?
ABAC你有哪些特征?
ReBAC你和这个对象是什么关系?

3.3 典型 ReBAC 场景​

场景关系
协作文档owner / editor / viewer
GitHub 仓库member / outside-collaborator
Notion / 飞书workspace member + page permission
社交friend / follower / blocked
项目team member / project owner / approver

3.4 ReBAC 的"关系链推导"​

用户 --[member]--> 团队
团队 --[owns]--> 项目
项目 --[contains]--> 仓库

↓ 推导
用户对该仓库有 [member] 权限

这种"从关系图推导权限"是 ReBAC 的核心特点,也是它实现起来比 RBAC 复杂的地方。


4. ABAC 模型简述​

ABAC 通过属性规则动态判断:

IF user.department == resource.department
AND user.level >= 2
AND action == "read"
THEN allow

四类属性:

  • 用户属性:部门 / 岗位 / 级别 / 地区
  • 资源属性:创建人 / 所属部门 / 敏感等级 / 状态
  • 操作属性:read / write / approve
  • 环境属性:时间 / IP / 地理位置 / 设备

适用:规则复杂多变(金融 / 医疗 / 政务)、需要细粒度条件。

代价:规则易膨胀,调试难。所以实际项目通常 RBAC 主导 + ABAC 补充。


5. Casbin 库核心(Python 版)​

Casbin 是一个通用的授权库,支持多种模型(RBAC / ABAC / ReBAC / RESTful),多种语言(Go / Java / Python / Node.js / PHP)。

核心思想:配置文件定义模型 + 策略文件定义数据,库帮你做"请求 → 决策"。

5.1 PERM 模型(Policy / Effect / Request / Matchers)​

任何 Casbin 模型都包含 4 段:

# 1. 请求定义:用户要做什么请求
[request_definition]
r = sub, obj, act

# 2. 策略定义:一条权限规则是什么样子
[policy_definition]
p = sub, obj, act

# 3. 角色定义(RBAC 用):用户到角色的映射
[role_definition]
g = _, _

# 4. 匹配器:请求和策略如何匹配(核心规则)
[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act

# 5. 效果:满足策略时的最终决定
[policy_effect]
e = some(where (p.eft == allow))

5.2 策略文件​

# policy.csv
p, alice, data1, read
p, bob, data2, write
p, data2_admin, data2, read
p, data2_admin, data2, write

g, alice, data2_admin # alice 继承 data2_admin 的所有权限

5.3 Python API 速查​

import casbin

e = casbin.Enforcer("model.conf", "policy.csv")

# 鉴权(核心)
e.enforce("alice", "data1", "read") # True(直接策略)
e.enforce("alice", "data2", "write") # True(通过 g 继承)
e.enforce("bob", "data1", "read") # False

# 运行时增删策略
e.add_policy("eve", "data3", "read")
e.remove_policy("eve", "data3", "read")

# 角色绑定
e.add_grouping_policy("alice", "data2_admin")
e.remove_grouping_policy("alice", "data2_admin")
e.get_roles_for_user("alice") # ["data2_admin"]
e.get_implicit_roles_for_user("alice") # 含继承传递
e.get_users_for_role("data2_admin") # ["alice"]

# 持久化
e.save_policy() # 写回 adapter

5.4 Adapter 选型​

Adapter适用
FileAdapter(CSV)demo / 小项目
casbin-sqlalchemy-adapter关系型数据库(推荐生产)
casbin-redis-adapter高频读 + 集群
casbin-mongodb-adapter文档型场景
# SQLAlchemy adapter 用法
from casbin_sqlalchemy_adapter import Adapter
import casbin

adapter = Adapter("postgresql://user:pass@host/db")
e = casbin.Enforcer("model.conf", adapter)
e.load_policy() # 从 DB 加载

6. RBAC 最小可运行示例(含角色继承)​

6.1 model.conf​

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act

6.2 policy.csv​

p, alice, data1, read
p, bob, data2, write
p, data2_admin, data2, read
p, data2_admin, data2, write

g, alice, data2_admin

6.3 验证​

import casbin
e = casbin.Enforcer("model.conf", "policy.csv")

e.enforce("alice", "data1", "read") # True(直接)
e.enforce("alice", "data2", "write") # True(继承自 data2_admin)
e.enforce("bob", "data2", "write") # True(直接)
e.enforce("bob", "data1", "read") # False

7. RBAC with Domains(多租户)​

问题:同一用户在不同租户有不同角色(如:Alice 在公司 A 是 admin,在公司 B 只是 user)。

7.1 model.conf(域扩展)​

[request_definition]
r = sub, dom, obj, act

[policy_definition]
p = sub, dom, obj, act

[role_definition]
g = _, _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub, r.dom) && r.dom == p.dom && r.obj == p.obj && r.act == p.act

7.2 policy.csv​

p, admin, tenant1, data1, read
p, admin, tenant2, data2, read
p, user, tenant2, data2, read

g, alice, admin, tenant1
g, alice, user, tenant2
g, bob, user, tenant2

7.3 验证​

e.enforce("alice", "tenant1", "data1", "read") # True(admin@tenant1)
e.enforce("alice", "tenant2", "data2", "read") # True(user@tenant2)
e.enforce("alice", "tenant2", "data1", "read") # False(tenant1 的 admin 不跨租户)
e.enforce("bob", "tenant1", "data1", "read") # False(bob 不是 tenant1 成员)

8. ReBAC 关系建模(Casbin g2)​

Casbin 默认 g 是用户-角色继承;g2 用于角色-角色继承,但更常见的用法是用 g 模拟"对象-关系"。

8.1 思路:把"关系"建模为 policy​

# 用户与资源的关系
p, doc_owner, doc_123, read
p, doc_owner, doc_123, write
p, doc_owner, doc_123, delete
p, doc_editor, doc_123, read
p, doc_editor, doc_123, write
p, doc_viewer, doc_123, read

# 谁是什么关系
g, alice, doc_owner, doc_123
g, bob, doc_editor, doc_123
g, carol, doc_viewer, doc_123

8.2 model.conf​

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _, _ # 用户, 关系角色, 资源

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub, r.obj) && r.obj == p.obj && r.act == p.act

8.3 验证​

e.enforce("alice", "doc_123", "delete") # True(owner)
e.enforce("bob", "doc_123", "write") # True(editor)
e.enforce("carol", "doc_123", "read") # True(viewer)
e.enforce("carol", "doc_123", "write") # False

生产环境关系数量爆炸(每个文档 × 3 种关系),需要把关系存数据库(adapter), 不要写 CSV 文件。


9. RESTful 路径权限检查(keyMatch2)​

场景:权限按 URL 路径 + HTTP 方法控制(如 alice 能访问 /api/users/* GET,admin 能访问 /api/* 任意方法)。

9.1 model.conf​

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub) && keyMatch2(r.obj, p.obj) && (r.act == p.act || r.act == "ANY")

9.2 policy.csv​

p, alice, /api/users/*, GET
p, bob, /api/orders/*, GET
p, admin, /api/*, ANY

g, alice, admin # alice 继承 admin 所有权限

9.3 验证​

e.enforce("alice", "/api/users/123", "GET") # True
e.enforce("alice", "/api/orders/1", "GET") # True(admin 继承)
e.enforce("bob", "/api/users/123", "GET") # False
e.enforce("admin", "/api/anything", "DELETE") # True(ANY)

keyMatch2 支持的路径模式:

  • /foo/:id 匹配 /foo/123
  • /foo/* 匹配 /foo/anything/more

10. Casbin 在 FastAPI 中集成​

10.1 单例 Enforcer​

# deps.py
import casbin
from functools import lru_cache

@lru_cache()
def get_enforcer() -> casbin.Enforcer:
return casbin.Enforcer("policy/model.conf", "policy/policy.csv")

# 用 SQLAlchemy adapter
# from casbin_sqlalchemy_adapter import Adapter
# @lru_cache()
# def get_enforcer():
# adapter = Adapter("sqlite:///casbin.db")
# return casbin.Enforcer("policy/model.conf", adapter)

10.2 依赖链:先鉴权(JWT)→ 再鉴权(Casbin)​

# main.py
from fastapi import Depends, FastAPI, HTTPException
from deps import get_enforcer
from auth import get_current_user # 见 [[鉴权与登录笔记]]

app = FastAPI()
enforcer = get_enforcer()


def check_permission(sub: str, obj: str, act: str):
if not enforcer.enforce(sub, obj, act):
raise HTTPException(403, "Forbidden")


@app.get("/api/users/{user_id}")
def get_user(
user_id: int,
user: dict = Depends(get_current_user),
):
check_permission(user["sub"], f"/api/users/{user_id}", "GET")
return {"user_id": user_id}


@app.delete("/api/users/{user_id}")
def delete_user(
user_id: int,
user: dict = Depends(get_current_user),
):
check_permission(user["sub"], f"/api/users/{user_id}", "DELETE")
# ... 业务逻辑
return {"deleted": user_id}

10.3 多租户 Casbin​

def check_permission_with_tenant(sub: str, tenant: str, obj: str, act: str):
if not enforcer.enforce(sub, tenant, obj, act): # 见 §7 模型
raise HTTPException(403, "Forbidden")

11. 实战:RBAC + ReBAC 混合​

11.1 场景​

某 SaaS 平台:

  • 平台层面:用户有 admin / member 角色(RBAC)
  • 项目层面:用户与项目有 owner / collaborator / viewer 关系(ReBAC)

11.2 model.conf(同时定义 RBAC 和 ReBAC)​

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _ # RBAC: 用户 - 平台角色
g2 = _, _, _ # ReBAC: 用户 - 资源关系 - 资源 ID

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = (g(r.sub, p.sub) || g2(r.sub, p.sub, r.obj)) \
&& r.obj == p.obj \
&& r.act == p.act

含义:用户要么通过平台角色(RBAC)要么通过资源关系(ReBAC)满足权限。

11.3 policy.csv​

# RBAC: 平台角色权限
p, admin, /api/projects/*, ANY
p, member, /api/projects/*, GET

# ReBAC: 项目关系 → 项目权限
p, owner, /api/projects/proj_123, ANY
p, collaborator, /api/projects/proj_123, GET
p, collaborator, /api/projects/proj_123, POST
p, viewer, /api/projects/proj_123, GET

# 平台角色绑定
g, alice, admin

# ReBAC 关系绑定
g2, alice, owner, proj_123
g2, bob, collaborator, proj_123
g2, carol, viewer, proj_123

11.4 验证​

# alice 是 admin,能操作任何项目
e.enforce("alice", "/api/projects/proj_123", "DELETE") # True(admin)
e.enforce("alice", "/api/projects/proj_999", "POST") # True(admin)

# bob 是 proj_123 的 collaborator
e.enforce("bob", "/api/projects/proj_123", "POST") # True(collaborator)
e.enforce("bob", "/api/projects/proj_123", "DELETE") # False(collaborator 没 DELETE)
e.enforce("bob", "/api/projects/proj_999", "GET") # False(不是 proj_999 成员)

关联笔记​

  • 登录鉴权流程(拿到用户身份):[[鉴权与登录笔记]]
  • 网关(鉴权中间件放哪):[[API网关原理与选型笔记]]
  • 数据库设计(角色表 / 权限表怎么设计):[[数据库设计与索引优化笔记]]

Demo​

完整代码:

Sources​

标签:#fastapi

鉴权与登录笔记

· 阅读需 13 分钟

原 旧稿(JWT 概念)+ 旧稿(OAuth2 + GitHub 第三方登录)的合并重写。 原笔记是概念罗列,本笔记在此基础上补全 4 种主流登录方式的完整流程、JWT 生产级实践(双 Token / 撤销 / 攻击防御)、扫码登录的时序设计。

权限模型(RBAC / ReBAC / Casbin)见 [[权限模型与Casbin实践笔记]]。 API 网关与鉴权中间件见 [[API网关原理与选型笔记]]。

目录​

  1. 登录方式全景对比
  2. 账号密码 + JWT(最常用)
  3. OAuth2 第三方登录(含 GitHub 完整流程)
  4. 扫码登录(PC + 移动 App)
  5. 手机号验证码登录
  6. Token 存储位置安全对比
  7. JWT 安全攻击与防御(RFC 8725)
  8. Token 撤销 / 黑名单
  9. JWT 完整代码示例 + 选型

1. 登录方式全景对比​

方式用户体验安全性适用场景关键技术
账号密码 + JWT中(要注册)中(密码泄漏风险)通用 Web / Appbcrypt + 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含义必填?
subsubject(用户 ID)✅
iatissued at(签发时间)推荐
expexpiration time(过期时间)✅
ississuer(签发方)推荐
audaudience(接收方)推荐
jtiJWT ID(唯一标识,用于黑名单)推荐
nbfnot 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 TokenRefresh Token
过期时间15 分钟 ~ 2 小时7 ~ 30 天
用途访问受保护 API换新的 Access Token
存储内存 / httpOnly cookiehttpOnly 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 URLhttps://yourapp.com
Authorization Callback URLhttps://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 字段指向攻击者控制的路径 / SQLkid 白名单 / 不解析为路径
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 算法选型​

算法类型密钥适用
HS256HMAC 对称单一密钥单服务 / 内部系统
RS256RSA 非对称私钥签 / 公钥验多服务 / 对外提供 SSO
ES256ECDSA更短移动端 / 高性能
EdDSAEd25519现代高性能新系统

原则:单服务用 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