Аутентификация в API: JWT и OAuth2

Привет! Аутентификация — это основа безопасности любого API. Без неё злоумышленники могут получить доступ к данным, выдавать себя за других пользователей и совершать вредоносные действия. В современном мире стандартами де-факто стали JWT (JSON Web Tokens) и OAuth2.

В этой статье мы разберём:

Что такое JWT и OAuth2
Настройку OAuth2 в FastAPI
Создание и валидацию JWT токенов
Хеширование паролей
Защиту эндпоинтов
Refresh-токены и роли

Содержание

Что нужно знать перед началом
Основная часть
Что такое JWT и OAuth2
Установка зависимостей
Настройка JWT
Хеширование паролей
Модели данных
Создание и проверка JWT токенов
Эндпоинты аутентификации
Refresh-токены
Роли и права доступа (RBAC)
Задачи для закрепления
Нюансы и подводные камни
Хранение секретов
Срок жизни токена
Защита от timing-атак
JWT не шифрует данные
Частые ошибки и как их избежать
Ошибка 1: Хранение SECRET_KEY в коде
Ошибка 2: Слишком долгий срок жизни access-токена
Ошибка 3: Хранение паролей в открытом виде
Ошибка 4: Отсутствие проверки type у refresh-токенов
Шпаргалка
Заключение
КВИЗ
Что дальше?

Что нужно знать перед началом

Для этого урока тебе понадобится:

Установленный FastAPI и Uvicorn
Базовое понимание асинхронности

Совет: JWT — это способ передавать информацию между сторонами в виде JSON-объекта, который можно проверить и которому можно доверять, потому что он подписан цифровой подписью.

Основная часть

Что такое JWT и OAuth2

JWT (JSON Web Token) — это компактный способ безопасной передачи информации в виде JSON-объекта. Он содержит три части, разделённые точками:

header.payload.signature

Header — тип токена и алгоритм подписи
Payload — полезная нагрузка (данные пользователя, срок действия)
Signature — цифровая подпись, подтверждающая, что токен не был изменён

Важно: JWT кодируется, а не шифруется! Никогда не храни в нём пароли или другую чувствительную информацию .

OAuth2 — это протокол авторизации, который позволяет клиентам получать доступ к ресурсам пользователя без передачи пароля. FastAPI встроенно поддерживает OAuth2 через класс OAuth2PasswordBearer.

Установка зависимостей

pip install python-jose[cryptography] passlib[bcrypt] python-multipart

python-jose — для создания и проверки JWT
passlib — для хеширования паролей
python-multipart — для обработки OAuth2 форм

Настройка JWT

from datetime import datetime, timedelta, timezone
from jose import jwt
from jose.exceptions import JWTError
from passlib.context import CryptContext
from fastapi.security import OAuth2PasswordBearer

# Генерация секретного ключа (в продакшене используй env)
# openssl rand -hex 32
SECRET_KEY = "09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

# Хеширование паролей
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

# OAuth2 схема
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

Совет: В продакшене храни SECRET_KEY в переменных окружения, а не в коде .

Хеширование паролей

def verify_password(plain_password: str, hashed_password: str) -> bool:
    return pwd_context.verify(plain_password, hashed_password)

def get_password_hash(password: str) -> str:
    return pwd_context.hash(password)

Совет: Используй Argon2 или bcrypt для хеширования паролей. Это защищает от атак перебором.

Модели данных

from pydantic import BaseModel

class Token(BaseModel):
    access_token: str
    token_type: str

class TokenData(BaseModel):
    username: str | None = None

class User(BaseModel):
    username: str
    email: str | None = None
    full_name: str | None = None
    disabled: bool | None = None

class UserInDB(User):
    hashed_password: str

Заглушка базы данных:

fake_users_db = {
    "johndoe": {
        "username": "johndoe",
        "full_name": "John Doe",
        "email": "johndoe@example.com",
        "hashed_password": "$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW",
        "disabled": False,
    }
}

def get_user(db, username: str):
    if username in db:
        user_dict = db[username]
        return UserInDB(**user_dict)

Совет: В реальных проектах используй базу данных (PostgreSQL, SQLite) вместо заглушки.

Создание и проверка JWT токенов

Создание токена:

def create_access_token(data: dict, expires_delta: timedelta | None = None) -> str:
    to_encode = data.copy()
    expire = datetime.now(timezone.utc) + (expires_delta or timedelta(minutes=15))
    to_encode.update({"exp": expire})
    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
    return encoded_jwt

Аутентификация пользователя:

from jose import JWTError

def authenticate_user(fake_db, username: str, password: str):
    user = get_user(fake_db, username)
    if not user:
        return False
    if not verify_password(password, user.hashed_password):
        return False
    return user

async def get_current_user(token: str = Depends(oauth2_scheme)):
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str = payload.get("sub")
        if username is None:
            raise credentials_exception
        token_data = TokenData(username=username)
    except JWTError:
        raise credentials_exception

    user = get_user(fake_users_db, username=token_data.username)
    if user is None:
        raise credentials_exception
    return user

async def get_current_active_user(current_user: User = Depends(get_current_user)):
    if current_user.disabled:
        raise HTTPException(status_code=400, detail="Inactive user")
    return current_user

Эндпоинты аутентификации

Login:

from fastapi.security import OAuth2PasswordRequestForm

@app.post("/token", response_model=Token)
async def login_for_access_token(
    form_data: Annotated[OAuth2PasswordRequestForm, Depends()]
):
    user = authenticate_user(fake_users_db, form_data.username, form_data.password)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
            headers={"WWW-Authenticate": "Bearer"},
        )
    access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    access_token = create_access_token(
        data={"sub": user.username}, expires_delta=access_token_expires
    )
    return {"access_token": access_token, "token_type": "bearer"}

Protected эндпоинт:

@app.get("/users/me", response_model=User)
async def read_users_me(current_user: User = Depends(get_current_active_user)):
    return current_user

Refresh-токены

Для долгосрочных сессий можно добавить refresh-токен (срок жизни — дни или недели). Он позволяет получить новый access-токен без повторного ввода пароля.

REFRESH_TOKEN_EXPIRE_DAYS = 7

def create_refresh_token(data: dict) -> str:
    to_encode = data.copy()
    expire = datetime.now(timezone.utc) + timedelta(days=REFRESH_TOKEN_EXPIRE_DAYS)
    to_encode.update({"exp": expire, "type": "refresh"})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

@app.post("/refresh", response_model=Token)
async def refresh_access_token(refresh_token: str = Body(...)):
    try:
        payload = jwt.decode(refresh_token, SECRET_KEY, algorithms=[ALGORITHM])
        if payload.get("type") != "refresh":
            raise HTTPException(status_code=401, detail="Invalid token type")
        username = payload.get("sub")
        if username is None:
            raise HTTPException(status_code=401, detail="Invalid token")
    except JWTError:
        raise HTTPException(status_code=401, detail="Invalid refresh token")

    user = get_user(fake_users_db, username)
    if not user:
        raise HTTPException(status_code=401, detail="User not found")

    new_access_token = create_access_token(data={"sub": user.username})
    return {"access_token": new_access_token, "token_type": "bearer"}

Роли и права доступа (RBAC)

from enum import Enum

class UserRole(str, Enum):
    READER = "reader"
    AUTHOR = "author"
    ADMIN = "admin"

# В модели User добавляем roles: list[UserRole]

def require_roles(*required_roles: UserRole):
    def role_checker(current_user: User = Depends(get_current_active_user)):
        user_roles = getattr(current_user, "roles", [])
        if not any(role in user_roles for role in required_roles):
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="Insufficient permissions"
            )
        return current_user
    return role_checker

@app.post("/posts")
async def create_post(
    post_data: PostCreate,
    current_user: User = Depends(require_roles(UserRole.AUTHOR, UserRole.ADMIN))
):
    # Только авторы и админы могут создавать посты
    return {"message": "Post created"}

Задачи для закрепления

Задача 1. Реализуй эндпоинт /register для создания нового пользователя с хешированием пароля.

Задача 2. Добавь проверку, что пользователь активен (disabled = False).

Задача 3. Реализуй refresh-токен.

Задача 4. Добавь роль admin и эндпоинт /admin, доступный только админам.

Задача 5. Защити эндпоинт /users/me с помощью Depends(get_current_active_user).

Ответы:

Задача 1.

@app.post("/register")
async def register_user(username: str, password: str, email: str = None):
    if username in fake_users_db:
        raise HTTPException(status_code=400, detail="Username already exists")
    hashed = get_password_hash(password)
    fake_users_db[username] = {
        "username": username,
        "email": email,
        "hashed_password": hashed,
        "disabled": False,
    }
    return {"message": "User created"}

Задача 2.

async def get_current_active_user(current_user: User = Depends(get_current_user)):
    if current_user.disabled:
        raise HTTPException(status_code=400, detail="Inactive user")
    return current_user

Задача 3.

# Реализован в разделе 2.8

Задача 4.

@app.get("/admin")
async def admin_only(current_user: User = Depends(require_roles(UserRole.ADMIN))):
    return {"message": "Welcome, admin!"}

Задача 5.

@app.get("/users/me")
async def read_users_me(current_user: User = Depends(get_current_active_user)):
    return current_user

Нюансы и подводные камни

Хранение секретов

Храни SECRET_KEY в переменных окружения, а не в коде.

Срок жизни токена

Устанавливай разумный срок жизни access-токена (15–30 минут) . Используй refresh-токены для долгих сессий.

Защита от timing-атак

При проверке пароля всегда используй хеш-функцию (bcrypt/Argon2), которая устойчива к атакам по времени. При проверке существования пользователя используй «пустой» хеш, чтобы время ответа не зависело от того, существует ли пользователь.

JWT не шифрует данные

Никогда не храни пароли и другую чувствительную информацию в JWT. Он подписан, но не зашифрован.

Частые ошибки и как их избежать

Ошибка 1: Хранение SECRET_KEY в коде

Используй переменные окружения или Secret Manager.

Ошибка 2: Слишком долгий срок жизни access-токена

15–30 минут — оптимальный срок.

Ошибка 3: Хранение паролей в открытом виде

Всегда хешируй пароли.

Ошибка 4: Отсутствие проверки `type` у refresh-токенов

Добавляй "type": "refresh" в payload и проверяй при обновлении.

Шпаргалка

Компонент	Назначение
`OAuth2PasswordBearer`	Извлекает токен из заголовка Authorization
`jwt.encode()`	Создаёт JWT токен
`jwt.decode()`	Проверяет и расшифровывает JWT токен
`passlib.CryptContext`	Хеширует и проверяет пароли
`Depends(oauth2_scheme)`	Защищает эндпоинт токеном
`refresh_token`	Используется для получения нового access-токена

Заключение

Сегодня мы:

Узнали, что такое JWT и OAuth2
Реализовали аутентификацию в FastAPI
Создавали и проверяли JWT токены
Добавили refresh-токены и роли

КВИЗ

Что дальше?

Следующая статья: «Тестирование API (Postman, pytest)»