⭐ Python Developer · Chặng 9Bài 4/6Bài học~75 phút

Xác thực trong FastAPI: băm mật khẩu Argon2 và JWT

Bảo vệ API: băm mật khẩu Argon2 với pwdlib, cấp JWT bằng PyJWT, OAuth2PasswordBearer, get_current_user và phân quyền theo người dùng.

Xác thực trong FastAPI: băm mật khẩu Argon2 và JWT

Học xong bài này, bạn sẽ

  • Băm mật khẩu bằng Argon2, không bao giờ lưu mật khẩu gốc
  • Cấp và kiểm tra JWT với OAuth2PasswordBearer
  • Bảo vệ endpoint và giới hạn dữ liệu theo người dùng

Nên học trước: FastAPI với cơ sở dữ liệu SQLAlchemy

Nội dung bài viết
  1. 1. Cài thêm thư viện và cấu trúc mới
  2. 2. Băm mật khẩu: không bao giờ lưu mật khẩu gốc
  3. 3. JWT: tấm vé có chữ ký
  4. 4. Model, schema và các endpoint tài khoản
  5. 5. Chạy thử luồng đầy đủ
  6. Tóm tắt
  7. Bài tập

API sổ ghi chú hiện ai cũng đọc, sửa, xóa được mọi ghi chú. Ứng dụng thật cần biết ai đang gọi (xác thực, authentication) và người đó được làm gì (phân quyền, authorization). Bài này thêm đăng ký, đăng nhập bằng mật khẩu băm Argon2, cấp token JWT, và giới hạn mỗi người chỉ thấy ghi chú của mình, theo đúng cách tài liệu FastAPI khuyến nghị.

Bảo mật: dùng thư viện, không tự chếTự viết thuật toán băm, tự chế định dạng token là con đường ngắn nhất dẫn đến lỗ hổng. Bài dùng pwdlib (băm mật khẩu) và PyJWT (token), hai thư viện mà tài liệu FastAPI hiện dùng. Mọi quyết định bảo mật trong bài đều có lý do, hãy đọc kỹ phần giải thích.

1. Cài thêm thư viện và cấu trúc mới

$ uv add pyjwt "pwdlib[argon2]"

app/
├── database.py   (giữ nguyên bài trước)
├── models.py     ← thêm bảng nguoi_dung, ghi_chu có chu_id
├── schemas.py    ← thêm NguoiDungTao, NguoiDungDoc, Token
├── security.py   ← MỚI: băm mật khẩu, tạo và đọc JWT
├── auth.py       ← MỚI: dependency lấy người dùng hiện tại
└── main.py       ← thêm /auth/dang-ky, /auth/token, /nguoi-dung/toi

2. Băm mật khẩu: không bao giờ lưu mật khẩu gốc

# (minh họa) app/security.py
"""Băm mật khẩu và cấp, kiểm tra JWT."""

import os
from datetime import UTC, datetime, timedelta

import jwt
from pwdlib import PasswordHash

SECRET_KEY = os.environ.get("SECRET_KEY", "chi-dung-khi-phat-trien-doi-khi-trien-khai")
ALGORITHM = "HS256"
THOI_HAN_PHUT = 30

password_hash = PasswordHash.recommended()  # Argon2 với tham số khuyến nghị
HASH_GIA = password_hash.hash("mat-khau-gia")  # dùng khi tên đăng nhập không tồn tại


def bam_mat_khau(mat_khau: str) -> str:
    return password_hash.hash(mat_khau)


def kiem_tra_mat_khau(mat_khau: str, da_bam: str) -> bool:
    return password_hash.verify(mat_khau, da_bam)


def tao_token(ten_dang_nhap: str) -> str:
    het_han = datetime.now(UTC) + timedelta(minutes=THOI_HAN_PHUT)
    return jwt.encode({"sub": ten_dang_nhap, "exp": het_han}, SECRET_KEY, algorithm=ALGORITHM)


def doc_token(token: str) -> str | None:
    """Trả tên đăng nhập nếu token hợp lệ và chưa hết hạn, ngược lại None."""
    try:
        du_lieu = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
    except jwt.InvalidTokenError:
        return None
    return du_lieu.get("sub")

Băm (hash) là biến đổi một chiều: từ mật khẩu tính ra chuỗi băm dễ, nhưng từ chuỗi băm không tính ngược ra mật khẩu. Khi đăng nhập, ta băm mật khẩu người dùng gõ rồi so với chuỗi đã lưu (verify). Nếu CSDL bị lộ, kẻ tấn công chỉ có chuỗi băm. Đây là hai dòng thật trong bảng sau khi đăng ký:

('an_nguyen', '$argon2id$v=19$m=65536,t=3,p=4$hLd5BjGEU...')
('binh',      '$argon2id$v=19$m=65536,t=3,p=4$SpO9zFYMG...')
  • Argon2id là thuật toán băm mật khẩu được khuyến nghị hiện nay: cố tình chậm và tốn bộ nhớ (m=65536 KB) để việc thử hàng tỷ mật khẩu trở nên quá đắt. Không bao giờ dùng MD5, SHA-256 trần cho mật khẩu: chúng quá nhanh.
  • Mỗi chuỗi băm có muối (salt) ngẫu nhiên riêng (phần sau dấu $ cuối), nên hai người cùng mật khẩu vẫn có chuỗi băm khác nhau.
  • HASH_GIA dùng ở endpoint đăng nhập (mục 4) để chống đoán tên đăng nhập qua thời gian phản hồi.

3. JWT: tấm vé có chữ ký

HTTP không trạng thái, nên sau khi đăng nhập, client phải chứng minh danh tính ở mỗi request. Máy chủ cấp một JWT (JSON Web Token): chuỗi gồm ba phần cách nhau bằng dấu chấm: header, payload (dữ liệu), chữ ký.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbl9uZ3V5ZW4iLCJleHAiOjE3OTMyNjg3MDZ9.HANJbZWy6fPCuO9fDWdlBKCBN9bcOqkD7Hr9PfUOSgc
           header (thuật toán)       .           payload                  .          chữ ký
import jwt

token = ("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbl9uZ3V5ZW4iLCJleHAiOjE3OTMyNjg3MDZ9"
         ".HANJbZWy6fPCuO9fDWdlBKCBN9bcOqkD7Hr9PfUOSgc")
print(jwt.decode(token, options={"verify_signature": False}))   # ai cũng đọc được payload!
{'sub': 'an_nguyen', 'exp': 1793268706}
  • Payload chỉ được mã hóa base64, không được mã hóa bí mật: ai có token cũng đọc được nội dung. Không bao giờ đặt mật khẩu, số thẻ hay dữ liệu nhạy cảm vào payload.
  • Chữ ký được tính từ header + payload + SECRET_KEY. Sửa một ký tự payload (đổi sub thành người khác) thì chữ ký không còn khớp và jwt.decode ném lỗi. Chỉ máy chủ biết SECRET_KEY nên chỉ máy chủ tạo được token hợp lệ.
  • sub (subject) là người dùng; exp là thời điểm hết hạn (giây tính từ 1/1/1970, giờ UTC); PyJWT tự kiểm tra exp khi decode. Token sống 30 phút: bị lộ thì thiệt hại có giới hạn.
  • SECRET_KEY đọc từ biến môi trường. Khi triển khai, tạo khóa ngẫu nhiên đủ dài: python -c "import secrets; print(secrets.token_hex(32))". Lộ khóa này là kẻ xấu tạo được token cho bất kỳ ai.

4. Model, schema và các endpoint tài khoản

# (minh họa) app/models.py
"""Model SQLAlchemy: cấu trúc bảng trong CSDL."""

from datetime import datetime

from sqlalchemy import JSON, ForeignKey, String, func
from sqlalchemy.orm import Mapped, mapped_column

from app.database import Base


class NguoiDung(Base):
    __tablename__ = "nguoi_dung"

    id: Mapped[int] = mapped_column(primary_key=True)
    ten_dang_nhap: Mapped[str] = mapped_column(String(50), unique=True)
    mat_khau_bam: Mapped[str]  # KHÔNG BAO GIỜ lưu mật khẩu gốc


class GhiChu(Base):
    __tablename__ = "ghi_chu"

    id: Mapped[int] = mapped_column(primary_key=True)
    chu_id: Mapped[int] = mapped_column(ForeignKey("nguoi_dung.id"), index=True)
    tieu_de: Mapped[str] = mapped_column(String(100))
    noi_dung: Mapped[str] = mapped_column(default="")
    the: Mapped[list[str]] = mapped_column(JSON, default=list)
    tao_luc: Mapped[datetime] = mapped_column(server_default=func.now())
# (minh họa) app/auth.py
"""Dependency lấy người dùng hiện tại từ header Authorization: Bearer <token>."""

from typing import Annotated

from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from sqlalchemy import select

