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 与 Lets Encrypt 免费配置 HTTPS可参阅 docs/en/docs/deployment 目录下的相关页面。OpenID Connect让 OAuth2 更互操作的身份层OpenID Connect 是基于 OAuth2的另一份规范。它并不推翻 OAuth2而是只做扩展把 OAuth2 中相对含糊的部分明确下来使其更易于互操作。判断二者关系的小技巧Google login使用 OpenID Connect其底层仍是 OAuth2Facebook login并不支持 OpenID Connect它用的是自己的一套 OAuth2 变体。注意区分 OpenID 与 OpenID Connect除了 OpenID Connect历史上还存在一个名为OpenID的规范。它试图解决与 OpenID Connect 相同的问题但不是建立在 OAuth2 之上因此是一套完全独立的额外体系。如今 OpenID 同样已不流行、很少被使用。OpenAPIFastAPI 安全体系的地基OpenAPI旧称 Swagger现为 Linux Foundation 旗下项目是用于构建 API 的开放规范。FastAPI 整个构建在 OpenAPI 之上——这正是它能自动生成交互式 API 文档、代码生成等能力的原因。对安全而言OpenAPI 的价值在于它定义了声明多种安全 schemes方案的标准方式。只要你的接口按这些 scheme 声明安全要求所有基于标准的工具包括交互式文档系统都能直接理解无需任何额外适配。OpenAPI 定义的 security schemes 可归纳为四类Scheme含义关键形态apiKey应用专属的 key可来自query parameter、header或cookie之一http标准 HTTP 认证体系bearerAuthorization: Bearer token继承自 OAuth2、HTTP Basic、HTTP Digest 等oauth2OAuth2 的全部处理方式即 flowsimplicit、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 可以看到它对外导出的完整工具集几乎一一对应上文的每种 schemeapiKey 一族APIKeyHeader、APIKeyQuery、APIKeyCookie见 fastapi/security/api_key.pyhttp 一族HTTPBasic、HTTPBearer、HTTPDigest以及承载凭证的数据类HTTPBasicCredentials、HTTPAuthorizationCredentials见 fastapi/security/http.pyoauth2 一族OAuth2PasswordBearer、OAuth2AuthorizationCodeBearer、表单依赖OAuth2PasswordRequestForm/OAuth2PasswordRequestFormStrict、SecurityScopes等见 fastapi/security/oauth2.pyopenIdConnectOpenIdConnect见 fastapi/security/open_id_connect_url.py。它们为何能被 OpenAPI 自动识别这些安全工具之所以能无缝进入 OpenAPI 与交互式文档关键在类继承体系。以最常用的OAuth2PasswordBearer为例其源码位于 fastapi/security/oauth2.pyOAuth2PasswordBearer 继承自 OAuth2OAuth2继承自 SecurityBaseSecurityBase定义了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_aliasTrue, exclude_noneTrue)把模型序列化为 OpenAPI 定义并以scheme_name作为去重与合并 key同一 scheme 的 OAuth2 scopes 会被合并进同一条security条目。在依赖注入中使用fastapi.security中的类实例同时也是可调用对象因而可以直接配合Depends()使用。例如后续章节会演示的OAuth2PasswordBearerfrom fastapi.security import OAuth2PasswordBearer oauth2_scheme OAuth2PasswordBearer(tokenUrltoken) 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在 34 行内搭建最原始的认证骨架并观察/docs交互界面自动出现的 Authorize 按钮与小锁图标Get Current User从 token 还原当前用户Simple OAuth2 with Password and Bearer真正实现passwordflow校验用户名密码并签发 tokenOAuth2 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），仅供参考 FastAPI 安全入门：读懂 OAuth2、OpenID Connect 与 OpenAPI 安全方案
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 与 Lets Encrypt 免费配置 HTTPS可参阅 docs/en/docs/deployment 目录下的相关页面。OpenID Connect让 OAuth2 更互操作的身份层OpenID Connect 是基于 OAuth2的另一份规范。它并不推翻 OAuth2而是只做扩展把 OAuth2 中相对含糊的部分明确下来使其更易于互操作。判断二者关系的小技巧Google login使用 OpenID Connect其底层仍是 OAuth2Facebook login并不支持 OpenID Connect它用的是自己的一套 OAuth2 变体。注意区分 OpenID 与 OpenID Connect除了 OpenID Connect历史上还存在一个名为OpenID的规范。它试图解决与 OpenID Connect 相同的问题但不是建立在 OAuth2 之上因此是一套完全独立的额外体系。如今 OpenID 同样已不流行、很少被使用。OpenAPIFastAPI 安全体系的地基OpenAPI旧称 Swagger现为 Linux Foundation 旗下项目是用于构建 API 的开放规范。FastAPI 整个构建在 OpenAPI 之上——这正是它能自动生成交互式 API 文档、代码生成等能力的原因。对安全而言OpenAPI 的价值在于它定义了声明多种安全 schemes方案的标准方式。只要你的接口按这些 scheme 声明安全要求所有基于标准的工具包括交互式文档系统都能直接理解无需任何额外适配。OpenAPI 定义的 security schemes 可归纳为四类Scheme含义关键形态apiKey应用专属的 key可来自query parameter、header或cookie之一http标准 HTTP 认证体系bearerAuthorization: Bearer token继承自 OAuth2、HTTP Basic、HTTP Digest 等oauth2OAuth2 的全部处理方式即 flowsimplicit、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 可以看到它对外导出的完整工具集几乎一一对应上文的每种 schemeapiKey 一族APIKeyHeader、APIKeyQuery、APIKeyCookie见 fastapi/security/api_key.pyhttp 一族HTTPBasic、HTTPBearer、HTTPDigest以及承载凭证的数据类HTTPBasicCredentials、HTTPAuthorizationCredentials见 fastapi/security/http.pyoauth2 一族OAuth2PasswordBearer、OAuth2AuthorizationCodeBearer、表单依赖OAuth2PasswordRequestForm/OAuth2PasswordRequestFormStrict、SecurityScopes等见 fastapi/security/oauth2.pyopenIdConnectOpenIdConnect见 fastapi/security/open_id_connect_url.py。它们为何能被 OpenAPI 自动识别这些安全工具之所以能无缝进入 OpenAPI 与交互式文档关键在类继承体系。以最常用的OAuth2PasswordBearer为例其源码位于 fastapi/security/oauth2.pyOAuth2PasswordBearer 继承自 OAuth2OAuth2继承自 SecurityBaseSecurityBase定义了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_aliasTrue, exclude_noneTrue)把模型序列化为 OpenAPI 定义并以scheme_name作为去重与合并 key同一 scheme 的 OAuth2 scopes 会被合并进同一条security条目。在依赖注入中使用fastapi.security中的类实例同时也是可调用对象因而可以直接配合Depends()使用。例如后续章节会演示的OAuth2PasswordBearerfrom fastapi.security import OAuth2PasswordBearer oauth2_scheme OAuth2PasswordBearer(tokenUrltoken) 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在 34 行内搭建最原始的认证骨架并观察/docs交互界面自动出现的 Authorize 按钮与小锁图标Get Current User从 token 还原当前用户Simple OAuth2 with Password and Bearer真正实现passwordflow校验用户名密码并签发 tokenOAuth2 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），仅供参考