humanoid-login 0.1.0

Django REST Framework JWT authentication with HttpOnly cookies.

humanoid_login

humanoid_login provides production-ready JWT authentication for Django REST Framework using secure HttpOnly cookies. It wraps djangorestframework-simplejwt with ready-made login, logout, refresh, and current-user endpoints so applications can ship cookie-based authentication without duplicating boilerplate.

Developed and maintained by Fardin Ibrahimi, CEO of Humanoid.

Installation

pip install humanoid-login

Quick Start

Add the app and authentication class:

INSTALLED_APPS = [
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "rest_framework",
    "humanoid_login",
]

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "humanoid_login.authentication.CookieJWTAuthentication",
    ],
}

Include the URLs:

from django.urls import include, path

urlpatterns = [
    path("", include("humanoid_login.urls")),
]

Or import views directly:

from humanoid_login.views import LoginView

API Endpoints

Method	Path	Description
POST	/login/	Authenticates credentials, returns user data, and sets access and refresh cookies.
POST	/logout/	Deletes cookies and blacklists the refresh token when SimpleJWT blacklist support is enabled.
POST	/refresh/	Reads the refresh cookie and issues a new access cookie.
GET	/me/	Returns the authenticated user's compact profile.

Login Example

POST /login/
Content-Type: application/json

{
  "email": "[e-mail]",
  "password": "correct-password"
}

Successful responses set HttpOnly cookies and return:

{
  "detail": "Login successful.",
  "user": {
    "id": 1,
    "email": "[e-mail]",
    "name": "John Doe",
    "role": "admin"
  }
}

Configuration

Override defaults in Django settings:

from datetime import timedelta

HUMANOID_LOGIN = {
    "ACCESS_COOKIE": "access_token",
    "REFRESH_COOKIE": "refresh_token",
    "COOKIE_HTTPONLY": True,
    "COOKIE_SECURE": True,
    "COOKIE_SAMESITE": "Lax",
    "COOKIE_PATH": "/",
    "COOKIE_DOMAIN": None,
    "ACCESS_TOKEN_LIFETIME": timedelta(minutes=5),
    "REFRESH_TOKEN_LIFETIME": timedelta(days=1),
    "ROTATE_REFRESH_TOKENS": False,
    "BLACKLIST_AFTER_ROTATION": True,
    "USER_ROLE_ATTRIBUTE": "role",
}

Recommended Production Settings

Use HTTPS and secure cookies in production:

HUMANOID_LOGIN = {
    "COOKIE_SECURE": True,
    "COOKIE_SAMESITE": "Lax",
    "COOKIE_HTTPONLY": True,
}

If your frontend and API are on different sites, configure CORS and CSRF deliberately and choose COOKIE_SAMESITE="None" only with COOKIE_SECURE=True.

Authentication Flow

1. LoginView validates email and password through LoginSerializer.
2. AuthService authenticates with Django's configured authentication backends.
3. SimpleJWT access and refresh tokens are generated.
4. Tokens are stored in configured HttpOnly cookies.
5. CookieJWTAuthentication reads the access cookie and validates it for DRF permissions.
6. RefreshView reads the refresh cookie and issues a new access cookie.
7. LogoutView removes cookies and blacklists refresh tokens when the blacklist app is installed.

Security Notes

• Access and refresh tokens are never returned in response bodies.
• Cookies default to HttpOnly=True.
• Set COOKIE_SECURE=True in production.
• Use short access-token lifetimes and rotate refresh tokens where appropriate.
• Consider enabling SimpleJWT's blacklist app:

INSTALLED_APPS = [
    "rest_framework_simplejwt.token_blacklist",
]

Run migrations after enabling blacklist support:

python manage.py migrate

Testing

pip install -e ".[dev]"
pytest
python -m build

Contributing

Contributions are welcome. Please open an issue for larger changes, include tests for new behavior, and keep authentication changes small, explicit, and documented.

Changelog

0.1.0

• Initial public release.
• Cookie-backed JWT login, logout, refresh, and current-user endpoints.
• Typed package marker and pytest coverage.

About the Author

humanoid_login is an open-source package developed and maintained by Fardin Ibrahimi, CEO of Humanoid, with the goal of making secure JWT cookie authentication effortless for Django REST Framework developers.

---

Documentation maintained by Fardin Ibrahimi, CEO of Humanoid.

humanoid-login