FastAPI HTTP Basic 认证教程

简介

HTTP Basic 认证是一种简单的 HTTP 协议内置认证方式，通过请求头发送用户名和密码（Base64 编码）来验证用户身份。本教程将引导您在 FastAPI 中实现 HTTP Basic 认证，确保您的 API 安全可靠。

前置要求

• 基本 Python 知识
• 安装 FastAPI：pip install fastapi uvicorn

HTTP Basic 认证原理

HTTP Basic 认证的工作原理是：客户端发送请求时，在 Authorization 头中包含 Basic 关键字和 Base64 编码的 username:password 字符串。服务器解码并验证凭据，如果有效则允许访问，否则返回 401 未授权错误。

注意：由于凭据以 Base64 形式传输，容易被拦截解码，因此在实际生产环境中应始终使用 HTTPS（SSL/TLS）来加密连接。

在 FastAPI 中实现 HTTP Basic 认证

步骤 1：导入模块

首先，导入 FastAPI 和相关安全模块。

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

• FastAPI：创建 API 应用的核心类。
• Depends：用于依赖注入，管理认证逻辑。
• HTTPException：处理认证失败时的错误。
• HTTPBasic 和 HTTPBasicCredentials：FastAPI 提供的 HTTP Basic 认证工具。
• secrets：Python 标准库，用于安全比较密码（示例中推荐使用）。

步骤 2：创建 FastAPI 应用实例

app = FastAPI()

步骤 3：设置 HTTPBasic 安全对象

HTTPBasic 对象用于自动解析请求中的凭据。

security = HTTPBasic()

步骤 4：编写认证函数

创建一个函数来处理凭据验证，并作为依赖项注入到路由中。

def get_current_username(credentials: HTTPBasicCredentials = Depends(security)):
    # 示例中硬编码用户名和密码；生产环境请使用数据库或其他安全存储方式
    correct_username = "admin"
    correct_password = "password"
    
    # 安全比较用户名和密码，使用 secrets.compare_digest 防止时序攻击
    if not (secrets.compare_digest(credentials.username, correct_username) and 
            secrets.compare_digest(credentials.password, correct_password)):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="无效的用户名或密码",
            headers={"WWW-Authenticate": "Basic"},
        )
    return credentials.username

• credentials 参数通过 Depends(security) 自动从请求头中提取。
• secrets.compare_digest 确保密码比较过程安全，避免时序攻击。
• 如果认证失败，抛出 HTTPException 并设置 401 状态码和 WWW-Authenticate 头，提示客户端重新认证。

步骤 5：将认证应用到路由

在需要保护的 API 端点中使用 Depends 引入认证函数。

@app.get("/protected/")
async def read_protected_data(username: str = Depends(get_current_username)):
    return {"message": f"欢迎, {username}！您已成功通过认证。", "data": "这是受保护的内容。"}

• 只有当 get_current_username 返回用户名（即认证成功）时，该路由才会执行。

完整代码示例

将以上步骤整合到一个文件中（如 main.py）。

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

app = FastAPI()
security = HTTPBasic()

def get_current_username(credentials: HTTPBasicCredentials = Depends(security)):
    correct_username = "admin"
    correct_password = "password"
    if not (secrets.compare_digest(credentials.username, correct_username) and 
            secrets.compare_digest(credentials.password, correct_password)):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="无效的用户名或密码",
            headers={"WWW-Authenticate": "Basic"},
        )
    return credentials.username

@app.get("/protected/")
async def read_protected_data(username: str = Depends(get_current_username)):
    return {"message": f"欢迎, {username}！您已成功通过认证。", "data": "这是受保护的内容。"}

@app.get("/public/")
async def read_public_data():
    return {"message": "这是一个公开的端点，无需认证。"}

运行和测试

1. 启动服务器：在终端运行 uvicorn main:app --reload。
2. 测试认证：
   • 成功案例：使用工具如 curl 或 Postman 发送 GET 请求到 http://127.0.0.1:8000/protected/，在请求头中添加 Authorization: Basic YWRtaW46cGFzc3dvcmQ=（这是 admin:password 的 Base64 编码）。应返回 JSON 响应。
   • 失败案例：发送无效凭据，服务器将返回 401 错误。
3. 公开端点测试：访问 http://127.0.0.1:8000/public/ 应直接返回数据。

安全注意事项

• 使用 HTTPS：HTTP Basic 认证的凭据以 Base64 编码传输，容易被窃取。在生产环境中，务必启用 HTTPS（例如使用 Let's Encrypt 或云服务提供的 SSL 证书）。
• 密码存储：避免硬编码密码。建议使用哈希算法（如 bcrypt）存储密码，并集成数据库（如 SQLite、PostgreSQL）来管理用户信息。
• 增强安全性：对于更高级的需求，考虑使用 OAuth2 或 JWT（JSON Web Tokens），FastAPI 内置支持这些方案。

SEO 优化建议

• 在您的 FastAPI 项目文档中，使用本教程的 SEO 标题和关键词，以提高搜索引擎可见性。
• 内容中可添加链接到官方 FastAPI 文档和社区资源，提升用户参与度。
• 定期更新教程，反映 FastAPI 最新版本和最佳实践。

总结

通过本教程，您学会了如何在 FastAPI 中实现 HTTP Basic 认证。它简单易用，适合快速原型或内部 API 保护。记住安全第一，始终结合 HTTPS 和其他安全措施。下一步，您可以探索 FastAPI 的 OAuth2 或依赖注入的高级用法。

如果您有任何问题，欢迎参考 FastAPI 官方文档或社区论坛。Happy coding！