title: FastAPI安全认证：从密码到令牌的魔法之旅

date: 2025/06/02 13:24:43
updated: 2025/06/02 13:24:43
author: cmdragon

excerpt:
在FastAPI中实现OAuth2密码流程的认证机制。通过创建令牌端点，用户可以使用用户名和密码获取JWT访问令牌。代码示例展示了如何使用CryptContext进行密码哈希处理，生成和验证JWT令牌，并实现安全路由保护。此外，还提供了JWT令牌的结构解析、常见报错解决方案以及安全增强建议，如使用HTTPS传输令牌和从环境变量读取密钥。最后，通过课后Quiz巩固了关键概念。

categories:

后端开发
FastAPI

tags:

FastAPI
OAuth2
JWT
安全认证
密码哈希
令牌校验
访问控制

扫描二维码
关注或者微信搜一搜：编程智域前端至全栈交流与成长

探索数千个预构建的 AI 应用，开启你的下一个伟大创意：https://tools.cmdragon.cn/

第一章：FastAPI安全认证核心实现

（注：根据写作规范要求，章节编号从第一章开始编排）

一、令牌端点（Token Endpoint）的创建

1.1 OAuth2密码流程原理

OAuth2密码流程（Password Grant）是直接通过用户名密码获取访问令牌的认证方式。类比演唱会验票流程：用户先到售票处（令牌端点）用身份证（凭证）换取门票（令牌），之后凭门票入场（访问资源）。

流程步骤：

客户端发送用户名密码到/token端点
服务器验证凭证有效性
生成包含用户身份和有效期的JWT令牌
返回访问令牌给客户端

1.2 FastAPI端点实现

from fastapi import APIRouter, Depends, HTTPException, status
from pydantic import BaseModel
from datetime import datetime, timedelta
from jose import JWTError, jwt
from passlib.context import CryptContext

router = APIRouter(tags=["Authentication"])

# 密码哈希配置（使用bcrypt算法）
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

# JWT配置（实际项目应从环境变量读取）
SECRET_KEY = "your-secret-key-keep-it-secret!"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30


# 用户模型
class UserCreate(BaseModel):
    username: str
    password: str


# 令牌响应模型
class Token(BaseModel):
    access_token: str
    token_type: str


@router.post("/token", response_model=Token)
async def login_for_access_token(form_data: UserCreate):
    # 用户验证（示例用静态数据，实际应查数据库）
    if form_data.username != "admin" or not pwd_context.verify(
            "secret",  # 数据库中存储的哈希密码
            form_data.password
    ):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="用户名或密码错误",
            headers={"WWW-Authenticate": "Bearer"},
        )

    # 生成JWT令牌
    access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    access_token = create_access_token(
        data={"sub": form_data.username},
        expires_delta=access_token_expires
    )
    return {"access_token": access_token, "token_type": "bearer"}


def create_access_token(data: dict, expires_delta: timedelta):
    to_encode = data.copy()
    expire = datetime.utcnow() + expires_delta
    to_encode.update({"exp": expire})
    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
    return encoded_jwt

代码解析：

CryptContext 使用bcrypt算法进行密码哈希处理
UserCreate模型规范了客户端请求的数据格式
密码验证使用verify()方法比对哈希值
create_access_token生成带过期时间的JWT令牌

1.3 运行环境配置

# 安装依赖库（版本需严格对应）
fastapi==0.68.1
uvicorn==0.15.0
python-jose[cryptography]==3.3.0
passlib==1.7.4

二、访问令牌生成与校验

2.1 JWT令牌结构解析

示例令牌：
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTY1OTA3MDQwMH0.3w7hJH4KZ6Q-Mje3Q2T3T6k4Vd6QyQ6Qk7v6Qw7q6Qk

分段说明：

Header：{"alg": "HS256", "typ": "JWT"}
Payload：{"sub": "admin", "exp": 1659070400}
Signature：使用密钥对前两部分的签名

2.2 令牌校验实现

from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/token")


async def get_current_user(token: str = Depends(oauth2_scheme)):
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="无法验证凭证",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str = payload.get("sub")
        if username is None:
            raise credentials_exception
    except JWTError:
        raise credentials_exception

    # 此处应查询数据库验证用户存在性
    if username != "admin":
        raise credentials_exception
    return username


# 安全路由示例
@router.get("/protected")
async def protected_route(current_user: str = Depends(get_current_user)):
    return {"message": f"欢迎您, {current_user}"}

校验流程：

从请求头提取Bearer令牌
解码并验证JWT签名
检查令牌有效期
验证用户是否存在（示例简化处理）

