Skip to content

示例:JWT 认证 API ​

注册 → 登录换 token → 带 token 访问受保护端点 → 无 token 得到 401 → 权限不足得到 403。这个示例把 OAuth2 密码模式 + PyJWT + Argon2 串成一条完整的链路,对应第 12 章。


学习目标 ​

  • 能用 pwdlib[argon2] 做密码哈希与校验,并知道为什么不用 passlib
  • 掌握 JWT 的签发、校验与过期处理
  • 理解 OAuth2PasswordBearer 与 get_current_user 依赖的配合方式
  • 能写出基于角色的权限依赖 require_role
  • 会用 curl 完整演示认证与鉴权两种失败

目录结构 ​

text
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.py

app/core/security.py 核心代码 ​

python
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:

python
# 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 依赖 ​

python
# 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 权限依赖 ​

把角色检查做成依赖工厂,用起来就是一行注解:

python
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"))]
python
# 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)永远排在权限依赖之前。


启动 ​

bash
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 走完整流程 ​

bash
BASE=http://127.0.0.1:8000/api/v1

1. 注册(201) ​

bash
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:

json
{"id": 1, "username": "alice", "email": "alice@example.com", "role": "user"}

2. 取 token(200) ​

注意是表单而不是 JSON:

bash
curl -s -X POST $BASE/auth/token \
  -d "username=alice&password=s3cret-pass"

预期:

json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

存进变量便于后续使用:

bash
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) ​

bash
curl -i $BASE/auth/me -H "Authorization: Bearer $TOKEN"

预期 200 OK,返回当前用户资料。

4. 不带 token(401) ​

bash
curl -i $BASE/auth/me

预期:

text
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer

{"detail":"Not authenticated"}

5. 伪造 / 过期 token(401) ​

bash
curl -i $BASE/auth/me -H "Authorization: Bearer not-a-real-token"

预期 401,detail 为"凭证无效或已过期"。若把 access_token_expire_minutes 临时改成 0 再登录,可验证过期分支返回"登录已过期,请重新登录"。

6. 权限不足(403) ​

普通用户访问管理员端点:

bash
curl -i $BASE/admin/users -H "Authorization: Bearer $TOKEN"

预期:

text
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 配置生效的表现。


对应章节 ​


👉 返回课程目录

本文阅读--次|全站访问--次|访客--人