Add Session Management

To manage the user's authenticated state, you'll need to configure Django's session framework with Wristband's encrypted cookie session engine. This stores authentication information in an encrypted cookie, and on subsequent requests, Django automatically decrypts the cookie and restores the session state into the request.session field.

Enable Django Sessions

To enable Django sessions, include the following Django middleware and app in your settings:

# your_project/settings.py

# ...your other settings...

INSTALLED_APPS = [
    # Add session framework
    'django.contrib.sessions',  
    # ... other apps
]

MIDDLEWARE = [
    # Add session middleware
    'django.contrib.sessions.middleware.SessionMiddleware',
    # ... other middleware
]

Configure Encrypted Cookie Sessions

Next, configure Django to use Wristband's encrypted cookie session engine. You'll need to provide a secret (at least 32 characters long) for the WRISTBAND_SESSION_SECRET value. You can generate a secure secret using 1Password's password generator.

⚙️
Disabling Secure Session Cookies in Local Development
By default, session cookies are marked as secure, meaning they are only sent over HTTPS connections. Most browsers make an exception for localhost and allow secure cookies to be sent over HTTP (e.g., http://localhost). However, some browsers, such as Safari, enforce stricter rules and never send secure cookies over HTTP, even for localhost.
If you need to disable the secure flag for local development, set secure=False in SessionMiddleware. However, be sure to restore secure=True in production to protect session data.

# your_project/settings.py

# ...your other settings...

# Wristband encrypted cookie-based sessions
SESSION_ENGINE = 'wristband.django_auth.sessions.backends.encrypted_cookies'
SESSION_COOKIE_AGE = 3600  # Cookies expires after 1 hour of inactivity
SESSION_COOKIE_SECURE = True  # Ensures the cookie is only sent over HTTPS
SESSION_COOKIE_HTTPONLY = True  # Prevents JavaScript access to session cookie
SESSION_COOKIE_SAMESITE = 'Lax'  # Protects againsts CSRF

# Session encryption secret (32+ characters recommended)
# IMPORTANT: In production, use a strong, randomly-generated secret!
WRISTBAND_SESSION_SECRET = 'your-secret-key-at-least-32-characters-long'

# your_project/settings.py

# ...your other settings...

# Wristband encrypted cookie-based sessions
SESSION_ENGINE = 'wristband.django_auth.sessions.backends.encrypted_cookies'
SESSION_COOKIE_AGE = 3600
SESSION_COOKIE_SECURE = False  # IMPORTANT: Set to True in production!
SESSION_COOKIE_HTTPONLY = True
SESSION_COOKIE_SAMESITE = 'Lax'
WRISTBAND_SESSION_SECRET = 'your-secret-key-at-least-32-characters-long'