FastAPI与Swagger UI集成OAuth2认证：提升API测试效率

本教程详细阐述了如何在FastAPI应用中，为Swagger UI集成OAuth2授权码流认证。通过引入`OAuth2AuthorizationCodeBearer`并将其作为依赖注入，开发者可以实现直接在Swagger界面内进行用户认证，从而简化API的测试流程。文章将涵盖核心配置、与现有认证机制的结合考虑，以及在使用过程中可能遇到的挑战与注意事项，旨在提升开发效率和用户体验。

在现代API开发中，Swagger UI（或OpenAPI UI）为开发者提供了一个直观、交互式的接口文档和测试平台。然而，当API需要认证时，手动获取和管理认证令牌（如Firebase ID Token）并将其粘贴到Swagger UI中进行测试，会显著降低开发效率。本文旨在指导您如何在FastAPI应用中集成OAuth2授权码流，使得用户可以直接在Swagger UI界面内完成认证，从而无缝测试受保护的API端点。

现有认证机制的挑战

在许多FastAPI应用中，开发者可能会实现一个自定义的HTTP中间件来处理认证逻辑。例如，对于使用Firebase认证的场景，一个典型的中间件可能会拦截所有请求，从请求头中提取Authorization令牌，并使用Firebase Admin SDK验证其有效性。

from starlette.middleware.base import BaseHTTPMiddleware
from starlette.requests import Request
from starlette.responses import JSONResponse
from fastapi import HTTPException
from typing import Callable
import time
# from firebase_admin import auth # 假设已初始化Firebase Admin SDK

class AuthenticationMiddleware(BaseHTTPMiddleware):
    """用于使用Firebase Auth验证请求的中间件。"""

    async def dispatch(self, request: Request, call_next: Callable):
        path = request.url.path
        # 排除特定路径，例如健康检查、登录、文档页面
        if path in ["/health", "/auth/login", "/docs", "/openapi.json"]:
            return await call_next(request)

        headers = request.headers
        token = headers.get("Authorization")

        if not token:
            raise HTTPException(status_code=401, detail="Authorization token is missing")

        try:
            # 假设令牌格式为 "Bearer "
            scheme, credentials = token.split()
            if scheme.lower() != 'bearer':
                raise HTTPException(status_code=401, detail="Invalid authorization scheme")

            # 实际应用中，此处应调用Firebase Admin SDK验证ID Token
            # user_info = auth.verify_id_token(credentials)
            # if user_info.get("exp") < time.time():
            #     raise HTTPException(status_code=401, detail="Token expired")

            # 简化示例：假设令牌验证成功，并获取到用户信息
            user_info = {"uid": "test_user_id", "email": "test@example.com", "exp": time.time() + 3600} # 模拟有效令牌
            request.state.user = user_info
            return await call_next(request)

        except Exception as err:
            # print(f"Authentication error: {err}") # 生产环境应记录日志
            raise HTTPException(status_code=401, detail="Invalid token") from err

虽然这种中间件能有效保护API端点，但对于Swagger UI而言，它无法自动处理OAuth2授权流程来获取和设置Authorization头。每次测试都需要用户手动通过其他方式（如Postman或Firebase SDK）获取令牌，然后复制粘贴到Swagger UI的授权框中，这无疑增加了测试的复杂性。

FastAPI中集成OAuth2授权码流

FastAPI通过其内置的fastapi.security模块，提供了对多种安全方案的便捷支持，包括OAuth2。我们可以利用OAuth2AuthorizationCodeBearer来实现Swagger UI的OAuth2登录集成。

1. 配置OAuth2授权码流

首先，我们需要导入必要的模块并实例化OAuth2AuthorizationCodeBearer。这个类需要OAuth2提供商的授权URL、令牌URL和所需的作用域（scopes）。

from fastapi import FastAPI, Depends, HTTPException, Security
from fastapi.security import OAuth2AuthorizationCodeBearer, HTTPAuthorizationCredentials
import time

app = FastAPI()

# 配置OAuth2授权码流
# 注意：这里以Google OAuth2端点作为示例，因为Firebase认证通常会与Google账户关联。
# 您需要根据实际的OAuth2提供商和您的Firebase项目配置进行调整。
oauth2_scheme = OAuth2AuthorizationCodeBearer(
    authorizationUrl="https://accounts.google.com/o/oauth2/v2/auth", # OAuth2提供商的授权端点
    tokenUrl="https://oauth2.googleapis.com/token", # OAuth2提供商的令牌端点
    scopes={"openid": "获取用户OpenID", "email": "获取用户邮箱地址"}, # 定义请求的作用域
    # refreshUrl="https://oauth2.googleapis.com/token" # 可选，用于令牌刷新
)

# ... (您的AuthenticationMiddleware定义，如果需要继续使用) ...
# app.add_middleware(AuthenticationMiddleware)

关键参数说明：

authorizationUrl: 用户将被重定向到此URL进行身份验证和授权。
tokenUrl: 应用程序将向此URL发送授权码以交换访问令牌。
scopes: 定义了应用程序请求用户授权的权限范围。

2. 创建认证依赖函数

接下来，我们创建一个异步函数作为FastAPI的依赖项。这个函数将使用Security装饰器来注入OAuth2AuthorizationCodeBearer实例，从而在API路由中强制执行OAuth2认证。

# 认证依赖函数
async def get_current_user_token(
    credentials: HTTPAuthorizationCredentials = Security(oauth2_scheme),
) -> str:
    """
    此依赖项将从请求头中提取Bearer令牌。
    在实际应用中，您应在此处验证此令牌的有效性，
    例如，如果令牌是Firebase ID Token，则使用Firebase Admin SDK进行验证。
    """
    token = credentials.credentials # 这是实际的Bearer令牌

    try:
        # 示例：验证令牌（如果它是Firebase ID Token）
        # from firebase_admin import auth
        # decoded_token = auth.verify_id_token(token)
        # if decoded_token.get("exp") < time.time():
        #     raise HTTPException(status_code=401, detail="Token expired")
        # request.state.user = decoded_token # 将解码后的用户信息存储在请求状态中

        # 为简化教程，此处仅返回令牌，实际应用中需进行严格验证
        print(f"Received token: {token}")
        return token
    except Exception as e:
        raise HTTPException(status_code=401, detail=f"Invalid authentication credentials: {e}")

在这个get_current_user_token函数中，credentials.credentials将包含从Swagger UI或客户端发送过来的实际访问令牌。您可以在这里集成您的Firebase Admin SDK逻辑来验证这个令牌（如果它是一个Firebase ID Token）。

3. 在API路由中使用认证依赖

将get_current_user_token依赖添加到您的受保护API路由中，FastAPI将自动处理认证流程。

@app.get("/protected-resource", summary="获取受保护的资源")
async def read_protected_resource(current_token: str = Depends(get_current_user_token)):
    """
    这是一个受OAuth2保护的API端点。
    只有通过认证的用户才能访问。
    """
    return {"message": "您已成功访问受保护的资源！", "your_token": current_token}

@app.get("/public-resource", summary="获取公开资源")
async def read_public_resource():
    """
    这是一个公开的API端点，无需认证即可访问。
    """
    return {"message": "这是一个公开的资源。"}

当您运行FastAPI应用并访问/docs（Swagger UI）时，您会看到一个新的“Authorize”按钮。点击它，会弹出一个OAuth2配置框，其中包含您在OAuth2AuthorizationCodeBearer中配置的authorizationUrl、tokenUrl和scopes。用户可以通过这个界面进行OAuth2登录，获取到令牌后，Swagger UI会自动将其添加到后续请求的Authorization头中。

与Firebase认证的结合点

虽然上述OAuth2AuthorizationCodeBearer的配置直接指向了一个OAuth2服务提供商（如Google），但它与Firebase认证是兼容的。通常，Firebase项目会配置为允许用户通过Google、Facebook等OAuth2提供商进行登录。当用户通过Google OAuth2流程登录并授权后，您会获得一个ID Token。这个ID Token就是Firebase Admin SDK可以验证的凭据。

因此，在get_current_user_token依赖函数中，当credentials.credentials（即访问令牌）被接收后，您可以：

如果令牌是Firebase ID Token： 直接使用firebase_admin.auth.verify_id_token(token)来验证。
如果令牌是OAuth2提供商的Access Token： 您可能需要先用这个Access Token去调用OAuth2提供商的用户信息API，获取用户身份信息，然后根据这些信息在Firebase中创建或查找用户，并生成一个自定义的Firebase Token，或者直接将OAuth2提供商的用户ID映射到您的Firebase用户。

提升中间件的集成度

为了更好地管理认证用户的状态，特别是当您希望在整个请求生命周期中访问request.user对象时，可以考虑将您的自定义认证中间件继承自starlette.middleware.authentication.AuthenticationMiddleware。这允许您定义一个AuthenticationBackend，它能更优雅地处理用户认证和用户对象的创建。