from app.database import SessionDep
from app.models import NguoiDung
from app.security import doc_token

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="auth/token")


def lay_nguoi_dung_hien_tai(
    token: Annotated[str, Depends(oauth2_scheme)], session: SessionDep
) -> NguoiDung:
    loi_401 = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Token không hợp lệ hoặc đã hết hạn",
        headers={"WWW-Authenticate": "Bearer"},
    )
    ten = doc_token(token)
    if ten is None:
        raise loi_401
    nguoi_dung = session.scalar(select(NguoiDung).where(NguoiDung.ten_dang_nhap == ten))
    if nguoi_dung is None:
        raise loi_401
    return nguoi_dung


NguoiDungHienTai = Annotated[NguoiDung, Depends(lay_nguoi_dung_hien_tai)]

OAuth2PasswordBearer(tokenUrl="auth/token") là dependency đọc header Authorization: Bearer <token>; thiếu header thì tự trả 401 "Not authenticated". lay_nguoi_dung_hien_tai phụ thuộc vào nó và vào SessionDep: dependency có thể phụ thuộc dependency khác, FastAPI tự giải quyết cả chuỗi. Endpoint nào khai báo tham số kiểu NguoiDungHienTai thì endpoint đó bắt buộc đăng nhập.

File app/main.py đầy đủ:

# (minh họa) app/main.py
"""API sổ ghi chú có đăng ký, đăng nhập; mỗi người chỉ thấy ghi chú của mình."""

from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from typing import Annotated

from fastapi import Depends, FastAPI, HTTPException, Query, status
from fastapi.security import OAuth2PasswordRequestForm
from sqlalchemy import or_, select

from app.auth import NguoiDungHienTai
from app.database import Base, SessionDep, engine
from app.models import GhiChu, NguoiDung
from app.schemas import GhiChuCapNhat, GhiChuDoc, GhiChuTao, NguoiDungDoc, NguoiDungTao, Token
from app.security import HASH_GIA, bam_mat_khau, kiem_tra_mat_khau, tao_token


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    Base.metadata.create_all(engine)
    yield


app = FastAPI(title="Sổ ghi chú", version="0.3.0", lifespan=lifespan)


# ---------------------------------------------------------------- tài khoản
@app.post("/auth/dang-ky", status_code=status.HTTP_201_CREATED)
def dang_ky(du_lieu: NguoiDungTao, session: SessionDep) -> NguoiDungDoc:
    if session.scalar(select(NguoiDung).where(NguoiDung.ten_dang_nhap == du_lieu.ten_dang_nhap)):
        raise HTTPException(status_code=409, detail="Tên đăng nhập đã được dùng")
    nd = NguoiDung(ten_dang_nhap=du_lieu.ten_dang_nhap, mat_khau_bam=bam_mat_khau(du_lieu.mat_khau))
    session.add(nd)
    session.commit()
    session.refresh(nd)
    return NguoiDungDoc.model_validate(nd)


@app.post("/auth/token")
def dang_nhap(form: Annotated[OAuth2PasswordRequestForm, Depends()], session: SessionDep) -> Token:
    nd = session.scalar(select(NguoiDung).where(NguoiDung.ten_dang_nhap == form.username))
    # Luôn kiểm tra một hash để thời gian phản hồi như nhau, kẻ xấu không đoán được tên nào tồn tại
    hop_le = kiem_tra_mat_khau(form.password, nd.mat_khau_bam if nd else HASH_GIA)
    if nd is None or not hop_le:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Sai tên đăng nhập hoặc mật khẩu",
            headers={"WWW-Authenticate": "Bearer"},
        )
    return Token(access_token=tao_token(nd.ten_dang_nhap))


@app.get("/nguoi-dung/toi")
def toi(nguoi_dung: NguoiDungHienTai) -> NguoiDungDoc:
    return NguoiDungDoc.model_validate(nguoi_dung)


# ---------------------------------------------------------------- ghi chú
def lay_cua_toi(session: SessionDep, ghi_chu_id: int, nguoi_dung: NguoiDung) -> GhiChu:
    gc = session.get(GhiChu, ghi_chu_id)
    if (
        gc is None or gc.chu_id != nguoi_dung.id
    ):  # của người khác cũng trả 404, không lộ là có tồn tại
        raise HTTPException(status_code=404, detail="Không tìm thấy ghi chú")
    return gc


@app.post("/ghi-chu", status_code=status.HTTP_201_CREATED)
def tao(du_lieu: GhiChuTao, session: SessionDep, nguoi_dung: NguoiDungHienTai) -> GhiChuDoc:
    gc = GhiChu(chu_id=nguoi_dung.id, **du_lieu.model_dump())
    session.add(gc)
    session.commit()
    session.refresh(gc)
    return GhiChuDoc.model_validate(gc)


@app.get("/ghi-chu")
def liet_ke(
    session: SessionDep,
    nguoi_dung: NguoiDungHienTai,
    tu_khoa: str | None = None,
    skip: Annotated[int, Query(ge=0)] = 0,
    limit: Annotated[int, Query(ge=1, le=100)] = 20,
) -> list[GhiChuDoc]:
    q = select(GhiChu).where(GhiChu.chu_id == nguoi_dung.id).order_by(GhiChu.id)
    if tu_khoa:
        q = q.where(
            or_(GhiChu.tieu_de.ilike(f"%{tu_khoa}%"), GhiChu.noi_dung.ilike(f"%{tu_khoa}%"))
        )
    return [GhiChuDoc.model_validate(gc) for gc in session.scalars(q.offset(skip).limit(limit))]


@app.get("/ghi-chu/{ghi_chu_id}")
def xem(ghi_chu_id: int, session: SessionDep, nguoi_dung: NguoiDungHienTai) -> GhiChuDoc:
    return GhiChuDoc.model_validate(lay_cua_toi(session, ghi_chu_id, nguoi_dung))


@app.patch("/ghi-chu/{ghi_chu_id}")
def cap_nhat(
    ghi_chu_id: int, du_lieu: GhiChuCapNhat, session: SessionDep, nguoi_dung: NguoiDungHienTai
) -> GhiChuDoc:
    gc = lay_cua_toi(session, ghi_chu_id, nguoi_dung)
    for truong, gia_tri in du_lieu.model_dump(exclude_unset=True).items():
        setattr(gc, truong, gia_tri)
    session.commit()
    session.refresh(gc)
    return GhiChuDoc.model_validate(gc)


@app.delete("/ghi-chu/{ghi_chu_id}", status_code=status.HTTP_204_NO_CONTENT)
def xoa(ghi_chu_id: int, session: SessionDep, nguoi_dung: NguoiDungHienTai) -> None:
    session.delete(lay_cua_toi(session, ghi_chu_id, nguoi_dung))
    session.commit()
  • Đăng ký trả NguoiDungDoc, không có trường mat_khau_bam: kiểu trả về lọc nó đi. Tên trùng trả 409.
  • Đăng nhập nhận form username, password theo chuẩn OAuth2 (OAuth2PasswordRequestForm), nên nút Authorize trên /docs dùng được ngay. Sai tên hay sai mật khẩu đều trả cùng một thông báo, và luôn chạy verify (với HASH_GIA khi tên không tồn tại) để thời gian phản hồi như nhau: kẻ xấu không phân biệt được "tên không có" với "sai mật khẩu".
  • Phân quyền: mọi truy vấn ghi chú đều lọc chu_id == nguoi_dung.id. Ghi chú của người khác trả 404 chứ không phải 403, để không tiết lộ ghi chú đó có tồn tại.

5. Chạy thử luồng đầy đủ

POST /auth/dang-ky  {"ten_dang_nhap":"an_nguyen","mat_khau":"matkhau-an-123"}
201 {"id":1,"ten_dang_nhap":"an_nguyen"}
POST /auth/dang-ky  (trùng tên)
409 {"detail":"Tên đăng nhập đã được dùng"}
POST /auth/token    username=an_nguyen&password=sai-mat-khau
401 {"detail":"Sai tên đăng nhập hoặc mật khẩu"}
POST /auth/token    username=an_nguyen&password=matkhau-an-123
200 {"access_token":"eyJhbGciOiJIUzI1NiIs...","token_type":"bearer"}
GET  /nguoi-dung/toi               Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
200 {"id":1,"ten_dang_nhap":"an_nguyen"}
GET  /ghi-chu                      (không có header)
401 {"detail":"Not authenticated"}
GET  /ghi-chu                      Authorization: Bearer abc.def.ghi
401 {"detail":"Token không hợp lệ hoặc đã hết hạn"}
POST /ghi-chu  {"tieu_de":"Bí mật của An"}        (token của An)
201 {"tieu_de":"Bí mật của An","noi_dung":"","the":[],"id":1,"tao_luc":"2026-10-29T09:41:46"}
GET  /ghi-chu/1                    (token của Bình)
404 {"detail":"Không tìm thấy ghi chú"}

Trên /docs, bấm nút Authorize, nhập tên và mật khẩu: Swagger UI tự gọi /auth/token và gắn token vào mọi request sau đó.

Những thứ còn thiếu cho hệ thống thậtLuôn chạy qua HTTPS (token gửi qua HTTP thường có thể bị nghe lén). Giới hạn số lần đăng nhập sai để chống dò mật khẩu. Thêm refresh token nếu không muốn người dùng đăng nhập lại mỗi 30 phút. Với ứng dụng lớn, cân nhắc dịch vụ xác thực có sẵn thay vì tự quản lý mật khẩu.

Tóm tắt

  • Băm mật khẩu bằng Argon2 qua pwdlib; chỉ lưu chuỗi băm; so khớp bằng verify.
  • JWT = header.payload.chữ ký; payload ai cũng đọc được; chữ ký chống giả mạo; có exp; SECRET_KEY từ biến môi trường.
  • OAuth2PasswordBearer + dependency lay_nguoi_dung_hien_tai; endpoint cần đăng nhập thì nhận NguoiDungHienTai.
  • Lọc dữ liệu theo chủ sở hữu; của người khác trả 404; thông báo đăng nhập sai chung chung.

Bài tập

Bài 1. Hai người dùng

Dựng API theo bài, tạo hai tài khoản trên /docs, mỗi người tạo 2 ghi chú. Đăng nhập bằng từng tài khoản (nút Authorize) và xác nhận mỗi người chỉ thấy ghi chú của mình; thử xem, sửa, xóa ghi chú của người kia.

Xem gợi ý

Mọi thao tác lên ghi chú của người kia phải trả 404. Mở so_ghi_chu.db để thấy cột chu_id và chuỗi băm Argon2 trong bảng nguoi_dung. Bạn sẽ tự động hóa đúng kịch bản này thành test ở bài sau.

Bài 2. Thử giả mạo token

Lấy token của tài khoản A, giải mã payload, sửa sub thành tên tài khoản B, ghép lại với chữ ký cũ và gửi lên API. Giải thích kết quả.

Xem đáp án
import base64
import json
from datetime import UTC, datetime, timedelta

import jwt

SECRET_KEY = "chi-dung-khi-phat-trien-doi-khi-trien-khai"
het_han = datetime.now(UTC) + timedelta(minutes=30)
that = jwt.encode({"sub": "an_nguyen", "exp": het_han}, SECRET_KEY, algorithm="HS256")
header, payload, chu_ky = that.split(".")

du_lieu = json.loads(base64.urlsafe_b64decode(payload + "=="))
du_lieu["sub"] = "binh"                                          # giả làm Bình
payload_gia = base64.urlsafe_b64encode(json.dumps(du_lieu).encode()).rstrip(b"=").decode()
gia = f"{header}.{payload_gia}.{chu_ky}"

try:
    jwt.decode(gia, SECRET_KEY, algorithms=["HS256"])
except jwt.InvalidSignatureError as loi:
    print("Bị từ chối:", loi)
print(jwt.decode(that, SECRET_KEY, algorithms=["HS256"])["sub"])
Bị từ chối: Signature verification failed
an_nguyen

Đọc và sửa payload thì dễ, nhưng chữ ký cũ được tính cho payload cũ. Muốn có chữ ký đúng cho payload mới phải biết SECRET_KEY. API trả 401 cho token giả. Đây là lý do SECRET_KEY phải bí mật, dài, ngẫu nhiên, và khác nhau giữa máy phát triển và máy chủ thật.

Nguồn tham khảo: FastAPI: OAuth2 with Password (and hashing), Bearer with JWT tokens; PyJWT; pwdlib; OWASP: Password Storage Cheat Sheet; RFC 7519: JSON Web Token.

Bài tập thực hành

  1. Thêm đăng ký, đăng nhập vào API sổ ghi chú; mỗi người chỉ xem được ghi chú của mình.
  2. Đọc payload một token trên jwt.io, giải thích vì sao không được đặt mật khẩu vào token.

Làm xong bài tập mới chuyển sang bài tiếp theo: tự viết code là cách duy nhất để nhớ lâu.

Bài tiếp theo
Ban biên tập HocFree

Chúng tôi viết những bài hướng dẫn dễ hiểu, thực tế để ai cũng có thể tự học lập trình và AI, hoàn toàn miễn phí.