Once Axes is installed and configured, you can login and logout
of your application via the
The attempts will be logged and visible in the Access Attempts section in admin.
Axes monitors the views by using the Django login and logout signals and locks out user attempts with a custom authentication backend that checks if requests are allowed to authenticate per the configured rules.
By default, Axes will lock out repeated access attempts from the same IP address by monitoring login failures and storing them into the default database.
Axes needs a
request attribute to be supplied to the stock Django
method in the
django.contrib.auth module in order to function correctly.
If you wish to manually supply the argument to the calls to
you can use the following snippet in your custom login views, tests, or other code:
def custom_login_view(request) username = ... password = ... user = authenticate( request=request, # this is the important custom argument username=username, password=password, ) if user is not None: login(request, user)
If your test setup has problems with the
request argument, you can either
supply the argument manually with a blank HttpRequest()` object,
disable Axes in the test setup by excluding
or leave out
axes.backends.AxesBackend from your
If you are using a 3rd party library that does not supply the
authenticate you can implement a customized backend that inherits
axes.backends.AxesBackend or other backend and overrides the
Resetting attempts and lockouts¶
When Axes locks an IP address, it is not allowed to login again. You can allow IPs to attempt again by resetting (deleting) the relevant AccessAttempt records in the admin UI, CLI, or your own code.
You can also configure automatic cool down periods, IP whitelists, and custom code and handler functions for resetting attempts. Please check out the configuration and customization documentation for further information.
Please note that the functionality describe here concerns the default database handler. If you have changed the default handler to another class such as the cache handler you have to implement custom reset commands.
Resetting attempts from the Django admin UI¶
Records can be easily deleted by using the Django admin application.
Go to the admin UI and check the
Access Attempt view.
Select the attempts you wish the allow again and simply remove them.
The blocked user will be allowed to log in again in accordance to the rules.
Resetting attempts from command line¶
Axes offers a command line interface with
management commands with the Django
django-admin command helpers:
python manage.py axes_resetwill reset all lockouts and access records.
python manage.py axes_reset_ip [ip ...]will clear lockouts and records for the given IP addresses.
python manage.py axes_reset_username [username ...]will clear lockouts and records for the given usernames.
python manage.py axes_reset_ip_username [ip] [username]will clear lockouts and records for the given IP address and username.
python manage.py axes_reset_logs (age)will reset (i.e. delete) AccessLog records that are older than the given age where the default is 30 days.
Resetting attempts programmatically by APIs¶
In your code, you can use the
reset()will reset all lockouts and access records.
reset(ip=ip)will clear lockouts and records for the given IP address.
reset(username=username)will clear lockouts and records for the given username.
Please note that if you give both
ip arguments to
that attempts that have both the set IP and username are reset.
The effective behaviour of
reset is to
and the terms instead of
or ing them.
Data privacy and GDPR¶
Most European countries have quite strict laws regarding data protection and privacy. It’s highly recommended and good practice to treat your sensitive user data with care. The general rule here is that you shouldn’t store what you don’t need.
When dealing with brute-force protection, the IP address and the username (often the email address) are most crucial. Given that you can perfectly use django-axes without locking the user out by IP but by username, it does make sense to avoid storing the IP address at all. You can not lose what you don’t have.
You can adjust the AXES settings as follows:
# Block by Username only (i.e.: Same user different IP is still blocked, but different user same IP is not) AXES_LOCKOUT_PARAMETERS = ["username"] # Disable logging the IP-Address of failed login attempts by returning None for attempts to get the IP # Ignore assigning a lambda function to a variable for brevity AXES_CLIENT_IP_CALLABLE = lambda x: None # noqa: E731