0
# User Session Management
1

2
Multi-device session tracking, session metadata collection, and cross-device logout capabilities. Provides visibility and control over user sessions across different devices and browsers for enhanced security and user experience.
3

4
## Capabilities
5

6
### Models
7

8
Core models for tracking and managing user sessions across devices.
9

10
```python { .api }
11
class UserSession(models.Model):
12
    """
13
    Track user sessions across devices and browsers.
14
    """
15
    user: User = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
16
    ip: str = models.GenericIPAddressField()
17
    user_agent: str = models.TextField()
18
    created_at: datetime = models.DateTimeField(auto_now_add=True)
19
    last_seen_at: datetime = models.DateTimeField(auto_now=True)
20
    session_key: str = models.CharField(max_length=40, unique=True)
21
    
22
    def __str__(self) -> str: ...
23
    def get_device_info(self) -> Dict[str, str]: ...
24
    def get_location_info(self) -> Dict[str, str]: ...
25
    def is_current_session(self, request: HttpRequest) -> bool: ...
26
    def end_session(self) -> None: ...
27

28
class UserSessionActivity(models.Model):
29
    """
30
    Track detailed activity within user sessions.
31
    """
32
    session: UserSession = models.ForeignKey(UserSession, on_delete=models.CASCADE)
33
    timestamp: datetime = models.DateTimeField(auto_now_add=True)
34
    path: str = models.CharField(max_length=500)
35
    method: str = models.CharField(max_length=10)
36
    status_code: int = models.IntegerField()
37
    
38
    def __str__(self) -> str: ...
39
```
40

41
### Views
42

43
Django views for session management and monitoring.
44

45
```python { .api }
46
class SessionsView(TemplateView):
47
    """
48
    View for displaying user's active sessions.
49
    """
50
    template_name: str = "usersessions/sessions.html"
51
    
52
    def get_context_data(self, **kwargs) -> Dict[str, Any]: ...
53

54
class EndSessionView(View):
55
    """
56
    End a specific user session.
57
    """
58
    
59
    def post(self, request: HttpRequest, session_id: int) -> HttpResponse: ...
60

61
class EndAllSessionsView(View):
62
    """
63
    End all user sessions except current one.
64
    """
65
    
66
    def post(self, request: HttpRequest) -> HttpResponse: ...
67

68
class SessionDetailView(DetailView):
69
    """
70
    Detailed view of a specific session.
71
    """
72
    model: type = UserSession
73
    template_name: str = "usersessions/session_detail.html"
74
    context_object_name: str = "session"
75
    
76
    def get_queryset(self) -> QuerySet: ...
77
```
78

79
### Middleware
80

81
Middleware for automatic session tracking and management.
82

83
```python { .api }
84
class UserSessionMiddleware:
85
    """
86
    Middleware to track user sessions automatically.
87
    """
88
    
89
    def __init__(self, get_response: Callable): ...
90
    
91
    def __call__(self, request: HttpRequest) -> HttpResponse: ...
92
    
93
    def process_request(self, request: HttpRequest) -> None:
94
        """
95
        Process incoming request for session tracking.
96
        
97
        Parameters:
98
        - request: HTTP request object
99
        """
100
    
101
    def process_response(self, request: HttpRequest, response: HttpResponse) -> HttpResponse:
102
        """
103
        Process response for session activity logging.
104
        
105
        Parameters:
106
        - request: HTTP request object
107
        - response: HTTP response object
108
        
109
        Returns:
110
        HTTP response object
111
        """
112
```
113

114
### Session Management
115

116
Core functions for session creation, tracking, and management.
117

118
```python { .api }
119
def create_user_session(request: HttpRequest, user: User) -> UserSession:
120
    """
121
    Create a new user session record.
122
    
123
    Parameters:
124
    - request: HTTP request object
125
    - user: User instance
126
    
127
    Returns:
128
    UserSession instance
129
    """
130

131
def get_user_session(request: HttpRequest) -> Optional[UserSession]:
132
    """
133
    Get current user session from request.
134
    
135
    Parameters:
136
    - request: HTTP request object
137
    
138
    Returns:
139
    UserSession instance if found, None otherwise
140
    """
141

142
def update_session_activity(request: HttpRequest, response: HttpResponse = None) -> None:
143
    """
144
    Update session activity with request details.
145
    
146
    Parameters:
147
    - request: HTTP request object
148
    - response: Optional HTTP response object
149
    """
150

151
def end_user_session(session: UserSession) -> None:
152
    """
153
    End a specific user session.
154
    
155
    Parameters:
156
    - session: UserSession instance to end
157
    """
158

159
def end_all_user_sessions(user: User, except_session: UserSession = None) -> int:
160
    """
161
    End all sessions for a user.
162
    
163
    Parameters:
164
    - user: User instance
165
    - except_session: Optional session to preserve
166
    
167
    Returns:
168
    Number of sessions ended
169
    """
170

171
def cleanup_expired_sessions(days: int = 30) -> int:
172
    """
173
    Clean up expired/inactive sessions.
174
    
175
    Parameters:
176
    - days: Number of days to consider as expired
177
    
178
    Returns:
179
    Number of sessions cleaned up
180
    """
181
```
182

183
### Device Detection
184

185
Device and browser detection utilities.
186

187
```python { .api }
188
def parse_user_agent(user_agent: str) -> Dict[str, str]:
189
    """
190
    Parse user agent string for device information.
191
    
192
    Parameters:
193
    - user_agent: User agent string
194
    
195
    Returns:
196
    Dictionary with device information:
197
    - browser: Browser name and version
198
    - os: Operating system name and version
199
    - device: Device type (desktop, mobile, tablet)
200
    - is_mobile: Boolean indicating mobile device
201
    - is_tablet: Boolean indicating tablet device
202
    """
203

204
def get_client_ip(request: HttpRequest) -> str:
205
    """
206
    Get client IP address from request.
207
    
208
    Parameters:
209
    - request: HTTP request object
210
    
211
    Returns:
212
    Client IP address string
213
    """
214

215
def get_location_from_ip(ip: str) -> Dict[str, str]:
216
    """
217
    Get approximate location from IP address.
218
    
219
    Parameters:
220
    - ip: IP address string
221
    
222
    Returns:
223
    Dictionary with location information:
224
    - country: Country name
225
    - region: Region/state name
226
    - city: City name
227
    - timezone: Timezone identifier
228
    """
229
```
230

231
### Security Features
232

233
Security-related session management features.
234

235
```python { .api }
236
def detect_suspicious_activity(user: User) -> List[Dict[str, Any]]:
237
    """
238
    Detect suspicious session activity for user.
239
    
240
    Parameters:
241
    - user: User instance
242
    
243
    Returns:
244
    List of suspicious activity indicators
245
    """
246

247
def require_session_verification(user: User, threshold_hours: int = 24) -> bool:
248
    """
249
    Check if user requires session verification based on activity.
250
    
251
    Parameters:
252
    - user: User instance
253
    - threshold_hours: Hours since last activity to require verification
254
    
255
    Returns:
256
    True if verification required
257
    """
258

259
def send_new_session_notification(user: User, session: UserSession) -> None:
260
    """
261
    Send notification for new session login.
262
    
263
    Parameters:
264
    - user: User instance
265
    - session: New UserSession instance
266
    """
267

268
def log_security_event(user: User, event_type: str, details: Dict[str, Any]) -> None:
269
    """
270
    Log security-related session events.
271
    
272
    Parameters:
273
    - user: User instance
274
    - event_type: Type of security event
275
    - details: Event details dictionary
276
    """
277
```
278

279
### Analytics and Reporting
280

281
Session analytics and reporting utilities.
282

283
```python { .api }
284
def get_session_statistics(user: User, days: int = 30) -> Dict[str, Any]:
285
    """
286
    Get session statistics for user.
287
    
288
    Parameters:
289
    - user: User instance
290
    - days: Number of days to analyze
291
    
292
    Returns:
293
    Dictionary with session statistics:
294
    - total_sessions: Total number of sessions
295
    - active_sessions: Currently active sessions
296
    - unique_devices: Number of unique devices
297
    - unique_locations: Number of unique locations
298
    - average_session_duration: Average session length
299
    """
300

301
def get_device_usage_report(user: User) -> List[Dict[str, Any]]:
302
    """
303
    Get device usage report for user.
304
    
305
    Parameters:
306
    - user: User instance
307
    
308
    Returns:
309
    List of device usage statistics
310
    """
311

312
def generate_session_activity_report(user: User, start_date: datetime, end_date: datetime) -> Dict[str, Any]:
313
    """
314
    Generate detailed session activity report.
315
    
316
    Parameters:
317
    - user: User instance
318
    - start_date: Report start date
319
    - end_date: Report end date
320
    
321
    Returns:
322
    Comprehensive activity report dictionary
323
    """
324
```
325

326
## Usage Examples
327

328
### Basic Session Tracking
329

330
```python
331
from allauth.usersessions.models import UserSession
332
from allauth.usersessions.utils import create_user_session, get_user_session
333

334
# Create session on login
335
def login_user(request, user):
336
    # Standard Django login
337
    login(request, user)
338
    
339
    # Create session tracking
340
    user_session = create_user_session(request, user)
341
    print(f"Session created: {user_session.session_key}")
342

343
# Get current session
344
current_session = get_user_session(request)
345
if current_session:
346
    print(f"Current session from {current_session.ip}")
347
    print(f"Device: {current_session.get_device_info()}")
348
```
349

350
### Session Management in Views
351

352
```python
353
from allauth.usersessions.models import UserSession
354
from allauth.usersessions.utils import end_user_session, end_all_user_sessions
355

356
class UserSessionsView(LoginRequiredMixin, TemplateView):
357
    template_name = 'account/sessions.html'
358
    
359
    def get_context_data(self, **kwargs):
360
        context = super().get_context_data(**kwargs)
361
        context['sessions'] = UserSession.objects.filter(
362
            user=self.request.user
363
        ).order_by('-last_seen_at')
364
        return context
365

366
class EndSessionView(LoginRequiredMixin, View):
367
    def post(self, request, session_id):
368
        try:
369
            session = UserSession.objects.get(
370
                id=session_id, 
371
                user=request.user
372
            )
373
            end_user_session(session)
374
            messages.success(request, "Session ended successfully")
375
        except UserSession.DoesNotExist:
376
            messages.error(request, "Session not found")
377
        
378
        return redirect('account_sessions')
379

380
class EndAllSessionsView(LoginRequiredMixin, View):
381
    def post(self, request):
382
        current_session = get_user_session(request)
383
        count = end_all_user_sessions(request.user, except_session=current_session)
384
        messages.success(request, f"Ended {count} sessions")
385
        return redirect('account_sessions')
386
```
387

388
### Device Detection
389

390
```python
391
from allauth.usersessions.device import parse_user_agent, get_client_ip
392

393
# Parse user agent
394
user_agent = request.META.get('HTTP_USER_AGENT', '')
395
device_info = parse_user_agent(user_agent)
396

397
print(f"Browser: {device_info['browser']}")
398
print(f"OS: {device_info['os']}")
399
print(f"Device Type: {device_info['device']}")
400
print(f"Is Mobile: {device_info['is_mobile']}")
401

402
# Get client IP
403
client_ip = get_client_ip(request)
404
print(f"Client IP: {client_ip}")
405

406
# Get location (requires IP geolocation service)
407
location = get_location_from_ip(client_ip)
408
print(f"Location: {location['city']}, {location['country']}")
409
```
410

411
### Security Monitoring
412

413
```python
414
from allauth.usersessions.security import (
415
    detect_suspicious_activity,
416
    send_new_session_notification,
417
    log_security_event
418
)
419

420
# Check for suspicious activity
421
suspicious_activities = detect_suspicious_activity(user)
422
if suspicious_activities:
423
    for activity in suspicious_activities:
424
        print(f"Suspicious: {activity['type']} - {activity['description']}")
425
        log_security_event(user, activity['type'], activity)
426

427
# Send notification for new session
428
def on_new_session(sender, user, session, **kwargs):
429
    device_info = session.get_device_info()
430
    if device_info['device'] != 'desktop':
431
        send_new_session_notification(user, session)
432

433
# Connect to login signal
434
from django.contrib.auth.signals import user_logged_in
435
user_logged_in.connect(on_new_session)
436
```
437

438
### Session Analytics
439

440
```python
441
from allauth.usersessions.analytics import (
442
    get_session_statistics,
443
    get_device_usage_report,
444
    generate_session_activity_report
445
)
446

447
# Get session statistics
448
stats = get_session_statistics(user, days=30)
449
print(f"Total sessions: {stats['total_sessions']}")
450
print(f"Active sessions: {stats['active_sessions']}")
451
print(f"Unique devices: {stats['unique_devices']}")
452
print(f"Average duration: {stats['average_session_duration']}")
453

454
# Device usage report
455
device_report = get_device_usage_report(user)
456
for device in device_report:
457
    print(f"{device['name']}: {device['session_count']} sessions")
458

459
# Detailed activity report
460
from datetime import datetime, timedelta
461
end_date = datetime.now()
462
start_date = end_date - timedelta(days=7)
463

464
activity_report = generate_session_activity_report(user, start_date, end_date)
465
print(f"Page views: {activity_report['page_views']}")
466
print(f"Most active hours: {activity_report['peak_hours']}")
467
```
468

469
### Template Usage
470

471
```html
472
<!-- User sessions page -->
473
<div class="user-sessions">
474
    <h2>Active Sessions</h2>
475
    
476
    {% for session in sessions %}
477
    <div class="session-card">
478
        <div class="session-info">
479
            <strong>{{ session.get_device_info.browser }}</strong>
480
            <small>{{ session.get_device_info.os }}</small>
481
        </div>
482
        
483
        <div class="session-details">
484
            <p>IP: {{ session.ip }}</p>
485
            <p>Location: {{ session.get_location_info.city }}, {{ session.get_location_info.country }}</p>
486
            <p>Last active: {{ session.last_seen_at|timesince }} ago</p>
487
            
488
            {% if session.is_current_session:request %}
489
                <span class="badge badge-success">Current Session</span>
490
            {% else %}
491
                <form method="post" action="{% url 'end_session' session.id %}">
492
                    {% csrf_token %}
493
                    <button type="submit" class="btn btn-sm btn-danger">End Session</button>
494
                </form>
495
            {% endif %}
496
        </div>
497
    </div>
498
    {% endfor %}
499
    
500
    <form method="post" action="{% url 'end_all_sessions' %}">
501
        {% csrf_token %}
502
        <button type="submit" class="btn btn-warning">End All Other Sessions</button>
503
    </form>
504
</div>
505
```
506

507
### Settings Configuration
508

509
```python
510
# In Django settings.py
511

512
# Enable user sessions
513
INSTALLED_APPS = [
514
    # ...
515
    'allauth.usersessions',
516
]
517

518
# Add middleware
519
MIDDLEWARE = [
520
    # ... other middleware
521
    'allauth.usersessions.middleware.UserSessionMiddleware',
522
]
523

524
# User sessions settings
525
USERSESSIONS_TRACK_ACTIVITY = True
526
USERSESSIONS_IP_GEOLOCATION = True
527
USERSESSIONS_CLEANUP_DAYS = 30
528
USERSESSIONS_NOTIFY_NEW_SESSIONS = True
529

530
# Security settings
531
USERSESSIONS_DETECT_SUSPICIOUS = True
532
USERSESSIONS_MAX_SESSIONS_PER_USER = 10
533
USERSESSIONS_SESSION_TIMEOUT_HOURS = 24
534

535
# URL configuration
536
urlpatterns = [
537
    # ...
538
    path('sessions/', include('allauth.usersessions.urls')),
539
]
540
```
541

542
### Management Commands
543

544
```bash
545
# Clean up old sessions
546
python manage.py cleanup_sessions --days 30
547

548
# Generate session report
549
python manage.py session_report --user-id 123 --format csv
550

551
# Monitor suspicious activity
552
python manage.py monitor_sessions --suspicious-only
553
```