Skip to content
NikPACodesPublic

About

JWTGuard — управляемая JWT-аутентификация на Django, PyJWT и Redis.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

🔐 JWTGuard — управляемая JWT-аутентификация на Django, PyJWT и Redis

JWTGuard — учебно-инженерный backend-проект на Django REST Framework, реализующий управляемую JWT-аутентификацию с использованием PyJWT, RS256, Redis и PostgreSQL.


Оглавление


🎯 Идея проекта

Классический 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


🔑 RSA-ключи

Проект использует RS256, поэтому для работы JWT нужны private/public RSA-ключи.

Сгенерировать ключи можно командой:

make keys

Проверить соответствие private/public key:

make verify-keys

Private key используется для подписи токенов.
Public key используется для проверки токенов.

⚠️ ️️Файлы ключей не должны попадать в Git.


📜 Makefile-команды

Основные команды проекта:

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


🌐 API endpoints

Auth

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/

Content

GET /api/content/health/
GET /api/content/
GET /api/content/{id}/

API documentation

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 whitelist

Проект намеренно не хранит 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-запросов.

🧪 Ручное тестирование API

BRUNO ── Коллекция Bruno для воспроизведения Auth, Content и Security сценариев.


🏛️ Политика репозитория

ℹ️ Этот репозиторий является общедоступным образовательным/справочным проектом только для чтения.

⚠️ Запросы на слияние (pull requests) не принимаются. Сообщения об ошибках (issues) принимаются только для воспроизводимых ошибок.
⚠️ Запросы на добавление новых функций, предложения по рефакторингу, обсуждения архитектуры, вопросы поддержки и запросы на адаптацию не принимаются.
⚠️ Будущие изменения ограничиваются исправлением ошибок, корректировкой документации и исправлениями, связанными с безопасностью, если это необходимо.

Подробности см. в CONTRIBUTING и SECURITY.


🚀 Перспективы развития

Проект считается завершённым в рамках текущей цели: показать управляемую JWT-аутентификацию на Django, DRF, PyJWT, RS256 и Redis.

На основе проекта готовится инженерная статья о реализации продвинутого JWT-flow:

  • refresh rotation;
  • blacklist / whitelist;
  • refresh token reuse detection;
  • atomic token rotation.

Архитектура проекта допускает дальнейшее развитие JWT-ядра в независимый auth-service, но это будет реализовываться в рамках отдельного проекта.

About

JWTGuard — управляемая JWT-аутентификация на Django, PyJWT и Redis.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages