Khi API của bạn có cả người dùng thường và admin, chỉ kiểm tra “đã đăng nhập” là chưa đủ: user thường vẫn gọi được endpoint xóa dữ liệu. OAuth2 scopes giải quyết đúng việc này — mỗi token mang theo danh sách quyền, và mỗi route khai báo nó cần quyền nào. FastAPI hỗ trợ sẵn qua Security() và SecurityScopes, không cần viết thêm middleware.
Vấn đề
Giả sử bạn đã có dependency get_current_user kiểm tra JWT như bài trước. Mọi route đều dùng chung nó:
@app.get("/admin/users")def list_users(current_user: User = Depends(get_current_user)): return fake_users_db # Ai đăng nhập cũng xem được
Vấn đề nằm ở chỗ dependency này chỉ trả lời một câu hỏi duy nhất: token có hợp lệ không? Nó không biết route này cần quyền gì, và token này được cấp quyền gì. Muốn chặn, bạn phải viết if kiểm tra role trong từng hàm — code lặp lại, dễ quên một chỗ là thủng quyền.
Giải pháp
OAuth2 định nghĩa sẵn khái niệm scope: một chuỗi quyền gắn vào token lúc đăng nhập. FastAPI cho phép bạn khai báo scope ngay trong OAuth2PasswordBearer và yêu cầu scope ở từng route bằng Security() thay vì Depends(). Khi token thiếu scope, FastAPI trả 403 trước khi hàm của bạn chạy.
from fastapi import Depends, FastAPI, HTTPException, Security, statusfrom fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm, SecurityScopesfrom pydantic import BaseModelapp = FastAPI()oauth2_scheme = OAuth2PasswordBearer( tokenUrl="token", scopes={"items:read": "Đọc danh sách item", "items:write": "Tạo và sửa item"},)class User(BaseModel): username: str scopes: list[str] = []# Giả lập: token chính là username, scope lấy từ "database"fake_users_db = { "alice": User(username="alice", scopes=["items:read"]), "bob": User(username="bob", scopes=["items:read", "items:write"]),}def fake_decode_token(token: str) -> User: user = fake_users_db.get(token) if user is None: raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="Token không hợp lệ", headers={"WWW-Authenticate": "Bearer"}, ) return userasync def get_current_user( security_scopes: SecurityScopes, token: str = Depends(oauth2_scheme)) -> User: user = fake_decode_token(token) for scope in security_scopes.scopes: if scope not in user.scopes: raise HTTPException( status_code=status.HTTP_403_FORBIDDEN, detail="Không đủ quyền", headers={"WWW-Authenticate": f'Bearer scope="{security_scopes.scope_str}"'}, ) return user@app.post("/token")async def login(form_data: OAuth2PasswordRequestForm = Depends()): user = fake_users_db.get(form_data.username) if user is None: raise HTTPException(status_code=400, detail="Sai tên đăng nhập") granted = [s for s in form_data.scopes if s in user.scopes] return {"access_token": user.username, "token_type": "bearer", "scope": " ".join(granted)}@app.get("/items/")async def read_items(current_user: User = Security(get_current_user, scopes=["items:read"])): return [{"name": "Bút bi", "owner": current_user.username}]@app.post("/items/", status_code=201)async def create_item(current_user: User = Security(get_current_user, scopes=["items:write"])): return {"message": f"{current_user.username} đã tạo item mới"}
Điểm mấu chốt là Security() thay cho Depends(): chỉ Security() mới truyền danh sách scope cần thiết vào SecurityScopes, để dependency biết route đang đòi quyền gì. FastAPI kiểm tra scope trước khi chạy hàm xử lý, nên code trong hàm không cần thêm một dòng if nào. Khai báo scopes={...} trong OAuth2PasswordBearer còn giúp Swagger UI hiện hộp tick chọn quyền khi bấm Authorize — tester xin đúng quyền mình cần, không xin thừa.
Áp dụng vào dự án của bạn
Chia quyền theo động từ + tài nguyên, ví dụ orders:read, orders:write, admin:manage, thay vì role chung chung. Cấp scope lúc đăng nhập theo đúng vai trò của user, và luôn kiểm tra ở tầng route — đừng chỉ ẩn nút trên giao diện, vì API vẫn gọi trực tiếp được. Khi thêm route mới, thói quen tốt là hỏi trước: route này cần scope nào? Trong code thật, token nên là JWT chứa scope trong claim, và hàm giải mã token chỉ cần tách chuỗi scope thành list rồi đưa vào object user như ví dụ trên.
Bài viết liên quan
- FastAPI: bảo vệ route bằng dependency JWT/OAuth2 tái sử dụng, không lặp code xác thực
- FastAPI: nhận dữ liệu form bằng Form() — endpoint login chuẩn OAuth2 trong 5 phút
- FastAPI: bảo vệ route bằng HTTPBearer — xác thực Bearer token không cần OAuth2 trong 5 phút
Câu hỏi thường gặp
Scope khác gì role?
Role là nhóm quyền của user (admin, editor), scope là từng quyền lẻ gắn vào token. Một role có thể gồm nhiều scope; FastAPI kiểm tra scope, không kiểm tra role. Dùng scope cho route, role chỉ để gom scope lúc cấp token.
Dùng Depends() thay Security() được không?
Không. Depends() không truyền scope yêu cầu vào dependency, nên security_scopes.scopes sẽ rỗng và mọi token hợp lệ đều qua. Muốn phân quyền theo scope, bắt buộc dùng Security().
Token xin scope mà user không có thì sao?
Endpoint /token chỉ cấp scope nằm trong giao của scope yêu cầu và scope user thật sự có. Xin thừa không được cấp thêm — code ví dụ lọc bằng list comprehension.
Scope có thay thế việc kiểm tra quyền sở hữu dữ liệu không?
Không. Scope chỉ nói user được phép gọi route; còn “user này có được sửa item của người khác không” vẫn phải kiểm tra trong hàm, vì đó là quyền trên từng bản ghi, không phải trên route.
Scope lưu ở đâu trong token thật (JWT)?
Trong claim scope hoặc scp, dạng chuỗi cách nhau bằng khoảng trắng, ví dụ "items:read items:write". Lúc giải mã JWT, tách chuỗi này thành list rồi đưa vào object user như ví dụ trên.
💬 Bạn đã thử cách này trong dự án của mình chưa? Nếu gặp lỗi hoặc có cách làm gọn hơn, để lại bình luận bên dưới — mình đọc hết và sẽ bổ sung những ý hay vào bài.
Nguồn tham khảo
- FastAPI — OAuth2 with Password (and hashing), Bearer with JWT: https://fastapi.tiangolo.com/tutorial/security/oauth2-jwt/
- FastAPI — OAuth2 scopes: https://fastapi.tiangolo.com/advanced/security/oauth2-scopes/
