5. Customization¶
Axes has multiple options for customization including customizing the attempt tracking and lockout handling logic and lockout response formatting.
There are public APIs and the whole Axes tracking system is pluggable. You can swap the authentication backend, attempt tracker, failure handlers, database or cache backends and error formatters as you see fit.
Check the API reference section for further inspiration on implementing custom authentication backends, middleware, and handlers.
Axes uses the stock Django signals for login monitoring and can be customized and extended by using them correctly.
Axes listens to the following signals from django.contrib.auth.signals
to log access attempts:
user_logged_in
user_logged_out
user_login_failed
You can also use Axes with your own auth module, but you’ll need to ensure that it sends the correct signals in order for Axes to log the access attempts.
Customizing authentication views¶
Here is a more detailed example of sending the necessary signals using
and a custom auth backend at an endpoint that expects JSON
requests. The custom authentication can be swapped out with authenticate
and login
from django.contrib.auth
, but beware that those methods take
care of sending the necessary signals for you, and there is no need to duplicate
them as per the example.
example/forms.py
:
from django import forms
class LoginForm(forms.Form):
username = forms.CharField(max_length=128, required=True)
password = forms.CharField(max_length=128, required=True)
example/views.py
:
from django.contrib.auth import signals
from django.http import JsonResponse, HttpResponse
from django.utils.decorators import method_decorator
from django.views import View
from django.views.decorators.csrf import csrf_exempt
from axes.decorators import axes_dispatch
from example.forms import LoginForm
from example.authentication import authenticate, login
@method_decorator(axes_dispatch, name='dispatch')
@method_decorator(csrf_exempt, name='dispatch')
class Login(View):
"""
Custom login view that takes JSON credentials
"""
http_method_names = ['post']
def post(self, request):
form = LoginForm(request.POST)
if not form.is_valid():
# inform django-axes of failed login
signals.user_login_failed.send(
sender=User,
request=request,
credentials={
'username': form.cleaned_data.get('username'),
},
)
return HttpResponse(status=400)
user = authenticate(
request=request,
username=form.cleaned_data.get('username'),
password=form.cleaned_data.get('password'),
)
if user is not None:
login(request, user)
signals.user_logged_in.send(
sender=User,
request=request,
user=user,
)
return JsonResponse({
'message':'success'
}, status=200)
# inform django-axes of failed login
signals.user_login_failed.send(
sender=User,
request=request,
credentials={
'username': form.cleaned_data.get('username'),
},
)
return HttpResponse(status=403)
urls.py
:
from django.urls import path
from example.views import Login
urlpatterns = [
path('login/', Login.as_view(), name='login'),
]
Customizing username lookups¶
In special cases, you may have the need to modify the username that is
submitted before attempting to authenticate. For example, adding namespacing or
removing client-set prefixes. In these cases, axes
needs to know how to make
these changes so that it can correctly identify the user without any form
cleaning or validation. This is where the AXES_USERNAME_CALLABLE
setting
comes in. You can define how to make these modifications in a callable that
takes a request object and a credentials dictionary,
and provide that callable to axes
via this setting.
For example, a function like this could take a post body with something like
username='prefixed-username'
and namespace=my_namespace
and turn it
into my_namespace-username
:
example/utils.py
:
def get_username(request, credentials):
username = credentials.get('username')
namespace = credentials.get('namespace')
return namespace + '-' + username
settings.py
:
AXES_USERNAME_CALLABLE = 'example.utils.get_username'
Note
You still have to make these modifications yourself before calling authenticate. If you want to re-use the same function for consistency, that’s fine, but Axes does not inject these changes into the authentication flow for you.
Customizing lockout responses¶
Axes can be configured with AXES_LOCKOUT_CALLABLE
to return a custom lockout response when using the plugin with e.g. DRF (Django REST Framework) or other third party libraries which require specialized formats such as JSON or XML response formats or customized response status codes.
An example of usage could be e.g. a custom view for processing lockouts.
example/views.py
:
from django.http import JsonResponse
def lockout(request, credentials, *args, **kwargs):
return JsonResponse({"status": "Locked out due to too many login failures"}, status=403)
settings.py
:
AXES_LOCKOUT_CALLABLE = "example.views.lockout"
Customizing lockout parameters¶
Axes can be configured with AXES_LOCKOUT_PARAMETERS
to lock out users not only by IP address.
AXES_LOCKOUT_PARAMETERS
can be a list of strings (which represents a separate lockout parameter) or nested lists of strings (which represents lockout parameters used in combination) or a callable which accepts HttpRequest or AccessAttempt and credentials and returns a list of the same form as described earlier.
Example AXES_LOCKOUT_PARAMETERS
configuration:
settings.py
:
AXES_LOCKOUT_PARAMETERS = ["ip_address", ["username", "user_agent"]]
This way, axes will lock out users using ip_address and/or combination of username and user agent
Example of callable AXES_LOCKOUT_PARAMETERS
:
example/utils.py
:
from django.http import HttpRequest
def get_lockout_parameters(request_or_attempt, credentials):
if isinstance(request_or_attempt, HttpRequest):
is_localhost = request.META.get("REMOTE_ADDR") == "127.0.0.1"
else:
is_localhost = request_or_attempt.ip_address == "127.0.0.1"
if is_localhost:
return ["username"]
return ["ip_address", "username"]
settings.py
:
AXES_LOCKOUT_PARAMETERS = "example.utils.get_lockout_parameters"
This way, if client ip_address is localhost, axes will lockout client only by username. In other case, axes will lockout client by username and/or ip_address.
Customizing client ip address lookups¶
Axes can be configured with AXES_CLIENT_IP_CALLABLE
to use custom client ip address lookup logic.
example/utils.py
:
def get_client_ip(request):
return request.META.get("REMOTE_ADDR")
settings.py
:
AXES_CLIENT_IP_CALLABLE = "example.utils.get_client_ip"