FastAPI 安全入门指南：从 OAuth2、OpenID Connect 到 OpenAPI 安全方案与 `fastapi.security` 工具

安全（Security）、认证（Authentication）与授权（Authorization）的实现方式多如牛毛，在多数框架与系统中，这部分代码往往要占据全部工作量的 50% 甚至更多。FastAPI 官方教程以本页（对应仓库 docs/en/docs/tutorial/security/index.md）作为"安全专栏"的总纲，逐一澄清 OAuth2、OpenID Connect、OpenAPI 等容易被混淆的规范概念，并预告 fastapi.security 内置工具如何在无需通读全部规范的前提下，用标准方式快速为 API 加上安全机制。读完本文，你将能理清"第三方登录"背后的协议栈、准确区分 OpenAPI 四类 security scheme，并了解如何借助 FastAPI 依赖注入体系把安全校验自动接入交互式文档，为后续动手实现用户名/密码认证、获取当前用户、JWT 等完整章节铺路。

为什么安全、认证、授权常常"难"？

在 Web 后端中，安全通常可以拆成三个层面：

• Security（安全）：保证请求来自合法来源、传输与凭证不被窃取与篡改的整体机制；
• Authentication（认证）：确认"你是谁"，即验证身份凭证；
• Authorization（授权）：确认"你能做什么"，即决定已认证主体对资源的访问范围。

原文档指出，在很多框架与系统中，仅实现安全与认证就要投入巨大精力和代码量。FastAPI 的设计目标之一是提供一组标准化、开箱即用的工具，把复杂度收敛到框架内部，让开发者不必先啃完所有安全规范才能动手。

需要说明的是：FastAPI 本身并不重新发明一套安全协议，而是围绕已有的行业标准（OAuth2、OpenAPI 等）做工程化封装。这样做的收益是——你的 API 安全声明可以被各类标准工具（文档系统、代码生成器、测试客户端）自动识别和复用。

时间紧迫？先记住这条路径

原文档专门设置了 "In a hurry?" 提示：如果你暂时不关心上述术语细节，只希望立刻为接口加上基于用户名和密码的认证，可以跳过本页直接阅读后面的实战章节。建议的快速路线（均位于英文文档教程目录下，对应本仓库）：

1. Security - First Steps（第一步：添加安全依赖）：演示如何用一个安全依赖让接口"保护"起来，并看到交互式文档中出现 Authorize 按钮；
2. Current User（获取当前用户）：在依赖中解析凭证并返回当前用户对象；
3. Simple OAuth2 with Password and Bearer（密码流 + Bearer 令牌的简单 OAuth2）：真正实现登录换 token 的完整流程；
4. OAuth2 with JWT（基于 JWT 的 OAuth2）：生产级常用的无状态令牌方案。

如果你希望横向加深理解（可选），还可以继续阅读进阶章节 HTTP Basic Auth 与 OAuth2 Scopes（作用域授权）。

OAuth2：认证与授权的"事实标准"

OAuth2 是什么

OAuth2 是一份定义了多种处理认证与授权方式的规范（RFC 6749），覆盖面广、使用场景复杂。它最重要的能力之一是支持"第三方登录"——所有"使用 Facebook / Google / X(Twitter) / GitHub 登录"的系统，底层基本都是 OAuth2。换言之，OAuth2 是一种委托授权框架：资源所有者允许第三方应用在有限范围内访问其受保护资源，而无需交出密码。

OAuth 1 与 OAuth2 的区别

需要特别区分的是，历史上还存在一个 OAuth 1，它与 OAuth2 差异极大，反而更复杂：OAuth 1 直接规定了如何对通信进行加密；而 OAuth2 不规定如何加密通信，它假定你的应用运行在 HTTPS 之上。这也是为什么 OAuth2 体系里"传输安全交给 TLS"成为默认前提。如今 OAuth 1 已不流行、基本不再被使用。

原文档在此给出了重要提醒：在**部署（Deployment）**章节中可以看到如何免费配置 HTTPS（例如使用 Traefik 与 Let's Encrypt）。本仓库对应英文文档为 docs/en/docs/deployment/https.md，部署总览见 docs/en/docs/deployment/index.md。在实际把 OAuth2 应用上线前，为站点启用 HTTPS 是必不可少的前置条件。

OpenID Connect：基于 OAuth2 的互操作层

OpenID Connect 是另一份规范，它建立在 OAuth2 之上，本质是对 OAuth2 中若干相对含糊的部分做补充与细化，目标是提高不同实现之间的互操作性。举例来说：Google 登录走的是 OpenID Connect（底层仍是 OAuth2）；而 Facebook 登录并不支持 OpenID Connect，它使用的是自己"风味"的 OAuth2 变体。

注意：OpenID 与 OpenID Connect 不是一回事

历史上还存在一份名为 OpenID 的规范。它试图解决与 OpenID Connect 相同的问题（身份认证），但并非基于 OAuth2，而是一套完全独立、额外的系统。如今 OpenID 同样已不流行、很少被使用。

把这条概念链理顺后，一个常见的理解误区也随之澄清：OAuth2 更偏向"授权"（放行第三方访问资源），OpenID Connect 在其上补充"认证"语义（告诉应用"用户是谁"），二者通常是叠加而非对立的关系。

OpenAPI 与它的安全方案（Security Schemes）

OpenAPI 是什么

OpenAPI（前身为 Swagger）是构建 API 的开放规范（现归属 Linux Foundation）。FastAPI 正是基于 OpenAPI 构建的——这正是它能自动生成多种交互式文档界面、支持代码生成等能力的原因。

OpenAPI 提供了一套声明**安全方案（security scheme）**的方式。使用这套声明，你定义的 API 就能被所有基于标准的工具识别，包括交互式文档系统（如 /docs 与 /redoc），从而获得自动的"Authorize"体验。

OpenAPI 定义的四类安全方案

原文档把 OpenAPI 支持的 security scheme 归纳为四种，这也是理解后续 fastapi.security 工具集的"坐标系"。在仓库源码 fastapi/openapi/models.py 中可以看到它们被建模为 SecuritySchemeType 枚举，取值恰好一一对应：

方案类型	含义	细分为
apiKey	应用专属密钥，可来自查询参数 / 请求头 / Cookie	APIKeyIn.query、APIKeyIn.header、APIKeyIn.cookie（见 models.py）
http	标准 HTTP 认证体系	bearer（Authorization: Bearer <token>，继承自 OAuth2）、HTTP Basic、HTTP Digest 等
oauth2	OAuth2 的各种处理方式（称为 flow）	implicit、clientCredentials、authorizationCode、password
openIdConnect	自动发现 OAuth2 认证数据的方式	其自动发现机制即由 OpenID Connect 规范定义

关键提示：OAuth2 的多数 flow（implicit、clientCredentials、authorizationCode）适合用来构建一个 OAuth 2.0 认证提供方（如 Google、Facebook、X/Twitter、GitHub 这样的平台）；而其中专门有一个 flow——password——可以完美用于在同一个应用内直接处理认证。后续章节（Simple OAuth2 等）给出的例子正是基于 password flow。

原文档同时提示：集成 Google、Facebook、X/Twitter、GitHub 等第三方认证提供方同样是可行且相对容易的。真正的难点在于"构建一个像它们那样的认证/授权提供方"，而 FastAPI 提供的工具正好能帮你在实现这类复杂目标时"帮你扛下重活"。

FastAPI 的实用工具：fastapi.security 模块

对应上面四类 OpenAPI 方案，FastAPI 在 fastapi.security 模块中提供了成套工具类。从 fastapi/security/init.py 可以看出模块完整导出清单，下面按方案分类映射：

OpenAPI 方案	FastAPI 工具类（源码文件）	说明
apiKey（query/header/cookie）	APIKeyQuery、APIKeyHeader、APIKeyCookie（api_key.py）	从对应位置提取 key
http	HTTPBasic、HTTPBearer、HTTPDigest（http.py）	解析 Authorization 头
oauth2	OAuth2PasswordBearer、OAuth2AuthorizationCodeBearer、OAuth2PasswordRequestForm、SecurityScopes 等（oauth2.py）	覆盖 password / authorizationCode flow
openIdConnect	OpenIdConnect（open_id_connect_url.py）	以 URL 声明自动发现端点

这些类统一继承自 fastapi/security/base.py 的 SecurityBase（其上声明 model 与 scheme_name 两个字段），并被设计为依赖项（dependency）：在路径操作参数中通过 Depends(...) 使用，安全逻辑便作为请求处理链的一环被自动执行。

统一的设计：提取凭证 + 401 挑战

从源码可以归纳出工具类一致的运行模式：

