3. Usage¶
Once Axes is installed and configured, you can login and logout
of your application via the django.contrib.auth
views.
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.
Authenticating users¶
Axes needs a request
attribute to be supplied to the stock Django authenticate
method in the django.contrib.auth
module in order to function correctly.
If you wish to manually supply the argument to the calls to authenticate
,
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 axes
from INSTALLED_APPS
,
or leave out axes.backends.AxesBackend
from your AUTHENTICATION_BACKENDS
.
If you are using a 3rd party library that does not supply the request
attribute
when calling authenticate
you can implement a customized backend that inherits
from axes.backends.AxesBackend
or other backend and overrides the authenticate
method.
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.
Note
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
axes_reset
, axes_reset_ip
, axes_reset_username
, and axes_reset_ip_username
management commands with the Django manage.py
or django-admin
command helpers:
python manage.py axes_reset
will 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 axes.utils.reset
function.
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.
Note
Please note that if you give both username
and ip
arguments to reset
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