三、课后Quiz

为什么在密码存储时要使用哈希而不是明文？
A. 提高查询速度
B. 防止数据泄露导致密码暴露
C. 减少存储空间占用
D. 方便密码找回
答案：B。哈希处理后的密码即使泄露也无法逆向获取原始密码
JWT中的签名部分主要作用是什么？
A. 美化令牌格式
B. 验证令牌内容未被篡改
C. 加速令牌解析
D. 支持多种加密算法
答案：B。签名确保令牌在传输过程中未被修改

四、常见报错解决方案

问题1：401 Unauthorized

现象：{"detail":"Not authenticated"}
原因：请求头缺少Authorization字段或格式错误

解决：

curl -H "Authorization: Bearer your_token" http://localhost:8000/protected

问题2：422 Validation Error

现象：请求体参数校验失败
原因：未按UserCreate模型格式提交数据
解决：检查请求是否包含username和password字段

问题3：403 Forbidden

现象：{"detail": "Invalid authentication credentials"}
原因：令牌已过期或签名验证失败
解决：重新获取有效令牌，检查密钥一致性

五、安全增强建议

生产环境必须：
- 通过HTTPS传输令牌
- 使用环境变量存储密钥
- 定期轮换加密密钥

推荐方案：

# 从环境变量读取密钥
import os
SECRET_KEY = os.getenv("JWT_SECRET_KEY")
if not SECRET_KEY:
    raise ValueError("Missing JWT_SECRET_KEY environment variable")

通过本章学习，开发者可以掌握FastAPI的OAuth2密码流程核心实现，建议结合数据库实现完整的用户管理系统。下一章将讲解权限控制与角色管理的高级应用。

余下文章内容请点击跳转至个人博客页面或者扫码关注或者微信搜一搜：编程智域前端至全栈交流与成长，阅读完整的文章：FastAPI安全认证：从密码到令牌的魔法之旅 | cmdragon’s Blog

往期文章归档：

ASCII编码的影响与作用：数字化时代的不可或缺之物

二月 25, 2024

一、ASCII编码的起源 ASCII（American Standard Code for Information Interchange）编码是一种最早用于将字符转换为数字的编码系统。它诞生于20世纪60年代，旨在解决计算机系统之间的字符传输和存储问题。在ASCII编码出现之前，不同的计算机系统使用不同的字符编码，导致字符在系统之间的传输和处理变得困难。 Ascii编码解码 | 一个覆盖广泛主题工具的高效在线平台(amd794.com) https://amd794.com/asciiencordec 二、ASCII编码解决了什么问题 ASCII编码的出现解决了字符传输和存储的标准化问题。它将字符映射为固定的7位二进制数，共计128个字符，包括英文字母、数字、标点符号和控制字符等。这种标准化的编码方式使得不同计算机系统之间可以准确地传输和处理字符数据，大大简化了字符处理的复杂性。三、ASCII编码对现在的影响和作用文本处理：ASCII编码在文本处理中起着重要作用，包括文件存储、数据传输、网络通信等。它成为了计算机系统中最基本的字符表示方式，被广泛应用于各种文本处理场景。编程语言：ASCII编码是大多数编程语言中字符表示的基础。程序员可以使用ASCII编码来处理和操作文本数据，实现各种字符处理的功能。数据库存储：ASCII编码可以用于将文本数据存储在数据库中，方便数据的检索和处理。它提供了一种标准的字符表示方式，使得数据的存储和查询更加方便和高效。跨平台兼容性：ASCII编码是一种标准化的字符编码系统，可以在不同的计算机和操作系统中使用。这种跨平台兼容性使得文本数据能够在不同的环境中无缝传输和处理。多语言处理：尽管ASCII编码只能表示英文字母、数字和一些基本符号，但它为后续的字符编码系统奠定了基础。ASCII编码的发展促使了后续的字符编码系统的出现，满足了多语言文本处理的需求。四、ASCII编码的应用领域电信通信：ASCII编码在电报和传真等通信方式中起着关键作用，实现了字符数据的传输和处理。网络通信：ASCII编码是互联网通信的基础，HTTP协议、电子邮件和网页等都使用ASCII编码来传输和处理文本数据。数据存储与处理：ASCII编码可以用于将文本数据存储在文件和数据库中，方便后续的数据检索和处理。编程语言与脚本：ASCII编码是大多数编程...

阅读全文

搜索此博客

cmdragon's Blog

FastAPI安全认证：从密码到令牌的魔法之旅