当前位置:

首页 > 编程开发 > FastAPI多认证方案:支持Basic与JWT验证

FastAPI多认证方案:支持Basic与JWT验证

本文详细阐述如何在FastAPI中实现灵活的多重认证机制,允许客户端通过BasicAuth或JWTBearerToken中的任意一种方式访问受保护的API端点。核心策略是将各个认证依赖项配置为在认证失败时不立即抛出异常,而是返回None,从而将最终的授权决策和错误处理集中到一个高级组合依赖中。

本文目录

    FastAPI实现多重可选认证:同时支持Basic Auth与JWT Auth

    本文详细阐述如何在FastAPI中实现灵活的多重认证机制,允许客户端通过Basic Auth或JWT Bearer Token中的任意一种方式访问受保护的API端点。核心策略是将各个认证依赖项配置为在认证失败时不立即抛出异常,而是返回None,从而将最终的授权决策和错误处理集中到一个高级组合依赖中。

    在构建现代Web API时,常常需要支持多种认证方式以适应不同的客户端或使用场景。例如,某些内部服务可能使用Basic Auth,而外部客户端则可能依赖JWT。FastAPI的依赖注入系统非常强大,但默认情况下,当一个端点声明了多个认证依赖时,FastAPI会尝试强制所有依赖都成功。这导致了一个常见问题:如何让端点支持“或”逻辑,即只要任意一种认证方式成功即可访问?

    本文将通过一个具体的示例,演示如何改造FastAPI的认证依赖,使其能够灵活地支持Basic Auth或JWT Auth的任选模式。

    1. 核心理念:非阻塞式认证依赖

    解决此问题的关键在于,让单个的认证依赖项在认证失败时不再立即抛出HTTPException,而是返回一个指示失败的值(通常是None)。这样,上层组合依赖就可以根据这些返回值来判断最终的认证状态。

    对于FastAPI内置的认证方案,如HTTPBasic和OAuth2PasswordBearer,可以通过设置auto_error=False来实现这一目标。

    2. 实现非阻塞式 Basic Authentication

    首先,我们需要修改HTTPBasic实例,使其在缺少或无效的Basic Auth头时不会自动抛出401错误。

    from fastapi.security import HTTPBasic, HTTPBasicCredentials
    from fastapi import Depends, HTTPException, status
    from typing import Optional, Annotated
    import secrets # 用于安全地比较字符串
    
    # 假设 settings.SESSION_LOGIN_USER 和 settings.SESSION_LOGIN_PASS 存储了正确的用户名和密码
    # 假设 router 和 db_session 已定义
    # 假设 User 模型已定义
    
    # 1. 初始化 HTTPBasic,设置 auto_error=False
    security = HTTPBasic(auto_error=False)
    
    # 2. 创建 Basic Auth 依赖函数
    def basic_logged_user(credentials: Annotated[Optional[HTTPBasicCredentials], Depends(security)]):
        """
        Basic Auth 认证依赖。
        如果认证失败,不抛出异常,而是返回 None。
        """
        if credentials is None:
            # 没有提供 Basic Auth 凭据
            return None
    
        # 安全地比较用户名和密码
        current_username_bytes = credentials.username.encode("utf8")
        correct_username_bytes = settings.SESSION_LOGIN_USER.encode("utf8")
        is_correct_username = secrets.compare_digest(current_username_bytes, correct_username_bytes)
    
        current_password_bytes = credentials.password.encode("utf8")
        correct_password_bytes = settings.SESSION_LOGIN_PASS.encode("utf8")
        is_correct_password = secrets.compare_digest(current_password_bytes, correct_password_bytes)
    
        if not (is_correct_username and is_correct_password):
            # 凭据无效,返回 None
            return None
    
        # 认证成功,返回用户名
        return credentials.username

    在这个basic_logged_user函数中:

    • Depends(security)会尝试解析Basic Auth凭据。由于auto_error=False,如果凭据缺失,credentials将为None。
    • 我们显式地将credentials声明为Optional[HTTPBasicCredentials],以处理None的情况。
    • 无论凭据缺失还是无效,函数都返回None,而不是抛出HTTPException。

    3. 实现非阻塞式 JWT Authentication

    类似地,我们需要对JWT认证方案进行调整。通常,JWT认证会使用OAuth2PasswordBearer。我们也需要将其初始化为auto_error=False。

    from fastapi.security import OAuth2PasswordBearer
    # ... 其他导入 ...
    # 假设 utils.verify_token 是一个验证JWT并返回用户数据的函数
    # 假设 db_session 和 User 模型已定义
    
    # 1. 初始化 OAuth2PasswordBearer,设置 auto_error=False
    oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token", auto_error=False) # tokenUrl 根据你的实际情况设置
    
    # 2. 创建 JWT Auth 依赖函数
    def jwt_logged_user(token: Annotated[Optional[str], Depends(oauth2_scheme)], 
                        db: Session = Depends(db_session)):
        """
        JWT Auth 认证依赖。
        如果认证失败,不抛出异常,而是返回 None。
        """
        if token is None:
            # 没有提供 JWT token
            return None
    
        try:
            # 假设 utils.verify_token 会验证 token 并返回一个包含用户信息的对象
            # 如果 token 无效,utils.verify_token 内部应该捕获异常或返回 None
            # 这里我们假设它在验证失败时会抛出异常,我们捕获它
            payload = utils.verify_token(token) # 假设 verify_token 成功返回 payload,失败抛异常
            username = payload.get("sub") # 假设 sub 字段存储用户名
            if not username:
                return None
    
            user = db.query(User).filter(User.username == username).first()
            if not user:
                return None
    
            return user # 认证成功,返回用户对象
        except Exception:
            # token 验证失败(过期、无效签名等)
            return None

    在这个jwt_logged_user函数中:

    • Depends(oauth2_scheme)会尝试从请求头中提取JWT token。由于auto_error=False,如果token缺失,token参数将为None。
    • 我们同样将token声明为Optional[str]。
    • utils.verify_token应该被设计为在验证失败时抛出异常或返回一个可识别的失败状态。这里我们用try-except块来捕获验证失败的情况,并返回None。

    4. 创建组合认证依赖 (auth_user)

    现在我们有了两个非阻塞式的认证依赖,可以创建一个新的依赖函数来组合它们,实现“或”逻辑。

    from fastapi import HTTPException, status
    # ... 其他导入 ...
    
    def auth_user(jwt_auth_result: Annotated[Optional[User], Depends(jwt_logged_user)], 
                  basic_auth_result: Annotated[Optional[str], Depends(basic_logged_user)]):
        """
        组合认证依赖,支持 Basic Auth 或 JWT Auth。
        如果任一认证方式成功,则返回相应的认证用户。
        如果两种方式都失败,则抛出 401 异常。
        """
        if jwt_auth_result:
            # JWT 认证成功
            return jwt_auth_result
    
        if basic_auth_result:
            # Basic Auth 认证成功
            # 注意:这里返回的类型需要与 jwt_auth_result 的类型保持一致,
            # 或者根据你的业务逻辑决定返回哪个。
            # 为了简化,这里假设可以返回一个字符串作为认证成功的标识。
            # 如果需要返回统一的用户对象,则需要从 basic_auth_result 中获取用户对象。
            return basic_auth_result
    
        # 两种认证方式都失败,抛出 401 未授权异常
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, 
            detail='Invalid Credentials',
            headers={"WWW-Authenticate": "Bearer, Basic"} # 提示客户端支持的认证方式
        )

    在这个auth_user函数中:

    • 它接收jwt_logged_user和basic_logged_user的返回值。
    • 如果jwt_auth_result不为None(即JWT认证成功),则直接返回该结果。
    • 否则,如果basic_auth_result不为None(即Basic Auth认证成功),则返回该结果。
    • 只有当两种认证方式都返回None时,才抛出HTTP_401_UNAUTHORIZED异常。

    5. 在API端点中使用组合认证

    最后,将auth_user依赖添加到你的API端点中。

    from fastapi import APIRouter, Depends
    from sqlalchemy.orm import Session
    # ... 其他导入 ...
    
    router = APIRouter() # 假设你有一个 APIRouter 实例
    
    @router.get("/users")
    async def get_users(db: Session = Depends(db_session), 
                        logged_user: Annotated[Union[User, str], Depends(auth_user)]):
        """
        获取用户列表,需要 Basic Auth 或 JWT Auth 认证。
        """
        query_users = db.query(User).all()
        return query_users

    现在,当客户端请求/users端点时:

    • 如果提供了有效的JWT Bearer Token,即使没有提供Basic Auth,请求也会成功。
    • 如果提供了有效的Basic Auth凭据,即使没有提供JWT Token,请求也会成功。
    • 只有当两种认证方式的凭据都缺失或无效时,才会收到401 Unauthorized响应。

    总结与注意事项

    通过将各个认证依赖项配置为非阻塞模式(auto_error=False并返回None),并创建一个中央组合依赖来处理最终的授权逻辑,我们成功地实现了FastAPI中多重可选认证的需求。

    注意事项:

    1. 返回类型统一: 在auth_user中,jwt_auth_result可能返回User对象,而basic_auth_result可能返回str(用户名)。在实际应用中,你可能希望将它们统一为某种形式的用户对象,例如通过用户名从数据库中加载用户对象,确保auth_user始终返回User类型或其接口类型。
    2. 错误信息: 在auth_user抛出HTTPException时,WWW-Authenticate头部应包含所有支持的认证方案,以便客户端知道如何进行认证。
    3. 安全性: 在实现认证逻辑时,务必使用secrets.compare_digest等安全函数来比较密码,以防止定时攻击。
    4. 可扩展性: 这种模式非常灵活,你可以轻松地添加更多可选的认证方案(如API Key认证),只需为每个方案创建非阻塞依赖,并在auth_user中进行组合。

    通过遵循这些原则,你可以构建出既安全又灵活的FastAPI认证系统。

    本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系bd@zhengruan.com
    作者最新文章
    编程开发
    相关文章 更多
    WorkBuddy怎么用API接口?有开发文档吗
    WorkBuddy怎么用API接口?有开发文档吗

    WorkBuddy 目前没有面向普通用户的公开 REST API 接口文档,扩展与集成走四条官方路径:接入 MCP 服务扩展工具能力、用连接器打通外部应用(支持公共/个人授权)、编写技能(Skill)与专家包定制工作流、在开放平台发布 Buddy 应用。另支持接入 OpenAI 兼容的自定义模型。本文含 4 张真实界面截图并如实说明现状。

    Google Workspace MCP OAuth 2.0迁移节点已过,旧客户端、普通REST与服务账户分别适用什么规则
    Google Workspace MCP OAuth 2.0迁移节点已过,旧客户端、普通REST与服务账户分别适用什么规则

    解释Google Workspace MCP 11月11日与12日的agentic OAuth客户端迁移节点,区分普通REST应用、混合客户端、预览资格、用户权限和服务账户、Apps Script边界。

    OpenAI Agents SDK v0.24.0-alpha.8升级前为何要备份状态?
    OpenAI Agents SDK v0.24.0-alpha.8升级前为何要备份状态?

    OpenAI Agents SDK v0.24.0-alpha.8预览版新增执行前审批、自有模型客户端、Realtime与预算检查点恢复,说明alpha.7回退、Linux运行及工具认证边界。

    Claude Trading Skills六项诊断修复覆盖哪些密钥泄漏路径?
    Claude Trading Skills六项诊断修复覆盖哪些密钥泄漏路径?

    Claude Trading Skills六项技能已修复API密钥异常日志泄漏路径;not_verified保留完整安全审核缺口,离线回归通过不等于实盘验收或全面认证。

    Microsoft C++ Language Server内置MSBuild提取器后,自动化范围和使用资格怎样理解
    Microsoft C++ Language Server内置MSBuild提取器后,自动化范围和使用资格怎样理解

    解释Microsoft C++ Language Server预览版的MSBuild编译数据库自动提取,区分CMake、自定义构建、有效Copilot订阅和CLI能力,避免把测试预发布版本当最低稳定版。

    LibreOffice宏怎么用?Python脚本能调用吗
    LibreOffice宏怎么用?Python脚本能调用吗

    LibreOffice可通过“工具→宏”创建和运行Basic宏,也支持由Python脚本提供程序运行Python宏。两种方式都可以使用UNO接口操作文档;Excel VBA只有有限兼容支持,不能把所有Excel宏直接复制过来当作LibreOffice原生宏执行。

    GitHub企业Copilot席位API开放应用调用后,读取和席位变更有什么区别
    GitHub企业Copilot席位API开放应用调用后,读取和席位变更有什么区别

    说明Enterprise GitHub Apps的Copilot席位管理权限,提供第一页只读GET示例,区分total_seats、授权明细、遥测活动和待取消计费条件。

    GitHub网页仪表盘默认视图、单行标题和六项列表分别改变什么
    GitHub网页仪表盘默认视图、单行标题和六项列表分别改变什么

    解释GitHub网页仪表盘Feed或Home默认视图、六项列表、自定义选择保留和Agent sessions隐藏条件,区分布局、数据与权限。

    LangChain Python 1.4.10、JS core 1.3.7与langchain 1.6.4为什么要区分拒答和失败
    LangChain Python 1.4.10、JS core 1.3.7与langchain 1.6.4为什么要区分拒答和失败

    核对LangChain三种包版本,解释refusal内容块、ModelRefusalError与中间件传递,提供自定义错误分支示例并区分Python消息流和追踪修复。

    Anthropic Python/Ruby 2.8.0、TS 1.8.0、Go 2.9.0、Java 3.8.0参数校验应如何理解
    Anthropic Python/Ruby 2.8.0、TS 1.8.0、Go 2.9.0、Java 3.8.0参数校验应如何理解

    区分Anthropic各语言SDK及TypeScript云适配包版本,解释Claude Tag字段、Bedrock/Vertex分号差异、非法路径参数和只读Python版本核对。

    查看更多
    精品专题 更多
    装机必备
    装机必备

    正软商城装机必备专区,精选办公、浏览器、安全防护、影音播放、压缩解压、设计创作和系统工具等电脑常用正版软件,帮助用户快速完成新电脑软件配置。

    Windows
    Windows

    正软商城Windows软件专区,汇集适用于Windows电脑的办公、设计、安全防护、影音播放、开发工具和系统优化软件,提供软件介绍、系统要求、正版授权及购买下载服务。

    PDF教程
    PDF教程

    正软商城PDF教程频道提供PDF编辑、转换、合并、拆分、压缩及格式处理方法,同时介绍常用PDF软件和工具的使用技巧。

    Mac软件 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    Aperty macOS版
    Aperty macOS版
    macOS

    Aperty 是 Skylum 推出的 AI 人像修图软件,支持自然肤质修饰、瑕疵处理、面部与身体调整、预设及批量同步。

    WINDOWS 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    PixTV 网页版
    PixTV 网页版
    Windows

    PixTV 是一款在浏览器中使用的 AI 视觉内容创作平台,提供图片、视频、音频、文字生成、AI 分镜、局部重绘、提示词反推和无限画布等工具,适合短剧、漫剧、广告及社交媒体内容制作。