معرفی کتابخانه fastapi-login در پایتون

کتابخانه fastapi-login یک افزونه سبک برای مدیریت احراز هویت مبتنی بر JWT در فریم‌ورک FastAPI است. این کتابخانه کار با توکن‌ها، محافظت از مسیرها و مدیریت کاربر را ساده کرده و برای پروژه‌های کوچک تا متوسط بسیار مناسب است. هدف آن ارائهٔ API ساده و قابل فهم برای پیاده‌سازی لاگین، تولید توکن و ایجاد وابستگی‌های محافظت‌شده است.

ویژگی‌های کلیدی

• ایجاد توکن‌های JWT و مدیریت اعتبار آن‌ها
• ادغام آسان با FastAPI و سیستم dependency
• پشتیبانی از ذخیره‌سازی کاربر دلخواه (database, ORM, in-memory)
• امکان استفاده از کوکی برای نگهداری توکن‌ها

نصب و شروع به کار

می‌توانید fastapi-login را با pip نصب کنید:

pip install fastapi-login

در ادامه پیاده‌سازی پایه‌ای برای احراز هویت را می‌بینیم.

from fastapi import FastAPI, Depends, HTTPException
from fastapi_login import LoginManager
from pydantic import BaseModel

SECRET = "your-secret-key"
manager = LoginManager(SECRET, token_url="/auth/login")

app = FastAPI()

# مثال مدل کاربر ساده
class User(BaseModel):
    id: int
    username: str

# تابعی برای بارگذاری کاربر از دیتابیس (ایده‌آل: async و از ORM)
def load_user(username: str):
    if username == "alice":
        return User(id=1, username="alice")
    return None

@manager.user_loader()
def get_user(username: str):
    return load_user(username)

@app.post("/auth/login")
def login(data: dict):
    username = data.get("username")
    user = load_user(username)
    if not user:
        raise HTTPException(status_code=401, detail="Invalid credentials")
    access_token = manager.create_access_token(
        data={"sub": user.username}
    )
    return {"access_token": access_token}

توضیح: در این مثال یک secret ساده تعریف شده و LoginManager ساخته شده است. تابع user_loader کاربر را از یک منبع (مثلاً دیتابیس) بارگذاری می‌کند. در مسیر /auth/login، در صورت وجود کاربر، توکن ساخته و بازگردانده می‌شود. در عمل باید اعتبارسنجی رمز عبور و مدیریت خطاها را اضافه کنید.

محافظت از مسیرها و وابستگی‌ها

برای محافظت از مسیرها می‌توان از dependency که fastapi-login ارائه می‌دهد استفاده کرد:

from fastapi import Depends

@app.get("/protected")
def protected_route(user=Depends(manager)):
    return {"message": f"Hello {user.username}"}

توضیح: این dependency توکن را از هدر Authorization می‌خواند و بر اساس payload، تابع user_loader را صدا می‌زند و آبجکت کاربر را به مسیر تزریق می‌کند. در صورت نامعتبر بودن توکن، خطای 401 برگردانده می‌شود.

استفاده از کوکی برای توکن

اگر می‌خواهید توکن در کوکی قرار گیرد (برای برنامه‌های صفحه واحد یا حفظ session در مرورگر)، fastapi-login این امکان را فراهم می‌کند:

@app.post("/auth/login-cookie")
def login_cookie(data: dict, response: Response):
    user = load_user(data.get("username"))
    if not user:
        raise HTTPException(status_code=401, detail="Invalid credentials")
    access_token = manager.create_access_token(
        data={"sub": user.username}
    )
    manager.set_cookie(response, access_token)
    return {"message": "Logged in"}

توضیح: این کد توکن را به صورت امن در کوکی قرار می‌دهد. دقت کنید که برای امنیت باید گزینه‌های cookie مانند HttpOnly، Secure و SameSite را درست تنظیم کنید و در محیط HTTPS استفاده کنید.

پیشرفته: ادغام Refresh Token و نقش‌ها (Roles)

fastapi-login به خودی خود مکانیزم refresh token پیچیده را ارائه نمی‌دهد، اما می‌توانید با ایجاد توکن‌های access کوتاه‌مدت و refresh بلندمدت، و نگهداری refresh در دیتابیس یا کوکی امن، آن را پیاده‌سازی کنید. مثال بهینه‌شده زیر ساختار کلی را نشان می‌دهد:

from datetime import timedelta

ACCESS_EXPIRES = timedelta(minutes=15)
REFRESH_EXPIRES = timedelta(days=7)

@app.post("/auth/login")
def login_with_refresh(data: dict, response: Response):
    user = load_user(data.get("username"))
    if not user:
        raise HTTPException(status_code=401, detail="Invalid credentials")
    access_token = manager.create_access_token(
        data={"sub": user.username},
        expires=ACCESS_EXPIRES
    )
    refresh_token = manager.create_access_token(
        data={"sub": user.username, "type": "refresh"},
        expires=REFRESH_EXPIRES
    )
    # ذخیرهٔ refresh_token در دیتابیس یا قرار دادن در کوکی امن
    manager.set_cookie(response, refresh_token, key="refresh_token")
    return {"access_token": access_token}

توضیح: در این نمونه توکن دسترسی کوتاه‌مدت و توکن بازنشانی بلندمدت ایجاد می‌شود. توجه داشته باشید که برای refresh باید مکانیزمی برای تایید و باطل‌سازی refresh token (مثلاً ذخیره hash آن در دیتابیس) داشته باشید تا در صورت سرقت بتوانید tokenها را باطل کنید.

نکات امنیتی و عملیاتی

• همیشه یک SECRET قوی و محرمانه استفاده کنید و آن را در متغیرهای محیطی ذخیره کنید.
• توکن‌های access را کوتاه‌مدت نگه دارید و refresh tokenها را امن ذخیره کنید.
• برای کوکی‌ها از HttpOnly، Secure و SameSite مناسب استفاده کنید تا حملات XSS و CSRF کاهش یابد.
• در محیط‌های تولیدی از HTTPS استفاده کنید.
• برای ورود با رمز عبور حتماً از hashing (مثل bcrypt) استفاده کنید و هرگز رمز را به صورت متن ساده ذخیره نکنید.
• برای آزمون و توسعه از مقادیر تستی استفاده کنید و در codebase محرمانه‌ها را نگه ندارید.

مقایسه کوتاه با راهکارهای دیگر

تست و دیباگ

برای تست سعی کنید توکن‌ها را با ابزارهایی مثل curl یا httpie و همچنین تست‌های واحد بررسی کنید. در تست‌ها می‌توانید secret را مقدار ثابت قرار دهید اما در محیط CI باید از secret ایمن استفاده شود.

جمع‌بندی و توصیه‌های حرفه‌ای

fastapi-login یک کتابخانه عالی برای کسانی است که می‌خواهند سریع و با کمترین پیچیدگی احراز هویت JWT را به اپلیکیشن FastAPI اضافه کنند. برای پروژه‌های بزرگ‌تر یا نیاز به امکانات کامل‌تر، ترکیب fastapi-login با لایه‌های مدیریت refresh، blacklist برای توکن‌ها و استفاده از راهکارهای مدیریت کاربران پیشنهاد می‌شود. همیشه نکات امنیتی مانند ذخیرهٔ امن secretها، استفاده از HTTPS و مدیریت صحیح refresh tokenها را رعایت کنید.

برای شروع: نصب، خواندن داکیومنتیشن رسمی و پیاده‌سازی نمونه‌های کوچک در محیط توسعه را توصیه می‌کنم تا با جریان کار و محدودیت‌ها آشنا شوید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال