示例:JWT 认证 API
注册 → 登录换 token → 带 token 访问受保护端点 → 无 token 得到 401 → 权限不足得到 403。这个示例把 OAuth2 密码模式 + PyJWT + Argon2 串成一条完整的链路,对应第 12 章。
学习目标
- 能用
pwdlib[argon2]做密码哈希与校验,并知道为什么不用 passlib - 掌握 JWT 的签发、校验与过期处理
- 理解
OAuth2PasswordBearer与get_current_user依赖的配合方式 - 能写出基于角色的权限依赖
require_role - 会用 curl 完整演示认证与鉴权两种失败
目录结构
auth-api/
├── README.md
├── pyproject.toml
├── .env.example
├── app/
│ ├── __init__.py
│ ├── main.py
│ ├── core/
│ │ ├── config.py # SECRET_KEY / 过期时间 / 算法
│ │ └── security.py # 哈希 + JWT 签发/校验
│ ├── db/
│ │ ├── base.py
│ │ └── session.py
│ ├── models/
│ │ └── user.py
│ ├── schemas/
│ │ └── user.py # UserCreate / UserOut / Token
│ ├── services/
│ │ ├── exceptions.py
│ │ └── user.py # 注册、认证
│ └── api/
│ ├── deps.py # get_current_user / require_role
│ └── v1/
│ ├── auth.py # /auth/register · /auth/token · /auth/me
│ └── admin.py # /admin/users(仅 admin)
└── tests/
└── test_auth.pyapp/core/security.py 核心代码
from datetime import datetime, timedelta, timezone
from typing import Any
import jwt
from pwdlib import PasswordHash
from app.core.config import get_settings
settings = get_settings()
# Argon2 是当前推荐的密码哈希算法;pwdlib 是 passlib 的现代替代
password_hash = PasswordHash.recommended()
def hash_password(plain: str) -> str:
return password_hash.hash(plain)
def verify_password(plain: str, hashed: str) -> bool:
return password_hash.verify(plain, hashed)
def create_access_token(subject: str, extra: dict[str, Any] | None = None) -> str:
now = datetime.now(timezone.utc)
payload: dict[str, Any] = {
"sub": subject, # 主体:用户 id 的字符串形式
"iat": int(now.timestamp()),
"exp": int((now + timedelta(minutes=settings.access_token_expire_minutes)).timestamp()),
}
if extra:
payload.update(extra)
return jwt.encode(payload, settings.secret_key, algorithm=settings.jwt_algorithm)
def decode_access_token(token: str) -> dict[str, Any]:
# 必须显式限定算法列表,否则存在 alg 混淆风险
# exp 过期会抛 jwt.ExpiredSignatureError,签名错误抛 jwt.InvalidTokenError
return jwt.decode(token, settings.secret_key, algorithms=[settings.jwt_algorithm])三个要点:
| 项 | 说明 |
|---|---|
PasswordHash.recommended() | 默认使用 Argon2id,参数随硬件自动调优 |
sub 必须是字符串 | JWT 规范要求;解出来用 int(payload["sub"]) 还原用户 id |
algorithms=[...] | 白名单,不写就可能被 alg=none 攻击 |
/token 端点
OAuth2 密码模式要求表单提交(application/x-www-form-urlencoded),而不是 JSON:
# app/api/v1/auth.py
from typing import Annotated
from fastapi import APIRouter, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm
router = APIRouter(prefix="/auth", tags=["auth"])
@router.post("/token", response_model=Token, summary="用用户名密码换取 JWT")
async def login_for_access_token(
form: Annotated[OAuth2PasswordRequestForm, Depends()],
service: UserServiceDep,
) -> Token:
user = await service.authenticate(form.username, form.password)
if user is None:
# 不区分"用户不存在"和"密码错误",避免用户名枚举
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="用户名或密码错误",
headers={"WWW-Authenticate": "Bearer"},
)
return Token(
access_token=create_access_token(str(user.id), {"role": user.role}),
token_type="bearer",
expires_in=settings.access_token_expire_minutes * 60,
)OAuth2PasswordRequestForm 的字段固定为 username / password(外加可选的 scope、grant_type),这也是 Swagger UI 上 "Authorize" 按钮能直接用的前提。
get_current_user 依赖
# app/api/deps.py
from typing import Annotated
import jwt
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from sqlalchemy.ext.asyncio import AsyncSession
from app.core.config import get_settings
settings = get_settings()
# tokenUrl 指向 /token,Swagger UI 据此渲染授权表单
oauth2_scheme = OAuth2PasswordBearer(tokenUrl=f"{settings.api_v1_prefix}/auth/token")
SessionDep = Annotated[AsyncSession, Depends(get_db)]
async def get_current_user(
session: SessionDep,
token: Annotated[str, Depends(oauth2_scheme)],
) -> User:
credentials_error = HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="凭证无效或已过期",
headers={"WWW-Authenticate": "Bearer"},
)
try:
payload = decode_access_token(token)
except jwt.ExpiredSignatureError:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="登录已过期,请重新登录",
headers={"WWW-Authenticate": "Bearer"},
) from None
except jwt.InvalidTokenError:
raise credentials_error from None
user = await session.get(User, int(payload["sub"]))
if user is None or not user.is_active:
raise credentials_error
return user
CurrentUser = Annotated[User, Depends(get_current_user)]OAuth2PasswordBearer 做两件事:从 Authorization: Bearer <token> 里取出 token;缺 token 时自动返回 401(而不是 403)。这也解释了为什么"没带 token"和"权限不足"是两个不同的状态码。
require_role 权限依赖
把角色检查做成依赖工厂,用起来就是一行注解:
def require_role(*roles: str):
"""生成一个校验当前用户角色的依赖。用法:Depends(require_role("admin"))."""
async def checker(user: CurrentUser) -> User:
if user.role not in roles:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail=f"需要以下角色之一:{', '.join(roles)}",
)
return user
return checker
AdminUser = Annotated[User, Depends(require_role("admin"))]# app/api/v1/admin.py
router = APIRouter(prefix="/admin", tags=["admin"])
@router.get("/users", response_model=list[UserOut], summary="列出全部用户(仅管理员)")
async def list_users(user: AdminUser, service: UserServiceDep) -> list[UserOut]:
return [UserOut.model_validate(u) for u in await service.list_all()]
@router.delete("/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_user(
user_id: Annotated[int, Path(ge=1)],
_: AdminUser,
service: UserServiceDep,
) -> None:
await service.delete(user_id)🔑 401 与 403 的分界线:换个身份能不能成功?能 → 403(身份合法但不够格);不能 → 401(压根没身份)。所以认证依赖(
get_current_user)永远排在权限依赖之前。
启动
cd examples/auth-api
cp .env.example .env
# .env 里至少要有一个 32 字节以上的 SECRET_KEY
uv sync
uv run alembic upgrade head
uv run fastapi dev app/main.py用 curl 走完整流程
BASE=http://127.0.0.1:8000/api/v11. 注册(201)
curl -i -X POST $BASE/auth/register \
-H "Content-Type: application/json" \
-d '{"username":"alice","email":"alice@example.com","password":"s3cret-pass"}'预期 201 Created。响应体里不应出现 password 或 hashed_password:
{"id": 1, "username": "alice", "email": "alice@example.com", "role": "user"}2. 取 token(200)
注意是表单而不是 JSON:
curl -s -X POST $BASE/auth/token \
-d "username=alice&password=s3cret-pass"预期:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer"
}存进变量便于后续使用:
TOKEN=$(curl -s -X POST $BASE/auth/token \
-d "username=alice&password=s3cret-pass" | python -c "import sys,json;print(json.load(sys.stdin)['access_token'])")3. 带 token 访问受保护端点(200)
curl -i $BASE/auth/me -H "Authorization: Bearer $TOKEN"预期 200 OK,返回当前用户资料。
4. 不带 token(401)
curl -i $BASE/auth/me预期:
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer
{"detail":"Not authenticated"}5. 伪造 / 过期 token(401)
curl -i $BASE/auth/me -H "Authorization: Bearer not-a-real-token"预期 401,detail 为"凭证无效或已过期"。若把 access_token_expire_minutes 临时改成 0 再登录,可验证过期分支返回"登录已过期,请重新登录"。
6. 权限不足(403)
普通用户访问管理员端点:
curl -i $BASE/admin/users -H "Authorization: Bearer $TOKEN"预期:
HTTP/1.1 403 Forbidden
{"detail":"需要以下角色之一:admin"}对照组——把该用户的 role 改成 admin(直接改库或用管理员注册接口),同一个请求应返回 200。
7. 在 Swagger UI 里跑一遍
打开 http://127.0.0.1:8000/docs ,点右上角 Authorize,username / password 填 alice / s3cret-pass,点 Authorize。之后所有受保护端点会自动带上 Authorization 头——这正是 tokenUrl 配置生效的表现。
对应章节
- 认证与授权完整讲解 → 第 12 章:认证与授权(OAuth2 + JWT)
- 依赖注入机制 → 第 6 章:依赖注入系统
- 敏感字段过滤 → 第 5 章:响应模型与状态码
- 把这个示例接入完整项目 →
capstone
👉 返回课程目录