FastAPI安全工具详解：Tutorial-Codebase-Knowledge项目实战指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00947/article/details/148439916

FastAPI安全工具详解：Tutorial-Codebase-Knowledge项目实战指南

Tutorial-Codebase-Knowledge Turns Codebase into Easy Tutorial with AI 项目地址: https://gitcode.com/gh_mirrors/tu/Tutorial-Codebase-Knowledge

引言：为什么需要API安全机制

在现代Web开发中，API安全是至关重要的环节。无论是简单的个人项目还是企业级应用，都需要确保API端点得到适当保护。FastAPI提供了一套强大而灵活的安全工具，让开发者能够轻松实现各种认证方案。

安全基础概念

认证(Authentication) vs 授权(Authorization)

认证(AuthN)：验证用户身份，回答"你是谁"的问题
授权(AuthZ)：验证用户权限，回答"你能做什么"的问题

常见认证方式

HTTP基本认证：最简单的用户名/密码认证
API密钥：常用于服务间通信
OAuth2：现代Web和移动应用的标准认证协议
JWT(JSON Web Token)：无状态的令牌认证机制

FastAPI安全模块详解

核心组件

安全方案类：定义认证方式
- HTTPBasic：基本认证
- APIKeyHeader/APIKeyQuery/APIKeyCookie：API密钥认证
- OAuth2PasswordBearer：OAuth2密码流程
Security函数：特殊的依赖注入标记
- 自动生成OpenAPI文档中的安全需求
- 在Swagger UI中显示认证选项
凭证模型：封装认证信息
- HTTPBasicCredentials：用户名和密码
- OAuth2PasswordRequestForm：OAuth2密码流程表单

实战示例：HTTP基本认证

实现步骤

导入必要模块

from typing import Annotated
from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials

创建安全方案实例

security = HTTPBasic()

编写验证器函数

def get_current_username(credentials: Annotated[HTTPBasicCredentials, Depends(security)]):
    # 生产环境中绝对不要硬编码凭证！
    correct_username = "stanley"
    correct_password = "password123"
    
    # 验证用户名和密码
    if not (credentials.username == correct_username 
            and credentials.password == correct_password):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="用户名或密码错误",
            headers={"WWW-Authenticate": "Basic"},
        )
    return credentials.username

保护API端点

@app.get("/users/me")
async def read_current_user(
    username: Annotated[str, Security(get_current_username)]
):
    return {"username": username}

安全注意事项

永远不要明文存储密码：使用如passlib等库进行密码哈希
使用HTTPS：基本认证在HTTP中是明文传输的
考虑访问限制：防止未授权访问尝试

API密钥认证实现

头部API密钥方案

from fastapi.security import APIKeyHeader

api_key_header = APIKeyHeader(name="X-API-KEY", auto_error=False)

async def verify_api_key(api_key: Annotated[str | None, Security(api_key_header)]):
    if api_key is None:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="缺少API密钥头部"
        )
    if api_key != "SECRET_API_KEY":
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="无效的API密钥"
        )
    return api_key

@app.get("/secure-data")
async def get_secure_data(
    verified_key: Annotated[str, Security(verify_api_key)]
):
    return {"data": "重要数据", "key": verified_key}

最佳实践

密钥存储：使用环境变量或密钥管理系统
密钥轮换：定期更换API密钥
最小权限原则：为不同密钥分配不同权限

OAuth2密码流程实现

完整实现示例

from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

@app.post("/token")
async def login_for_access_token(
    form_data: Annotated[OAuth2PasswordRequestForm, Depends()]
):
    # 实际项目中应验证数据库中的用户凭证
    if form_data.username != "stanley" or form_data.password != "password123":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="无效的用户名或密码",
            headers={"WWW-Authenticate": "Bearer"},
        )
    
    # 生成访问令牌(JWT)
    access_token = f"token_for_{form_data.username}"
    return {"access_token": access_token, "token_type": "bearer"}

async def get_current_user(token: Annotated[str, Security(oauth2_scheme)]):
    if token != "token_for_stanley":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="无效的认证凭证",
            headers={"WWW-Authenticate": "Bearer"},
        )
    return {"username": "stanley", "email": "stanley@example.com"}

@app.get("/users/me/oauth")
async def read_users_me_oauth(
    current_user: Annotated[dict, Security(get_current_user)]
):
    return current_user