django-lockout
is a cache-based Django app that locks out users after too many failed login attempts. Because django-lockout
tracks login attempts in your site's cache, it is fast and lightweight. It is intended for Django sites where protection against brute force attacks is desired with no additional database overhead.
django-lockout
wraps django.contrib.auth.authenticate
and raises lockout.LockedOut
when too many login attempts occur. Your views are responsible for catching and handling LockedOut
however you deem appropriate. django-lockout
's middleware class stores the request object in the thread local namespace to give the wrapped auth.authenticate
function access to it.
Login attempts can be tracked by IP only or by IP plus user-agent.
django-lockout
is designed for Django 1.3. It also works with Django 1.0, 1.1, and 1.2, with the exception of the test suite (which relies on django.test.client.RequestFactory
). If you use django-lockout
with an earlier version of Django than 1.3, you should not add 'lockout'
to your INSTALLED_APPS
.
django-lockout
requires that you have enabled a cache for your site.
You can install django-lockout
with:
pip install django-lockout
or:
easy_install django-lockout
Add 'lockout.middleware.LockoutMiddleware'
to your MIDDLEWARE_CLASSES
. It should come before Django's AuthenticationMiddleware
:
MIDDLEWARE_CLASSES = [
'lockout.middleware.LockoutMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
...
]
Adding 'lockout'
to your INSTALLED_APPS
is only required if you want to run django-lockout
's test suite.
Below is an example of how you might use django-lockout
:
try:
user = auth.authenticate(username=username, password=password)
except LockedOut:
messages.warning(request, 'Your account has been locked out because of too many failed login attempts.')
If you need to clear the record of failed attempts for an IP or IP plus user-agent, call lockout.reset_attempts
, passing the request
for that IP or IP plus user-agent:
reset_attempts(request)
- LOCKOUT_MAX_ATTEMPTS
The maximum number of login attempts before the IP or IP plus user-agent is locked out. Default:
5
.- LOCKOUT_TIME
The number of seconds the IP or IP plus user-agent should be locked out. Default:
600
(10 minutes).- LOCKOUT_ENFORCEMENT_WINDOW
The number of seconds before the failed login attempts are reset and the IP or IP plus user-agent gets a fresh start. Default:
300
(5 minutes).LOCKOUT_ENFORCEMENT_WINDOW
affects failed login attempts up to the max allowed, whileLOCKOUT_TIME
takes effect when the max attempts is reached. For example, with aLOCKOUT_ENFORCEMENT_WINDOW
of 5 minutes, suppose a user has a failed login attempt, followed by another failed login attempt 3 minutes later. Both attempts will count toward the maximum. However, if the 5-minute mark (from the first failed attempt) is reached with fewer than the max allowed attempts, the failures will expire and the user will once again be allowed the maximum attempts. If the user exceeds the max within theLOCKOUT_ENFORCEMENT_WINDOW
, the user will be locked out forLOCKOUT_TIME
seconds.- LOCKOUT_USE_USER_AGENT
Whether to track failed login attempts by IP plus user-agent, instead of by IP only. Default:
False
.- LOCKOUT_CACHE_PREFIX
The prefix for cache keys generated by
django-lockout
. Default:'lockout'
.