Django User Sessions’s Documentation¶
Django includes excellent built-in sessions, however all the data is hidden away into base64 encoded data. This makes it very difficult to run a query on all active sessions for a particular user. django-user-sessions fixes this and makes session objects a first class citizen like other ORM objects.
Contents:
Installation¶
pip install django-user-sessions
- In
INSTALLED_APPS
replace'django.contrib.sessions'
with'user_sessions'
. - In
MIDDLEWARE
orMIDDLEWARE_CLASSES
replace'django.contrib.sessions.middleware.SessionMiddleware'
with'user_sessions.middleware.SessionMiddleware'
. - Add
SESSION_ENGINE = 'user_sessions.backends.db'
. - Add
url(r'', include('user_sessions.urls', 'user_sessions')),
to yoururls.py
. - Make sure
LOGOUT_REDIRECT_URL
is set to some page to redirect users after logging out. - Run
python manage.py syncdb
(ormigrate
) and browse to/account/sessions/
.
System check framework¶
Django warns you about common configuration errors. When replacing the session middleware with the one provided by this library, it’ll start warning about admin.E410. You can silence this warning by adding the following line in your settings file:
SILENCED_SYSTEM_CHECKS = [‘admin.E410’]
GeoIP¶
You need to setup GeoIP for the location detection to work. See the Django documentation on installing GeoIP.
IP when behind a proxy¶
If you’re running Django behind a proxy like nginx, you will have to set the REMOTE_ADDR META header manually using a middleware, to stop it from always returning the ip of the proxy (e.g. 127.0.0.1 in many cases).
An example middleware to fix this issue is django-xforwardedfor-middleware which simply does this for each request:
request.META['REMOTE_ADDR'] = request.META['HTTP_X_FORWARDED_FOR'].split(',')[0].strip()
Your particular configuration may vary, X-Forwarded-For must be set by a proxy that you have control over, otherwise it might be spoofed by the client.
Usage¶
Current session¶
The current session is available on the request, just like the normal session middleware makes the session available:
def my_view(request):
request.session
All sessions¶
To get the list of a user’s sessions:
sessions = user.session_set.filter(expire_date__gt=now())
You could logout the user everywhere:
user.session_set.all().delete()
Generic views¶
There are two views included with this application,
SessionListView
and
SessionDeleteView
. Using this views you have a
simple, but effective, user session management that even looks great out of
the box:
Template tags¶
Two template tags are included
device()
and
location()
. These can be used
for respectively humanizing the user agent string and showing an approximate
location of the IP address:
{% load user_sessions %}
{{ session.user_agent|device }} -> Safari on OS X
{{ session.ip|location }} -> Zwolle, The Netherlands
Admin views¶
The user’s IP address and user agent are also stored on the session. This allows to show a list of active sessions to the user in the admin:
Reference¶
Middleware¶
-
class
user_sessions.middleware.
SessionMiddleware
(get_response=None)¶ Middleware that provides ip and user_agent to the session store.
Models¶
Session Backends¶
Template Tags¶
Transform a User Agent into human readable text.
Example output:
- Safari on iPhone
- Chrome on Windows 8.1
- Safari on OS X
- Firefox
- Linux
- None
Transform an IP address into an approximate location.
Example output:
- Zwolle, The Netherlands
- The Netherlands
- None
Views¶
-
class
user_sessions.views.
SessionListView
(**kwargs)¶ View for listing a user’s own sessions.
This view shows list of a user’s currently active sessions. You can override the template by providing your own template at user_sessions/session_list.html.
-
class
user_sessions.views.
SessionDeleteView
(**kwargs)¶ View for deleting a user’s own session.
This view allows a user to delete an active session. For example log out a session from a computer at the local library or a friend’s place.
Unit tests¶
Release Notes¶
1.7.0¶
- new: Support for Django 2.2+.
- Dropped Django <2.2 support.
1.6.0¶
- New: Support for Django 2.0.
- Dropped Django <1.11 support.
- Command for migrating existing sessions to the new session store (#33).
1.5.3¶
- Fixed issue with incorrect location being displayed.
1.5.2¶
- Also work with GeoIP2 country database.
1.5.1¶
- Updated documentation for GeoIP2 library.
- Correctly detect macOS version on Firefox.
1.5.0¶
- Added Django 1.11 support.
- Added support for GeoIP2 library.
- Added detection of Windows 10 and macOS from user-agent.
- Fixed #73 – Error when deleting individual session from list view.
- Fixed #74 – user agent not being shown in list view.
- Resolved Django’s deprecation warnings (preliminary Django 2.0 support).
- Make templatetags return None instead of ‘unknown’, provide your own fallback value with default_if_none:.
- Allow translation of fallback values.
1.4.0¶
- Added Django Channels support.
- Fixed #62 – Provide request.user in signals.
- Ending current session will logout instead, make sure LOGOUT_REDIRECT_URL is set.
1.3.1¶
- Added Django 1.10 support.
1.3.0¶
- Added Django 1.9 support.
- Dropped support for Django 1.7 and below.
1.2.0¶
- New feature: delete all-but-current sessions.
- Added clearsessions command.
1.1.1¶
- Added Django 1.8 support.
1.1.0¶
- Fixed #14 – Truncate long user agents strings.
- Fixed #23 – Cannot use admin view search.
- Added Django 1.7 migrations.
1.0.0¶
- #8 – Consistent URL patterns.
- #11 – Support Django 1.6’s ATOMIC_REQUESTS.
- German translation added.
0.1.4¶
- Python 3.4 support.
- Django 1.7 (beta) support.
- Italian translation added.
- Chinese translation added.
- Arabic translation updated.
0.1.3¶
- Documentation.
- Hebrew translation added.
- Arabic translation added.
- Fixed #3 – Reset user_id on logout.
- Fixed #4 – Add explicit license text.
0.1.2¶
- Ship with default templates.
- Added Dutch translation.
0.1.1¶
- Added South migrations.
0.1.0¶
- Initial release.