Add Session Management

To manage a user's authenticated state, configure Django's session framework with the Wristband encrypted cookie session engine. This stores session data securely via encrypted cookies, allowing Django to decrypt the cookie and restore session state automatically into request.sessionon later requests.

Enable Django Sessions

Include the following Django middleware and app in your settings to enable Django sessions:

# 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

To configure Django for Wristband's encrypted cookie session engine, define WRISTBAND_SESSION_SECRET with a strong, 32+ character key generated using the Secure Password Generator.

📘
Disabling Secure Session Cookies in Local Development
By default, session cookies are marked as secure and are only transmitted over HTTPS. Most browsers allow secure cookies to be used over unencrypted HTTP connections on localhost, but browsers such as Safari enforce this requirement and may drop these cookies.
For local testing, set secure=False in your SessionMiddlewareconfiguration. Remember to change it back to secure=True before deploying to production.

# 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'

Enable Django Sessions

Configure Encrypted Cookie Sessions

Disabling Secure Session Cookies in Local Development

What’s Next