from starlette.middleware.authentication import AuthenticationMiddleware, SimpleUser, AuthCredentials
from starlette.authentication import BaseUser, UnauthenticatedUser
from starlette.requests import Request
from starlette.responses import PlainTextResponse
from starlette.types import ASGIApp
# from firebase_admin import auth # 假设已初始化Firebase Admin SDK

class AuthenticatedUser(SimpleUser):
    """自定义用户类，可以存储更多用户信息，如Firebase UID、email等。"""
    def __init__(self, uid: str, email: str, display_name: str = None):
        super().__init__(display_name or email) # 使用email作为名称，如果display_name不存在
        self.uid = uid
        self.email = email

class FirebaseAuthenticationBackend:
    async def authenticate(self, conn: Request):
        if "Authorization" not in conn.headers:
            return

        auth_header = conn.headers["Authorization"]
        try:
            scheme, credentials = auth_header.split()
            if scheme.lower() == 'bearer':
                # 实际应用中，这里应调用Firebase Admin SDK验证credentials
                # decoded_token = auth.verify_id_token(credentials)
                # return AuthCredentials(["authenticated"]), AuthenticatedUser(
                #     uid=decoded_token['uid'],
                #     email=decoded_token['email'],
                #     display_name=decoded_token.get('name')
                # )

                # 简化示例：假设令牌验证成功，并模拟用户信息
                mock_uid = f"user_{credentials[:5]}" # 从令牌前缀生成模拟UID
                mock_email = f"{mock_uid}@example.com"
                return AuthCredentials(["authenticated"]), AuthenticatedUser(uid=mock_uid, email=mock_email)
        except ValueError:
            pass # 令牌格式不正确
        except Exception as e:
            # print(f"Firebase authentication failed: {e}") # 记录日志
            pass # 令牌验证失败

        return # 认证失败

# app = FastAPI() # 假设已创建FastAPI实例
# app.add_middleware(AuthenticationMiddleware, backend=FirebaseAuthenticationBackend())

# 之后，在任何路由中都可以通过 request.user 访问认证用户
# @app.get("/whoami")
# async def who_am_i(request: Request):
#     if request.user.is_authenticated:
#         return {"uid": request.user.uid, "email": request.user.email}
#     return {"message": "Not authenticated"}

通过这种方式，您可以将OAuth2流程获取到的令牌与您的后端认证逻辑（包括Firebase）更好地整合，并在整个应用中以统一的方式访问用户数据。

注意事项与局限性

客户端ID和密钥配置：
- OAuth2AuthorizationCodeBearer主要用于定义Swagger UI如何与OAuth2提供商交互。Swagger UI本身会处理client_id和client_secret的配置，这些通常在OAuth2提供商（如Google Cloud Console）中为您的Web应用程序注册时获得。
- 在FastAPI代码中，您不需要直接在OAuth2AuthorizationCodeBearer的构造函数中指定client_id和client_secret。它们将由Swagger UI在前端处理，并通过重定向和授权码流传递给OAuth2提供商。
Token刷新问题：
- Swagger UI在OAuth2授权码流的Token刷新机制上可能存在一些局限性。这意味着长时间测试时，已获取的访问令牌可能会过期，导致需要重新进行认证。社区中关于此问题的讨论（如Swagger UI GitHub issue #7257）仍在进行中。
安全性：
- 确保您的OAuth2回调URL（redirect_uri）在OAuth2提供商处配置正确且安全，以防止重定向攻击。
- 在生产环境中，始终对所有传入的令牌进行严格的后端验证。

总结

通过在FastAPI中集成OAuth2AuthorizationCodeBearer，您可以极大地提升Swagger UI的可用性，使开发者能够直接在API文档界面中完成OAuth2认证并测试受保护的API端点。这不仅简化了开发和测试流程，也提供了一个更专业的API交互体验。虽然存在一些如Token刷新机制的局限性，但通过合理的配置和后端验证，OAuth2集成仍然是增强FastAPI应用安全性和开发效率的强大工具。结合Starlette的AuthenticationMiddleware，您还可以构建一个更加健壮和可维护的认证系统。

# js # 前端 # git # json # go # github # app # facebook # access # 工具 # 后端 # ai # 路由 # 中间件 # postman # fastapi # 构造函数 # Token # 继承 # 接口 # console # 对象 # 作用域 # 异步 # http # ui # issue

返回目录在线咨询

上一篇：jquery实现放大镜简洁代码(推荐)
下一篇：上海建站公司：专业打造您的线*户

您的项目需求

*请认真填写需求信息，我们会在24小时内与您取得联系。

全网整合营销服务商