Django Sesame

Common errors

• django.contrib.auth.backends.ModelBackend.authenticate() received an unexpected keyword argument 'url_auth_token'

  cause Using the deprecated `url_auth_token` argument with `authenticate()` after upgrading to `django-sesame` v2.0 or later.
  fix Update your code to use the `sesame` keyword argument: `user = authenticate(request, sesame=token_value)`.

• Magic link works once, then fails subsequent attempts, even if 'SESAME_ONE_TIME' is False.

  cause If `SESAME_ONE_TIME` is enabled (even implicitly if not explicitly `False`) and the user's `last_login` field is updated by another login mechanism or `authenticate(update_last_login=True)`, the token becomes invalid.
  fix Ensure `SESAME_ONE_TIME = False` explicitly in settings if tokens should be reusable. If you need reusable tokens and also update `last_login` through other means, consider setting `SESAME_INVALIDATE_ON_PASSWORD_CHANGE = False` (with security review) or regenerate tokens.

Warnings

• breaking Changing most Django Sesame settings (e.g., `SECRET_KEY`, `SESAME_TOKEN_NAME`, `SESAME_TOKENS`) will invalidate all previously generated authentication tokens.
  Fix: Configure all Django Sesame settings carefully before generating tokens in a production environment. If settings must change, regenerate and redistribute new tokens.
• breaking Upgrading Django versions can invalidate existing magic links/tokens, particularly long-lived ones. This is because Django's password hashers increase their work factor with new releases, making a password hash upgrade indistinguishable from a password change to `django-sesame`.
  Fix: After a Django upgrade, regenerate and redistribute new tokens. Alternatively, for long-lived tokens, consider setting `SESAME_INVALIDATE_ON_PASSWORD_CHANGE = False` in `settings.py`, but be aware of the security implications.
• gotcha One-time tokens (`SESAME_ONE_TIME = True`) can fail if sent via email, as email providers often fetch links for previews or security scans, consuming the token before the actual user clicks it.
  Fix: Instead of `SESAME_ONE_TIME`, consider using a short `SESAME_MAX_AGE` (e.g., 5-10 minutes) for login-by-email scenarios to balance security and usability.
• gotcha Safari's 'Protection Against First Party Bounce Trackers' can cause issues (clearing cookies, logging out users) when `django-sesame` redirects after successful authentication.
  Fix: Install the `ua-parser` package (`pip install ua-parser`). `django-sesame` will then use it to detect Safari and avoid the problematic redirect.
• gotcha The primary keys of users are stored in clear text within tokens. While this is not inherently a security flaw if the token is secure, it's a privacy consideration.
  Fix: If this is a concern, consider customizing primary keys or carefully review the use case for magic links.

Install

• pip install django-sesame Basic Installation
• pip install django-sesame[ua] With User-Agent Parsing (for Safari)

Imports

• get_query_string

  from sesame.utils import get_query_string

  Used to generate a URL query string containing an authentication token for a given user.
• get_user

  from sesame.utils import get_user

  Used in custom view logic to authenticate a user based on a token found in the request.
• LoginView

  from sesame.views import LoginView

  A class-based view that handles token validation and user login, similar to Django's built-in LoginView.
• ModelBackend

  from sesame.backends import ModelBackend

  The authentication backend to be added to Django's AUTHENTICATION_BACKENDS setting.
• authenticate (decorator)

  from sesame.decorators import authenticate

  A view decorator to authenticate a user for a specific view using a token.
• authenticate (function)
  wrong:

  user = authenticate(url_auth_token=token_value)

  correct:

  from django.contrib.auth import authenticate
  user = authenticate(request, sesame=token_value)

  The `url_auth_token` argument was deprecated and removed in favor of `sesame` in version 2.0.

Quickstart

To quickly integrate `django-sesame`, first configure your Django `settings.py` by adding `sesame.backends.ModelBackend` to `AUTHENTICATION_BACKENDS`. Then, define a URL route for `sesame.views.LoginView` in your `urls.py`. You can then generate magic links using `sesame.utils.get_query_string(user)` and send them to users. Visiting this link will log the user in. You can also configure `SESAME_MAX_AGE` for token lifetime and mark user passwords as unusable if they'll only use magic links.

import os
from django.contrib.auth import get_user_model
from django.urls import path
from sesame.views import LoginView
from sesame.utils import get_query_string

# --- Django settings.py (example additions) ---
# AUTHENTICATION_BACKENDS = [
#     'django.contrib.auth.backends.ModelBackend',
#     'sesame.backends.ModelBackend',
# ]
# # Optional: Configure token lifetime (e.g., 10 minutes for login by email)
# import datetime
# SESAME_MAX_AGE = datetime.timedelta(minutes=10)

# --- Your app's urls.py (example) ---
urlpatterns = [
    path("sesame/login/", LoginView.as_view(), name="sesame-login"),
]

# --- Example usage in a view or script ---
User = get_user_model()

# Create or get a user (e.g., for 'jane.doe@example.com')
try:
    user = User.objects.get(email="jane.doe@example.com")
except User.DoesNotExist:
    user = User.objects.create_user("jane.doe", "jane.doe@example.com", "password123")
    user.set_unusable_password() # If only using magic links, make password unusable
    user.save()

# Assuming a base URL like 'http://127.0.0.1:8000'
base_url = os.environ.get('DJANGO_BASE_URL', 'http://127.0.0.1:8000')
login_path = '/sesame/login/'

# Generate a magic link
magic_link = base_url + login_path + get_query_string(user)

print(f"Magic link for {user.email}: {magic_link}")

# To test, manually visit this link in a browser while logged out.