📑 本页目录(点开跳转)
08 · 认证、会话与多租户
⏱ 40 分钟 | ⭐ 别自己存密码;也别指望「记得写 WHERE tenant_id」
🎯 一句话
认证的成本不在「验密码」那一步,多租户的风险也不在「加个字段」那一步 —— 两件事真正要命的地方都在于:出了错,没有任何东西会告诉你。 这一章先选会话方式,再把当前授权范围传到数据访问和审计。
🧩 一、先把两个词分清
| 问的是 | 答错的后果 | |
|---|---|---|
| 认证 Authentication | 你是谁? | 陌生人变成了张三 |
| 授权 Authorization | 你能做什么? | 张三看见了李四公司的数据 |
Acme 员工小林登录后可以看本公司的报告,但不能因此读取 Globex 的报告。登录验证身份,后续请求仍要验证会话或访问凭证。访问某个对象时,应用还要检查这位用户此刻能对该对象做什么。身份提供方可以验证小林是谁,应用仍须提供文档归属与访问规则。
🔑 二、三条路,和一个明确的建议
| 路 | 你要维护什么 |
|---|---|
| ① 自己做密码登录 | 哈希、注册、登录、改密、忘密、邮件、验证码、限流、撞库检测、多设备登出、合规 |
| ② OIDC 第三方登录 | 使用成熟客户端处理回调、验证身份并绑定本地账号 |
| ③ 托管认证服务 🗓️ | 一段校验凭证的代码 + 配置 |
⭐ 建议就一句:绝大多数人应该走 ② 或 ③。 不是因为你写不出密码校验 —— 那反而是最简单的一格;是因为写完那一格之后还有十几格。
⚠️ 就算只做第一格,也有三个「知道才会写」的细节:慢哈希(scrypt / argon2;不能用 SHA-256,它太快,而快正是攻击者要的)、每人一份独立盐(否则一张彩虹表通吃)、等时比较(== 会泄漏「第几个字节开始不同」)。还要把算法和代价参数存进哈希串,否则日后升级算法时老记录你验都验不动。
⚠️ 这块代码的特点是「写完就再没人碰」,没有任何日常信号会提醒你算法选错了 —— 等泄库时才发现存的是无盐 MD5,而用户在别的站用了同一个密码。
OAuth 2.0处理应用获得资源访问权限的问题。OpenID Connect(OIDC)在它之上增加验证用户身份的约定。第三方登录完成后,还要把可信身份映射到应用账号。详见 OpenID Connect Core 和 第 08d 章。
🍪 三、会话怎么维持:Cookie 还是 Bearer
登录成功后,下一次请求还得证明「是同一位用户」。下表比较两种常见的传送方式。Cookie 里的值可以只是会话编号,Authorization: Bearer … 里的访问令牌也可以是需要查表的随机字符串。值的格式和发送位置要分开判断。
| Cookie(浏览器自动带) | Bearer(前端手动放进 header) | |
|---|---|---|
| 浏览器跨源请求 | 携带 Cookie 要满足凭证设置、CORS 和 Cookie 策略 | 显式设置请求头,跨源时仍需 CORS 预检 |
| XSS(跨站脚本) | HttpOnly 禁止脚本读取值,同源脚本仍可代发请求 |
脚本能访问的令牌仍需防泄露 |
| CSRF(跨站请求伪造) | 自动附带的凭证需要 CSRF 防护 | 仅接受显式请求头时,不依赖自动带凭证 |
| 适合 | 常见于同源网页应用 | 常见于移动端和第三方 API |
同源网页可以从服务端会话和
HttpOnly、Secure、SameSite=Lax开始。状态变更应按 第 08c 章设计 CSRF 防护。跨源判断源是否相同,跨站判断 Cookie 的站点边界,同站子域也可能跨源。参见 第 08b 章、RFC 6265 Cookie 属性和 RFC 6750 Bearer 请求头。
查表式会话在服务端保存用户、到期时间和撤销状态。每次请求都读最新状态时,撤销可在下一次校验生效。签名自包含令牌可以不查会话表就校验签名及声明,但只有签名的 JWT 内容是可解码的,敏感内容别放进去。短时效访问令牌能缩短旧权限的有效时间,停止刷新后,已发放的访问令牌仍可能用到过期。需要更快撤销时要接入服务端状态检查,详见 第 08e 章。
⚠️ 流式请求带凭证的坑(第 10 章会正面撞上)
浏览器原生的 EventSource 不能自定义请求头,也就是带不了 Authorization。于是很多人塞进 URL:/stream?token=xxx。⚠️ 这是个坏主意 —— URL 会进服务端访问日志、反向代理日志、浏览器历史、Referer,一份凭证抄成四份,而日志通常不脱敏、留存很久。
三条出路:① 同源 Cookie(自动带、不进 URL);② 换 fetch + ReadableStream(能自己设 header,第 10 章的主推做法);③ 换一张几十秒过期的一次性票据。
🧷 四、用依赖注入拿到「当前用户」
第 3 章把 current_user 留作依赖注入的接口。这里让受保护的路由统一经过身份解析、成员关系检查,再把结果交给业务代码。只有声明了依赖的路由才会执行它,所以还要用路由分组和匿名访问回归测试确认保护范围。
# FastAPI 接入片段。app_auth、app_docs 是由项目提供的模块。
from fastapi import Depends, FastAPI, HTTPException
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from app_auth import Principal, membership, verify_access_token
from app_docs import list_titles
app = FastAPI()
bearer = HTTPBearer(auto_error=False)
def current_principal(
tenant_id: str,
credential: HTTPAuthorizationCredentials | None = Depends(bearer),
) -> Principal:
# 由可信验证器校验签发者、受众、有效期与凭证类型。
user_id = verify_access_token(credential.credentials) if credential else None
if user_id is None:
raise HTTPException(401, headers={"WWW-Authenticate": "Bearer"})
role = membership(user_id, tenant_id)
if role not in {"viewer", "editor"}:
raise HTTPException(403)
return Principal(user_id, tenant_id, role)
@app.get("/api/tenants/{tenant_id}/docs")
def list_docs(me: Principal = Depends(current_principal)):
return list_titles(me)这里 Principal 保存本次请求的可信身份、授权租户和角色。租户参数只表达「想打开哪个工作区」。后端用已验证的身份查当前成员关系,才把租户放入 Principal。同一用户在两个工作区可以有不同角色。该路由只接受 Bearer,若服务还提供 Cookie 路由,凭证解析可复用同一身份层,每条路由仍应明确接受哪一种。上面是接入示意,项目需提供验证器、成员关系查询与数据层。参见 FastAPI 依赖文档。
🏢 五、多租户:AI 产品最容易出事故的地方
多租户 = 一套服务同时服务多家客户。bug 不再是「用户看到不该看的按钮」,而是「A 公司看到了 B 公司的合同」。
| 档 | ✅ | ⚠️ 代价 |
|---|---|---|
① 共享表 + tenant_id 列(靠 WHERE 分开) |
最省、加租户零成本 | 隔离全靠代码正确;大租户拖慢小租户 |
| ② 每租户一个 schema | 误查跨不过去、按租户备份 | 改表要循环 N 次;上千租户时迁移和连接池都难受 |
| ③ 每租户一个库 | 隔离最强、可单独扩容 | 成本和运维复杂度乘 N |
⭐ 默认选 ①;有合规硬要求或超大客户单独付钱,就对那几个用 ③ —— 混合是最常见的真实答案。 ⚠️ 向量库同档:embedding 里带着原文的信息,别因为「它只是一堆浮点数」就放松。
隔离边界与容量分片分开判断:分库分表把数据/负载拆到不同逻辑库表,但是否跨物理节点还取决于部署;分片本身也不替代副本。
- 垂直拆分:按业务域或字段访问模式分开,例如账务与内容;要重新判断跨域关联和事务边界。
- 水平范围:同一结构按租户键或时间等范围分行,范围查找直观,但活跃范围可能形成热点。
- 水平哈希:按稳定分片键映射,可能分散负载;热门租户仍可能很热,范围查询常需跨片。
代价包括跨片事务、JOIN/聚合与全局唯一键/发号,路由、扩容再均衡、迁移核对和备份恢复也更复杂。可信登录身份决定可访问租户,服务端路由再选分片;客户端传来的分片号不能当权限。路由后仍须核租户权限,并测试跨租户请求被拒。依据:数据分区策略与代价。分表或表分区不自动跨节点,未运行分片迁移。
⚠️ 为什么「忘了加 WHERE tenant_id」特别可怕
普通 bug 会报错、会崩、会被测试抓住。这个不会:
- 不报错 —— 少一个条件,SQL 照样合法执行,只是多返回几行
- 测试环境看不出来 —— 测试库大概率只有一个租户,加不加条件结果一模一样
- 静默越权 —— 没有 403、没有异常、没有告警,只有客户某天打电话说「我搜到了别人公司的名字」
- 不可撤销 —— 数据已经渲染在对方屏幕上了,事后改代码撤销不了「已经被看见」
⭐ 所以这类问题不能靠「记得写」防,只能靠「写错跑不通」防。 任何形如「所有人都要记得在每个查询里加 X」的规范,都会在第 200 个查询上失效 —— 不是人不专业,是概率。
⭐ 三层结构性防御
第一层:只向业务代码提供已经绑定授权范围的数据接口。固定查询由仓储层维护,参数值由驱动绑定。调用方不自行拼接查询。先跟完一条请求,再看数据库如何复查范围。
小林点开「Acme 的季度报告」后发生什么
Acme 和 Globex 都可以有编号 d7 的文档。若系统只按文档编号取数据,它无法知道小林要看哪份报告。下图每一格都对应代码中的一次判断。
同源 Cookie 方案中,登录响应可设 Set-Cookie: sid=<会话编号>; Path=/; Secure; HttpOnly; SameSite=Lax,随后浏览器请求 GET /api/tenants/acme/docs/d7 并带上 Cookie: sid=<会话编号>。后端按上图检查,成功回 200 和 {"id":"d7","title":"Acme 的季度报告"}。会话失效属于身份失败,应用记录为 401。会话有效但没有对应操作权限为 403。已授权范围内无可见对象可回 404,无需查别的租户来解释原因。参见 RFC 9110 的客户端错误语义。
把下面代码保存为 tenant_demo.py,运行 python tenant_demo.py。它用内存里的会话、成员关系和 SQLite 文档模拟上面四站。登录已经完成,编号和时间都是固定的测试数据,代码不会启动 HTTP 服务。
import sqlite3
from contextlib import closing
from dataclasses import dataclass
@dataclass(frozen=True)
class Principal:
user_id: str
tenant_id: str
role: str
class AccessDenied(Exception):
def __init__(self, status: int):
super().__init__(status)
self.status = status
def resolve_principal(sessions, members, sid, requested_tenant, now):
# 会话表由服务端维护。查不到也包含已撤销的会话。
session = sessions.get(sid)
if session is None:
raise AccessDenied(401)
user_id, expires_at = session
if now >= expires_at:
raise AccessDenied(401)
role = members.get((user_id, requested_tenant))
if role not in {"viewer", "editor"}:
raise AccessDenied(403)
return Principal(user_id, requested_tenant, role)
def read_document(db, me, doc_id):
row = db.execute(
"SELECT title FROM docs WHERE tenant_id = ? AND id = ?",
(me.tenant_id, doc_id),
).fetchone()
if row is None:
raise AccessDenied(404)
return {"id": doc_id, "title": row[0]}
def rename_document(db, me, doc_id, title):
if me.role != "editor":
raise AccessDenied(403)
with db:
result = db.execute(
"UPDATE docs SET title = ? WHERE tenant_id = ? AND id = ?",
(title, me.tenant_id, doc_id),
)
if result.rowcount == 0:
raise AccessDenied(404)
return {"id": doc_id, "title": title}
def handle(db, sessions, members, sid, tenant, doc, now, *, new_title=None):
try:
me = resolve_principal(sessions, members, sid, tenant, now)
if new_title is None:
return 200, read_document(db, me, doc)
return 200, rename_document(db, me, doc, new_title)
except AccessDenied as exc:
return exc.status, None
if __name__ == "__main__":
with closing(sqlite3.connect(":memory:")) as db:
db.execute(
"CREATE TABLE docs (tenant_id TEXT, id TEXT, title TEXT, "
"PRIMARY KEY (tenant_id, id))"
)
db.executemany("INSERT INTO docs VALUES (?, ?, ?)", [
("acme", "d7", "Acme 的季度报告"),
("globex", "d7", "Globex 的季度报告"),
])
db.commit()
# 时间用同一时钟的秒数,当前 100 秒,200 秒时失效。
sessions = {"lin-sid": ("lin", 200), "wu-sid": ("wu", 200)}
members = {
("lin", "acme"): "editor", ("lin", "globex"): "viewer",
("wu", "acme"): "viewer",
}
def visit(sid, tenant, doc="d7", *, now=100, title=None):
return handle(db, sessions, members, sid, tenant, doc, now, new_title=title)
status, doc = visit("lin-sid", "acme")
assert doc == {"id": "d7", "title": "Acme 的季度报告"}
saved, _ = visit("lin-sid", "acme", title="Acme 已核对")
assert visit("lin-sid", "acme") == (200, {"id": "d7", "title": "Acme 已核对"})
# 同一编号的 Globex 文档仍是原值。
assert visit("lin-sid", "globex") == (
200, {"id": "d7", "title": "Globex 的季度报告"},
)
cases = [
("读取 Acme 文档", status, 200),
("编辑者改名", saved, 200),
("缺少会话", visit(None, "acme")[0], 401),
("会话刚好过期", visit("lin-sid", "acme", now=200)[0], 401),
("只读成员改名", visit("lin-sid", "globex", title="新名字")[0], 403),
("没有 Globex 成员资格", visit("wu-sid", "globex")[0], 403),
("授权范围内无此文档", visit("lin-sid", "acme", "d8")[0], 404),
]
assert visit("lin-sid", "globex")[1]["title"] == "Globex 的季度报告"
del members["lin", "acme"]
cases.append(("会话仍有效,但成员资格撤销", visit("lin-sid", "acme")[0], 403))
del sessions["lin-sid"]
cases.append(("退出后旧会话失效", visit("lin-sid", "globex")[0], 401))
for label, actual, expected in cases:
assert actual == expected, (label, actual, expected)
print(f"{label} → {actual}")顺序对照代码:resolve_principal 校验会话并查当前角色,read_document 只读取该租户下的编号,rename_document 还要求编辑权限。示例约定该租户成员可读其共享文档。遇到私有文档或单独分享时,还要在同一个授权范围内核对对象权限。模拟是单线程的,生产写入需要在一致的权限判定和数据写入边界内处理撤销等并发变化。
先预测,再对照输出。小林是 Acme 的编辑者、Globex 的只读成员。她能改 Acme 的 d7,但不能改 Globex 的 d7。撤销 Acme 成员资格后,会话还有效,但读 Acme 变成 403。删除会话后,读仍有成员资格的 Globex 则变成 401。程序逐条断言并打印九种结果。
同一边界也要传给下游。向量检索先限定本次授权可用的候选,再把文档交给模型。模型提议调用工具时,服务端仍须按当前用户和对象权限复查。缓存命中之前检查当前授权,缓存键还要覆盖租户、实际可见范围和资源版本。权限变更后应让旧范围的条目失效,或在返回前按当前对象权限重新校验。
记录授权决策时,可保留请求 ID、经确认的用户与租户、操作、结果和内部原因类别。对未授权的工作区请求,把选定工作区与已授权租户分开。凭证、文档全文和提示词不写入审计日志。对应字段与留存见 第 15 章。
第二层用至少两个租户的测试数据验证读取和写入,覆盖同编号、无成员资格和撤销。第三层在 PostgreSQL 用行级安全(Row-Level Security,RLS)限制应用数据库角色能读写哪些行。下例假设 tenant_id 是文本列,应用角色已经有必要的表权限:
-- ⚠️ 未实跑,需要 PostgreSQL
ALTER TABLE docs ENABLE ROW LEVEL SECURITY;
ALTER TABLE docs FORCE ROW LEVEL SECURITY; -- ⭐ 连表的属主也一起管住
CREATE POLICY tenant_isolation ON docs
USING (tenant_id = current_setting('app.tenant_id', true))
WITH CHECK (tenant_id = current_setting('app.tenant_id', true));
USING 限制可见或可修改的原有行,WITH CHECK 检查写入后形成的新行。业务事务开始后,用参数化的 set_config('app.tenant_id', …, true) 写入已经授权的租户值,再在同一事务里执行查询。true 让设置仅在当前事务生效。有效租户编号必须非空。未设置租户时,本例不会匹配有效租户行。应用连接应使用非表所有者且没有 BYPASSRLS 的普通角色。FORCE 让表所有者也受行策略约束,超级用户及拥有 BYPASSRLS 的角色仍不适用。策略只检查行的租户归属,具体对象权限仍由业务规则决定。参见 PostgreSQL 行级安全。
💀 事故的典型形状:某天加了个「全局搜索」接口,作者为了性能绕过仓储层直接拼了句 LIKE,结果混进了别家租户的文档标题(标题本身就带客户名)。没被发现:单测种子只有一个租户,少条件结果完全一样;评审看的是注入和索引;没有任何监控会因为「多返回几行」而波动。
⭐ 最便宜的一条防线:让测试种子数据里永远至少有两个租户。 它把「静默的越权」变成「一跑就红的断言」,成本几乎为零。
🔁 六、换个栈怎么对应
| 概念(不会过期) | Python / FastAPI | Node(Express / Hono) | Go |
|---|---|---|---|
| 从请求解析身份 | Depends(current_principal) |
中间件写进 req.user / c.set() |
包一层 Handler,写进 context.Context |
| 强制不可跳过 | 声明式参数依赖 ⭐ | 路由分组挂中间件;⚠️ 忘挂就漏 | 只暴露「已鉴权」的注册函数 |
| 签名凭证 / Cookie 属性 | 成熟 JWT 库 🗓️;HttpOnly/Secure/SameSite |
同名,写法不同 | 同名 |
| 绑定租户的数据句柄 / 数据库兜底 | 仓储类或 ORM 全局过滤 + Postgres RLS | 同 | 同 |
⭐ 换语言换掉的只是「中间件」还是「依赖」这个叫法。 「从已验证会话或凭证取得身份」「从当前授权关系确定数据范围」「数据库层再兜一次」这三条,到哪个栈都一样。
🔗 这一章连到哪里
| 去哪 | 为什么 |
|---|---|
| 数据这一关 19 · 隐私脱敏与留存 | 隔离解决「谁能看」,那一章解决「本来就不该存」。⭐ 日志、prompt、向量库都在沉淀用户原文,隔离再好也挡不住存了不该存的东西 |
| 智能体工程教程 15 · 安全-沙箱与提示注入 | 本章防「代码写漏」,那章防「模型被骗」。⚠️ 两者会叠加:模型被注入后会主动去要别人的数据,所以隔离必须做在数据层 |
| 智能体工程教程 16 · 企业落地与生产化 | 那一章「合规与风险」一节把 To B 采购真正卡的关列成了表:数据去向、PII 脱敏、⭐ 可追溯的审计日志、高风险决策要有人工介入。⭐ 本章的租户隔离是其中「数据边界」那一条的实现侧,那一章讲的是为什么签不了单 |
| 03 · 后端骨架 | ⭐ 那一章的 current_user 依赖是个空壳挂载点,明说了「留给第 8 章」。第四节的 current_principal 演示把身份与成员关系校验接进受保护路由 |
| 07 · 向量检索落地 | 那一章的检索按业务授权范围筛选候选。租户共享、个人私有和对象级分享可以有不同规则。向量也保留原文的信息,要和原文一起纳入授权范围与隔离测试 |
| ⭐ 08b · 同源策略与 CORS | 本章第三节区分了跨源请求与跨站 Cookie。第 08b 章展开同源策略、CORS 与预检请求 —— ⚠️ 16 章那条 CORS 检查项以前写着「本板块未展开」,现在指的就是它 |
| ⭐ 08c · CSRF 与 XSS | 本章的对照表里 CSRF 和 XSS 各占一格(「自动带 = 别人的页面也能替你带」)。那一章把这两格展开成两套完全不同的防线 —— ⭐ 也终于给第 10 章那套净化判据起了名字 |
| ⭐ 08d · OAuth2 与 OIDC | 本章第二节给出 OIDC 或托管认证的选型起点。第 08d 章展开回调与账号绑定:授权码流程为什么要绕一圈、state 防什么、PKCE 解决什么 |
| ⭐ 08e · JWT | ⚠️ 本章第三节末尾那段「查表式 vs 签名自包含、吊销难」只讲了两百字就停了。那一章从这里接着讲:三段结构、四种绕过、以及吊销真正的几种解法 |
| 10 · 把流式接到界面上 | 第三节「EventSource 带不了 Authorization」那个坑,在那一章正面解决 |
✅ 检查点
- 认证和授权分别问什么?登录成功后,访问一份报告还需确认什么?
- 三条登录路建议走哪条?自己存密码有哪三个「知道才会写」的细节?
- Cookie 自动附带与 Bearer 请求头有什么差别?同源网页有哪些基本的 Cookie 设置和请求防护?
- 签名自包含凭证的两个反直觉点是什么?为什么不能把 token 放进
?token=xxx? - 依赖注入能统一哪些检查?怎样确认所有受保护路由都经过它?
- 「忘了加 WHERE tenant_id」为什么特别可怕(四点)?三层防御各挡住什么?
- 小林登录有效,是 Acme 编辑者和 Globex 只读成员。她能否修改两个工作区的
d7?退出和单独撤销 Acme 成员资格后,下一次读取的结果有何差别?
👀 答案
- 认证问「你是谁」,授权问「你能对哪个对象做什么」。先验证这次请求的会话或凭证,再核对当前的租户成员关系和报告的访问条件。
- 走 ② OIDC 或 ③ 托管服务 —— 密码校验是最简单的一格,后面还有改密、忘密、验证码、限流、撞库、多设备登出、合规十几格。三个细节:慢哈希、每人一份独立盐、等时比较。
- 浏览器会按规则自动带 Cookie,状态变更要做 CSRF 检查。
HttpOnly限制脚本读值,Secure约束传输,SameSite=Lax限制部分跨站附带。仅接受显式 Bearer 请求头的路由不使用自动附带的会话,仍要保护令牌并防止同源脚本被注入。 - ① payload 只是 base64 不是加密,别塞敏感信息;② 吊销难(解法:短时效访问凭证 + 长时效刷新凭证)。token 不能进 URL,因为它会被服务端日志、代理日志、浏览器历史、Referer 各抄一份。
- 身份解析与成员资格检查可以作为同一个依赖交给受保护路由,避免每个处理函数重复实现。仍要用统一路由分组和匿名访问测试确认保护没有漏挂。
- 不报错、测试环境看不出来(测试库通常只有一个租户)、静默越权(无 403、无异常、无告警)、不可撤销。三层:数据接口绑定范围,双租户测试覆盖遗漏,数据库行级策略再限定应用角色能读写的行。租户设置只在当前事务有效。
- 她只能改 Acme 的文档。撤销 Acme 成员资格后,登录会话仍有效,但读取 Acme 返回
403。退出使会话失效后,再访问受保护页面先得到401。
本节回顾
⚡ 走神救援
先记住这几件事
- 认证回答你是谁,授权回答你能访问什么;登录外包后仍要逐次检查权限。
- 会话、凭证与租户身份必须由可信的服务端流程建立,不能相信请求里的租户号。
- 数据库访问统一绑定租户条件,并用至少两个租户的数据测试隔离。
- Cookie、Bearer 和刷新凭证各有风险,按本章流程检查存储、过期与退出。
下一节 👉 08b-同源策略与CORS.md