JWTGuard — учебно-инженерный backend-проект на Django REST Framework,
реализующий управляемую JWT-аутентификацию с использованием PyJWT, RS256, Redis и PostgreSQL.
- JWTGuard — управляемая JWT-аутентификация на Django, PyJWT и Redis
Классический JWT часто используется как полностью stateless credential.
Такой подход прост, но ограничивает возможности управления сессиями:
- сложно выполнить logout до истечения токена;
- сложно отозвать конкретную сессию;
- сложно обнаружить повторное использование refresh token;
- сложно централизованно управлять активными пользовательскими сессиями.
В этом проекте используется гибридный подход:
JWT = переносимый authentication credential
Redis = источник актуального состояния сессии
ℹ️ JWT остаётся удобным форматом передачи identity-данных, но окончательное решение о валидности сессии принимается с учётом состояния в Redis.
- собственная генерация и проверка JWT через
PyJWT; - асимметричная подпись токенов через
RS256; - Redis-backed session state;
- пара токенов access / refresh;
- refresh token whitelist;
- access / refresh blacklist;
- atomic refresh rotation;
- refresh token reuse detection;
- регистрация пользователя;
- login по email/password;
- logout текущей сессии;
- logout всех сессий пользователя;
- демонстрационная ролевая модель через Django Groups;
- защищённый content API;
- Docker-окружение для локального запуска;
- тесты основных auth-flow сценариев.
- Python 3.12
- Django
- Django REST Framework
- PyJWT
- Redis
- PostgreSQL
- Docker / Docker Compose
- Pytest
- drf-spectacular
Для быстрого запуска выполните следующие команды:
git clone https://github.com/NikPACodes/JWTGuard.git
cd JWTGuard
cp .env.example .env.dev
make keys
make build
make up-d
make migrate
make demoПосле этого проект будет готов к локальной проверке.
ℹ️ Подробная инструкция — DEVELOPMENT
Проект использует RS256, поэтому для работы JWT нужны private/public RSA-ключи.
Сгенерировать ключи можно командой:
make keysПроверить соответствие private/public key:
make verify-keysPrivate key используется для подписи токенов.
Public key используется для проверки токенов.
Основные команды проекта:
make build # собрать Docker-образы
make up-d # запустить контейнеры в background
make down # остановить контейнеры
make logs # логи app-контейнера
make ps # статус контейнеров
make migrate # применить миграции
make demo # создать demo-данные
make tests # запустить тесты
make check # выполнить django check
make keys # сгенерировать RSA-ключи
...ℹ️ Полный список команд с пояснениями — DEVELOPMENT
GET /api/auth/health/
POST /api/auth/register/
POST /api/auth/login/
POST /api/auth/refresh/
POST /api/auth/logout/
POST /api/auth/logout-all/
GET /api/auth/profile/
GET /api/content/health/
GET /api/content/
GET /api/content/{id}/
GET /api/schema/
GET /api/schema/swagger/
GET /api/schema/redoc/
ℹ️ Примеры запросов — API_EXAMPLES
Проект использует стандартные Django Groups для демонстрационной RBAC-модели.
Команда создания тестовых ролей и демонстрационного контента:
make demoℹ️ Content API возвращает только тот контент, который доступен группам текущего пользователя.
Запуск тестов:
make testsТестами покрываются основные сценарии:
- login;
- registration;
- access token validation;
- refresh rotation;
- atomic refresh rotation;
- refresh token reuse detection;
- logout;
- logout all sessions;
- token store;
- role-based content access.
Проект намеренно не хранит access token в whitelist.
Access token:
- короткоживущий;
- проверяется по RS256-подписи;
- проверяется по expiration;
- проверяется по blacklist;
- проверяется через Redis session state;
- должен соответствовать
session.access_jti.
Такой подход позволяет сохранить управляемость сессий без необходимости хранить каждый access token в отдельном whitelist.
Подробное объяснение находится в ARCHITECTURE и SECURITY_MODEL.
Проект является учебно-инженерным примером и не претендует на готовую production-auth платформу.
Для production-использования дополнительно потребуются:
- HTTPS;
- защищённое хранение private key;
- ротация RSA ключей;
- rate limiting;
- audit logging security-событий;
- мониторинг Redis;
- защита Redis от внешнего доступа;
- alerting при refresh token reuse detection;
- политика управления security incidents.
LICENSE ── Условия использования и распространения проекта.
CONTRIBUTING ── Как сообщать об ошибках и уязвимостях.
SECURITY ── Политика безопасности.
DEVELOPMENT ── Локальный запуск, Docker, Makefile-команды и тесты.
ARCHITECTURE ── Описание общей архитектуры проекта.
JWT_FLOW ── Жизненный цикл токенов и auth-flow.
SECURITY_MODEL ── Модель безопасности, угрозы и ограничения.
API_EXAMPLES ── Примеры API-запросов.
BRUNO ── Коллекция Bruno для воспроизведения Auth, Content и Security сценариев.
ℹ️ Этот репозиторий является общедоступным образовательным/справочным проектом только для чтения.
Подробности см. в CONTRIBUTING и SECURITY.
Проект считается завершённым в рамках текущей цели:
показать управляемую JWT-аутентификацию на Django, DRF, PyJWT, RS256 и Redis.
На основе проекта готовится инженерная статья о реализации продвинутого JWT-flow:
- refresh rotation;
- blacklist / whitelist;
- refresh token reuse detection;
- atomic token rotation.
Архитектура проекта допускает дальнейшее развитие JWT-ядра в независимый auth-service, но это будет реализовываться в рамках отдельного проекта.