repository·main·Indexed 21 days ago
https://github.com/aaugustin/django-sesameProvides frictionless, stateless, token-based authentication for Django projects, commonly used to implement 'Magic Links'. It supports expiring and single-use tokens, scoped tokens for restricted resource access, and integration via middleware, decorators, or a dedicated LoginView. Compatible with custom user models and Django versions 4.2, 5.0, 5.1, and 5.2.
django-sesame is compatible with custom user models, provided they include the password and last_login fields. These fields are standard in any model inheriting from django.contrib.auth.models.AbstractBaseUser.To prevent a token created for one purpose from being reused for another, you can assign a scope to tokens. A token is only valid if the same scope used during generation is provided during authentication.
Key Rules:
"")."report:66") are not valid in the default scope.sesame.middleware.AuthenticationMiddleware does not support scopes; it only accepts tokens generated with the default scope.>>> # Generating a scoped token
>>> from sesame.utils import get_token
>>> get_token(user, scope="report:66")
'jISWHmrXr4zg8FHVZZuxhpHs'django-sesame tokens are constructed using the following components:
SESAME_MAX_AGE is enabled.SESAME_INVALIDATE_ON_PASSWORD_CHANGE is False).SESAME_INVALIDATE_ON_EMAIL_CHANGE is True).SESAME_ONE_TIME is True).SESAME_SIGNATURE_SIZE (1-64 bytes).Signer or TimestampSigner.By default, SESAME_TOKENS is set to ["sesame.tokens_v2", "sesame.tokens_v1"], meaning the system generates v2 tokens but accepts both v2 and v1.
django-sesame supports several stateless, token-based authentication patterns:
SESAME_MAX_AGE (e.g., 10 minutes).SESAME_MAX_AGE (e.g., a few days). Note: To prevent email forwarding from logging a user into the whole site, ensure these links only grant access to specific views rather than performing a full session login.Tokens can be invalidated through several mechanisms:
SESAME_MAX_AGE. Once the lifetime expires, the token is rejected.SESAME_ONE_TIME to invalidate a token immediately after its first successful use. This works by tying the token to the user's last login date; authenticating the token updates that date, rendering the token invalid. Note: Using short-lived tokens is generally recommended over single-use tokens due to the risk of accidental invalidation (e.g., if a user logs in via another method).SESAME_INVALIDATE_ON_PASSWORD_CHANGE = False.SESAME_INVALIDATE_ON_EMAIL_CHANGE = True to invalidate tokens when a user's email is updated.is_active attribute is set to False, all their tokens are rejected.SESAME_KEY setting.SESAME_SALT setting.django-sesame is compatible with Django REST framework (DRF), but for DRF-specific implementations, it is recommended to use DRF's built-in TokenAuthentication or other recommended alternatives.The sesame.middleware.AuthenticationMiddleware provides site-wide authentication. When a valid token is found in a URL, the user is logged in automatically, and the token is removed from the URL via an HTTP 302 Redirect. This allows users to access views protected by login_required or LoginRequiredMixin using a single click.
Setup:
Add the middleware to your MIDDLEWARE setting immediately after Django's built-in AuthenticationMiddleware.
Note for Safari users:
You must install the ua extra to ensure compatibility with Safari:
pip install 'django-sesame[ua]'
MIDDLEWARE = [
...,
"django.contrib.auth.middleware.AuthenticationMiddleware",
"sesame.middleware.AuthenticationMiddleware",
...,
]To enable token-based authentication, add sesame.backends.ModelBackend to your AUTHENTICATION_BACKENDS setting in settings.py. You should typically keep the default django.contrib.auth.backends.ModelBackend as well.
AUTHENTICATION_BACKENDS = [
"django.contrib.auth.backends.ModelBackend",
"sesame.backends.ModelBackend",
]To validate a token that was generated with a specific scope, you must provide that same scope when authenticating. You can do this using get_user, the authenticate decorator, or the LoginView.
from sesame.utils import get_user
# Manual check
def share_report(request, report_id):
user = get_user(request, scope=f"report:{report_id}")
if user is None:
raise PermissionDenied
...
# Using the decorator
from sesame.decorators import authenticate
@authenticate(scope="report:{report_id}")
def share_report(request, report_id):
...If your primary key is not an integer or UUID (e.g., a custom string), the default binary representation might be inefficient. You can implement a custom packer by subclassing sesame.packers.BasePacker and setting SESAME_PACKER to the dotted Python path of your class.
Example of a packer for 24-character hexadecimal strings:
from sesame.packers import BasePacker
class Packer(BasePacker):
@staticmethod
def pack_pk(user_pk):
assert len(user_pk) == 24
return bytes.fromhex(user_pk)
@staticmethod
def unpack_pk(data):
return data[:12].hex(), data[12:]
# In settings.py:
# SESAME_PACKER = 'path.to.your.module.Packer'django-sesame requires a compatible authentication backend to be added to your AUTHENTICATION_BACKENDS setting.
It provides:
sesame.backends.ModelBackend: A standard backend implementation.sesame.backends.SesameBackendMixin: A mixin that provides the authenticate method for custom backends.Install the package using pip.
$ pip install django-sesame