FastAPI 安全入门：读懂 OAuth2、OpenID Connect 与 OpenAPI 安全方案
【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi
导读
Web API 的 security、authentication 与 authorization 常常被视为"困难"主题——在不少框架与系统中，仅实现安全与认证就要花费总代码量的一半甚至更多。本篇基于 FastAPI 官方文档的安全章节（对应仓库 docs/hi/docs/tutorial/security/index.md，英文原文见 docs/en/docs/tutorial/security/index.md），为你梳理进入 FastAPI 安全世界前必须先搞清的核心概念：OAuth2 / OAuth 1、OpenID Connect / OpenID，以及支撑 FastAPI 一切自动化的 OpenAPI 安全方案（security schemes），并结合 fastapi/security 源码说明这些规范在 FastAPI 中的落地形态。读完你将具备完整的"概念地图"，可无缝衔接到后续的 OAuth2 密码流实战章节。
为什么"安全"是大多数框架的痛点
安全、认证与授权有无数种实现方式，且通常是一个复杂的话题。在许多框架和系统中，仅处理 security 与 authentication 就需要投入大量精力和代码——在很多情况下，这部分代码可能占项目全部代码的50% 甚至更多。
FastAPI 的目标是让你轻松、快速、以标准化方式处理 Security，而不必通读全部安全规范（如 RFC 6749 等）才能动手。这一点源自 FastAPI 的架构选择：它基于 OpenAPI 构建，而安全机制与 OpenAPI 文档系统深度集成，详见后文。
赶时间的读者怎么办
如果你对 OAuth2、OpenID Connect 这些术语本身并不关心，只是想立刻加上基于用户名密码的认证，那么可以直接跳过本节概念，前往下一章：
- 第一步入门示例见 first-steps.md；
- 完整"用户名 + 密码换取 Token"的演练见 simple-oauth2.md 与 oauth2-jwt.md。
OAuth2：现代登录体系背后的公共语言
OAuth2 是一份定义多种认证与授权处理方式的规范（specification）。它覆盖面很广，涵盖大量复杂用例，其中就包括借助"第三方"完成认证——这正是在 Facebook、Google、X (Twitter)、GitHub 等站点上看到的 "login with ..." 按钮底层实际使用的东西。
FastAPI 的后续章节将以 OAuth2 为骨架演示安全接入，因此理解它有四个要点：
- OAuth2 是规范而非实现：它只定义各方如何协作的流程（flows），具体加密、存证等细节交给实现者。
- 它面向"委托授权"设计：OAuth2 假设后端 API 与负责认证用户的服务器可以是相互独立的；不过 FastAPI 后续章节会展示同一个 FastAPI 应用同时承担 API 与认证的简化用法。
- 它不规定通信加密：OAuth2 并不规定如何加密通信，它默认你的应用已经通过HTTPS提供服务。
- 最常用于 API 的形态是 Bearer Token：客户端在
Authorization请求头中携带Bearer <token>（字符串Bearer加空格再加 token 值）。
OAuth 1：已被淘汰的前辈
历史上还曾有过OAuth 1，它与 OAuth2 差异很大且更加复杂——因为它直接规定了通信如何加密。如今 OAuth 1 已不再流行，很少被使用。
提示：关于 HTTPS 的免费搭建，官方文档在deployment（部署）章节介绍了如何借助 Traefik 与 Let's Encrypt 免费配置 HTTPS，可参阅 docs/en/docs/deployment 目录下的相关页面。
OpenID Connect：让 OAuth2 更"互操作"的身份层
OpenID Connect 是基于 OAuth2的另一份规范。它并不推翻 OAuth2，而是只做扩展：把 OAuth2 中相对含糊的部分明确下来，使其更易于互操作。
判断二者关系的小技巧：
- Google login使用 OpenID Connect（其底层仍是 OAuth2）；
- Facebook login并不支持 OpenID Connect，它用的是自己的一套 OAuth2 变体。
注意区分 OpenID 与 OpenID Connect
除了 OpenID Connect，历史上还存在一个名为OpenID的规范。它试图解决与 OpenID Connect 相同的问题，但不是建立在 OAuth2 之上，因此是一套完全独立的额外体系。如今 OpenID 同样已不流行、很少被使用。
OpenAPI：FastAPI 安全体系的"地基"
OpenAPI（旧称 Swagger，现为 Linux Foundation 旗下项目）是用于构建 API 的开放规范。FastAPI 整个构建在 OpenAPI 之上——这正是它能自动生成交互式 API 文档、代码生成等能力的原因。
对安全而言，OpenAPI 的价值在于：它定义了声明多种安全 "schemes"（方案）的标准方式。只要你的接口按这些 scheme 声明安全要求，所有基于标准的工具（包括交互式文档系统）都能直接理解，无需任何额外适配。
OpenAPI 定义的 security schemes 可归纳为四类：
| Scheme | 含义 | 关键形态 |
|---|---|---|
apiKey | 应用专属的 key | 可来自query parameter、header或cookie之一 |
http | 标准 HTTP 认证体系 | bearer（Authorization: Bearer <token>，继承自 OAuth2）、HTTP Basic、HTTP Digest 等 |
oauth2 | OAuth2 的全部处理方式（即 "flows"） | implicit、clientCredentials、authorizationCode（适合构建 Google/Facebook/GitHub 这类认证提供商）；以及password（适合在同一应用内直接处理认证） |
openIdConnect | 自动发现 OAuth2 认证数据的方式 | 该自动发现机制正是 OpenID Connect 规范所定义的 |
关于oauth2需要特别指出：其中implicit、clientCredentials、authorizationCode等流程更适合用于构建一个 OAuth 2.0 认证提供商；而password流程则可以被完美地用于在同一应用内直接处理认证——后续章节的示例（first-steps.md、simple-oauth2.md）正是围绕password流程展开的。
提示：接入 Google、Facebook、X (Twitter)、GitHub 等第三方认证/授权提供商是可行且相对容易的。真正最复杂的问题是"像它们一样去构建一个认证提供商"，而 FastAPI 提供工具帮你完成这种 heavy lifting。
FastAPI 安全工具：规范到可调用依赖的桥
概念之外，FastAPI 在这些 scheme 之上提供了一套开箱即用的工具模块fastapi.security。从仓库源码 fastapi/security/init.py 可以看到它对外导出的完整工具集，几乎一一对应上文的每种 scheme：
- apiKey 一族：
APIKeyHeader、APIKeyQuery、APIKeyCookie（见 fastapi/security/api_key.py）； - http 一族：
HTTPBasic、HTTPBearer、HTTPDigest，以及承载凭证的数据类HTTPBasicCredentials、HTTPAuthorizationCredentials（见 fastapi/security/http.py）； - oauth2 一族：
OAuth2PasswordBearer、OAuth2AuthorizationCodeBearer、表单依赖OAuth2PasswordRequestForm/OAuth2PasswordRequestFormStrict、SecurityScopes等（见 fastapi/security/oauth2.py）； - openIdConnect：
OpenIdConnect（见 fastapi/security/open_id_connect_url.py）。
它们为何能被 OpenAPI 自动识别
这些安全工具之所以能无缝进入 OpenAPI 与交互式文档，关键在类继承体系。以最常用的OAuth2PasswordBearer为例，其源码位于 fastapi/security/oauth2.py：
- OAuth2PasswordBearer 继承自 OAuth2；
OAuth2继承自 SecurityBase；SecurityBase定义了model: SecurityBaseModel与scheme_name两个属性，作为与 OpenAPI 模型对接的最小接口。
所有需要与 OpenAPI（以及自动 API 文档）集成的安全工具都会继承SecurityBase——FastAPI 正是据此识别"这是一个安全 scheme"并将其写入 OpenAPI。在 fastapi/openapi/utils.py 的_get_openapi_security_definitions函数中可以看到实际转化逻辑：FastAPI 收集依赖中的安全方案，用jsonable_encoder(security_scheme.model, by_alias=True, exclude_none=True)把模型序列化为 OpenAPI 定义，并以scheme_name作为去重与合并 key（同一 scheme 的 OAuth2 scopes 会被合并进同一条security条目）。
在依赖注入中使用
fastapi.security中的类实例同时也是"可调用对象"，因而可以直接配合Depends()使用。例如后续章节会演示的OAuth2PasswordBearer：
from fastapi.security import OAuth2PasswordBearer oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token") async def read_items(token: str = Depends(oauth2_scheme)): ...这里tokenUrl只是声明客户端将来获取 token 所用的 URL（用于 OpenAPI 与文档 UI），并不会自动创建该端点；真实的/token路径操作仍需你自己实现。若请求缺少Authorization头或值不是Bearer <token>，该依赖会直接返回401 UNAUTHORIZED——你甚至无需在业务代码里再检查 token 是否为空（详见 first-steps.md 中OAuth2PasswordBearer一节的展开）。
章节导览：概念之后怎么走
本页是安全教程的总览/索引，确认概念后再按如下顺序深入，即可在数行代码内获得初步可用的安全能力：
- Security - First Steps：用
OAuth2PasswordBearer在 3～4 行内搭建最原始的认证骨架，并观察/docs交互界面自动出现的 Authorize 按钮与小锁图标； - Get Current User：从 token 还原当前用户；
- Simple OAuth2 with Password and Bearer：真正实现
passwordflow，校验用户名密码并签发 token； - OAuth2 with JWT：引入 JWT 让 token 携带可校验的用户信息与过期时间，构成生产可用方案。
相关源码示例位于 docs_src/security 目录（如tutorial001_an_py310.py），仓库还提供了大量对应测试，例如 tests/test_security_oauth2.py、tests/test_security_http_bearer.py 等，可作为验证实现行为的参考。
小结
一句话回顾本文主线：安全规范（OAuth2、OpenID Connect）负责"定协议"，OpenAPI 负责"标准化声明"，而fastapi.security把两者折叠成可注入的 Python 依赖——这正是 FastAPI 能让安全从"50% 代码量的难题"变成"几行声明式代码"的根本原因。现在，你可以带着这份概念地图进入 first-steps.md，亲手跑通第一个带 Authorize 按钮的安全接口了。
【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
