📣 Wristband Django Auth SDK 1.0.0 Release 🎉

Release v1.0.0

Breaking Changes

Migration Guide: https://github.com/wristband-dev/django-auth/blob/main/migration/v1/README.md

🔄 CallbackResult Structure Changes

The CallbackResult model now uses a discriminated union pattern with explicit variant types.

Migration:

• Use isinstance() checks instead of comparing callback_result.type
• Import new result types: CompletedCallbackResult, RedirectRequiredCallbackResult
• No more assert statements needed - type narrowing is automatic
• New reason field added to RedirectRequiredCallbackResult

📝 Query Parameter and URL Placeholder Standardization

Query Parameters:

• tenant_domain → tenant_name

URL Placeholders:

• {tenant_domain} → {tenant_name} ({tenant_domain} is deprecated but still supported for backward compatibility)

🗄️ Session Management Changes

Session Engine:

• New encrypted cookie-based session engine: wristband.django_auth.sessions.backends.encrypted_cookies
• Session fields now stored directly in request.session instead of nested under request.session['wristband']
• New session_from_callback() helper function for populating sessions

Session Configuration:

• WRISTBAND_SESSION_SECRET required for encrypted cookie sessions
• Session fields include is_authenticated flag for authentication validation

🛡️ Authentication Protection Changes

Removed:

• @wristband_auth_required decorator removed
• WristbandAuthRequiredMixin mixin removed

New Factory Methods:

• create_auth_decorator() - Create configurable authentication decorators
• create_auth_mixin() - Create configurable authentication mixins
• create_drf_session_auth() - Create Django REST Framework session authentication classes
• create_drf_jwt_auth() - Create Django REST Framework JWT authentication classes

Migration:

• Authentication logic now embedded in decorators/mixins instead of custom middleware
• Must explicitly create decorator/mixin instances with desired strategy and behavior
• No need to write or maintain custom authentication middleware

👤 Django User Synchronization Changes

New Authentication Backend:

• WristbandAuthBackend handles automatic User creation and synchronization
• Adapter pattern for customizing user field mapping and role synchronization

Migration:

• Add wristband.django_auth.WristbandAuthBackend to AUTHENTICATION_BACKENDS
• Use authenticate() and login() instead of manual User object creation
• Create custom adapter class for role mapping instead of inline logic
• Must include profile and roles scopes for full User synchronization

New Features

🔐 JWT Authentication Support

New JWT bearer token authentication powered by @wristband/python-jwt.

Features:

• Stateless JWT validation with JWKS
• Configurable JWK cache size and TTL
• Decoded JWT payload available in request.auth.payload
• Raw JWT string available in request.auth.jwt
• Full type safety with TypedDict models

✨ Multi-Strategy Authentication

Support multiple authentication strategies with fallback behavior.

Supported Strategies:

• SESSION - Django session authentication with automatic token refresh
• JWT - Bearer token authentication with JWKS validation

Features:

• Try multiple strategies in order until one succeeds
• Automatic access token refresh for expired tokens (SESSION strategy)
• Automatic CSRF token refresh for rolling sessions (SESSION strategy)
• Rolling session windows (SESSION strategy)
• Configurable JWKS caching (JWT strategy)

🔄 Callback Failure Reasons

CallbackResult now includes a reason field when isinstance(callback_result, RedirectRequiredCallbackResult):

• MISSING_LOGIN_STATE - Login state cookie not found
• INVALID_LOGIN_STATE - Login state validation failed
• LOGIN_REQUIRED - Wristband returned login_required error
• INVALID_GRANT - Authorization code was invalid or expired

🌐 Django REST Framework Support

New DRF Authentication Classes:

• create_drf_session_auth() - Session-based authentication for DRF
• create_drf_jwt_auth() - JWT-based authentication for DRF

Features:

• Native DRF authentication_classes support
• Combine multiple authentication strategies in single view
• Works with DRF's IsAuthenticated permission
• Requires djangorestframework>=3.15.0

📦 Enhanced Session Management

New Helper Functions:

• session_from_callback() - Populate session from callback data
• get_session_response() - Create session response for frontend SDKs
• get_token_response() - Create token response for frontend SDKs

New Session Engine:

• Encrypted cookie-based sessions with AES-256-GCM
• Stateless session storage with no database required
• Configurable session expiration and cookie security

🎯 Authentication Backend and Adapters

New Components:

• WristbandAuthBackend - Django authentication backend for Wristband
• DefaultWristbandAuthBackendAdapter - Default user field mapping
• Custom adapter pattern for role mapping and permissions

Features:

• Automatic Django User creation and synchronization
• Customizable user field mapping via adapters
• Role-based group and permission assignment
• Support for passing custom data to adapters via **kwargs

For full documentation, see the README.