1. 从请求中提取凭证：APIKeyQuery/Header/Cookie 分别从 request.query_params、request.headers、request.cookies 中取值；HTTP/OAuth2 家族则统一读取 Authorization 头。
2. 头部解析：fastapi/security/utils.py 中 get_authorization_scheme_param() 用 partition(" ") 按第一个空格把 Authorization 值切分为 scheme 与 credentials 两部分——例如 Bearer deadbeef12346 会得到 scheme="Bearer"、credentials="deadbeef12346"（其数据结构见 http.py 中的 HTTPAuthorizationCredentials）。
3. 缺失时返回 401 挑战：默认情况下（auto_error=True）凭证缺失时工具类会抛出 401 HTTPException，并按要求附带 WWW-Authenticate 挑战头（例如 Bearer 方案发 WWW-Authenticate: Bearer、HTTP Basic 发 WWW-Authenticate: Basic）。
4. auto_error=False 支持可选认证：此时凭证缺失不会报错，依赖结果退化为 None，便于实现"可选认证"或"多种方式任选其一"的认证（如"要么带 Bearer token、要么带 Cookie"）。

关键工具类速览

以仓库源码为准，几个最常使用的类构造参数如下：

• APIKeyQuery/APIKeyHeader/APIKeyCookie(name=..., scheme_name=None, description=None, auto_error=True)：name 分别对应查询参数名、请求头名、Cookie 名；依赖结果是对应位置的 key 字符串。
• HTTPBearer(bearerFormat=None, scheme_name=None, description=None, auto_error=True)：要求 Authorization: Bearer <token>；依赖结果是 HTTPAuthorizationCredentials。
• HTTPBasic(scheme_name=None, realm=None, description=None, auto_error=True)：内部对 Base64 编码的凭证做 username:password 解析（见 http.py），依赖结果是 HTTPBasicCredentials(username, password)。
• OAuth2PasswordBearer(tokenUrl, scheme_name=None, scopes=None, description=None, auto_error=True, refreshUrl=None)：tokenUrl 指向负责签发 token 的路径操作；该安全方案会写入 OpenAPI 的 oauth2/password flow。
• OAuth2PasswordRequestForm：一个依赖类，专门按 OAuth2 规范用表单数据收集 username、password（可选 grant_type、scope、client_id、client_secret）；其中 scope 是一个用空格分隔的字符串，会被自动 split() 成多个 scope（如 "items:read items:write"）。若希望强制 grant_type 必须为 "password"，可改用严格版 OAuth2PasswordRequestFormStrict。实现细节见 oauth2.py。
• SecurityScopes：可在依赖参数中声明，用于一次性取得整条依赖链上所有安全依赖累计要求的 scope 列表（对应进阶主题 OAuth2 Scopes）。

从概念到实践：后续章节怎么读

本页的意义在于为读者建立"规范 → 工具 → 应用"的三层心智模型。真正动手时，建议按下面的路径逐个攻破：

1. First Steps：先跑通一个受保护接口 —— 使用 OAuth2PasswordBearer 作为依赖，观察请求无 token 时被自动 401 拒绝，以及 /docs 出现 Authorize 按钮的过程。这一步能直观看到"声明安全方案"如何通过 OpenAPI 传导到交互式文档。
2. Get Current User：把 token 变成用户 —— 编写依赖读取 token、加载用户，再通过依赖注入把当前用户传递到路径操作里。
3. Simple OAuth2：完整实现用户名/密码登录换 token —— 用 OAuth2PasswordRequestForm 收集表单、校验用户、签发不透明 token，OAuth2PasswordBearer 负责校验后续请求。
4. 进阶：OAuth2 with JWT —— 用签名令牌（JWT）承载用户身份，实现无状态、可验证的跨服务认证（见 docs/en/docs/tutorial/security/oauth2-jwt.md）。

如果你想观察这些功能的行为边界，仓库 tests 下有大量对应的测试可作参考，例如 test_security_api_key_query.py、test_security_http_bearer.py、test_security_oauth2.py 等，它们覆盖了"凭证缺失 / 凭证错误 / 可选认证"等各类分支；教程源码示例集中在 docs_src 下对应章节目录（如 security），可用于对照阅读。

小结

安全认证领域的术语向来容易让人却步，但本质可以浓缩成一句话：OAuth2 管"授权"，OpenID Connect 在 OAuth2 之上补"认证"，OpenAPI 把这些方案标准化为可声明的 security scheme，而 FastAPI 用 fastapi.security 把它们变成可直接 Depends 的依赖。理清这条主线后，无论是自建用户体系（password flow + JWT），还是对接第三方登录平台，你都能在统一的心智模型下快速落地，且全程自动获得交互式文档与标准工具链的支持。