django-axes Documentation

Axes uses a combination of exceptions, signals, and middleware to manage security:

• Blocking: When an authentication attempt violates a rule, AxesBackend raises a PermissionDenied exception. This stops further authentication backends from running and triggers the user_login_failed signal.
• Monitoring: Axes tracks failed attempts by monitoring the user_login_failed signal. It can track failures based on the attempt IP address, username, user agent, or a combination of all three.
• Lockout Enforcement: When a lockout rule is triggered, Axes marks the request with a special attribute. The AxesMiddleware then intercepts this request and returns the appropriate lockout response to the user.

Note for Developers: Axes assumes that login views either call the authenticate method or otherwise notify Axes of attempts/failures using standard Django authentication signals.

Django Axes integrates with the standard Django authentication framework by adding three specific layers to the login process to monitor attempts and enforce lockouts:

1. Authentication Backend (AxesBackend): This custom backend checks every authentication request. If a request matches a lockout rule (such as a blacklisted IP or exceeding maximum attempts), it raises a PermissionDenied exception to block the attempt.
2. Signal Receivers: Axes listens for the user_login_failed signal. It records failures from both AxesBackend and other authentication backends, tracking metadata like IP address, username, and user agent.
3. Middleware (AxesMiddleware): If a request is identified as being under a lockout, the middleware detects a special attribute set on the request and returns a lockout response to the user.

Axes is designed to be compatible with standard Django implementations and is extensible for 3rd party packages like Django REST Framework, Django Allauth, and Python Social Auth.

To integrate django-axes into your Django project, follow these four steps:

1. Add to INSTALLED_APPS: Add 'axes' to your list. It can be in any position.
2. Configure AUTHENTICATION_BACKENDS: Add 'axes.backends.AxesStandaloneBackend' as the first item in the list. This ensures Axes processes authentication attempts before the default ModelBackend.
3. Add AxesMiddleware: Add 'axes.middleware.AxesMiddleware' to your MIDDLEWARE list. It should be the last middleware in the list. This middleware handles formatting lockout messages and rendering responses. If you use custom views and do not want Axes to override authentication responses, you can skip this step.
4. Sync Database: Run migrations to create the necessary tables.

Note on Backends: AxesStandaloneBackend is recommended if you have custom logic overriding standard permissions. For backwards compatibility, AxesBackend can be used, but it includes ModelBackend functionality internally.

INSTALLED_APPS = [
    ...,
    'axes',
]

AUTHENTICATION_BACKENDS = [
    'axes.backends.AxesStandaloneBackend',
    'django.contrib.auth.backends.ModelBackend',
]

MIDDLEWARE = [
    ...,
    'axes.middleware.AxesMiddleware',
]

Axes supports Django REST Framework (DRF) authentication schemes that rely on Django's authenticate() function. It does not currently support other schemes like TokenAuthentication.

To enable lockout functionality in DRF, you must connect DRF to Axes via lockout signals. When a user is locked out, you should catch the user_locked_out signal and raise a rest_framework.exceptions.PermissionDenied exception to return an HTTP 403 response.

Ensure your signals are loaded in your application's ready() method.

# example/signals.py
from django.dispatch import receiver
from axes.signals import user_locked_out
from rest_framework.exceptions import PermissionDenied

@receiver(user_locked_out)
def raise_permission_denied(*args, **kwargs):
    raise PermissionDenied("Too many failed login attempts")

# example/apps.py
from django import apps

class AppConfig(apps.AppConfig):
    name = "example"

    def ready(self):
        from example import signals  # noqa

Axes supports django-simple-captcha by allowing you to redirect locked-out users to a page where they can solve a captcha to reset their request status.

1. Set AXES_LOCKOUT_URL to the path of your captcha view.
2. In your captcha view, use axes.utils.reset_request(request) after a successful captcha validation to clear the lockout for that request.

# settings.py
AXES_LOCKOUT_URL = '/locked'

# example/views.py
from axes.utils import reset_request
from django.http import HttpResponseRedirect
from django.shortcuts import render
from django.urls import reverse_lazy
from .forms import AxesCaptchaForm

def locked_out(request):
    if request.POST:
        form = AxesCaptchaForm(request.POST)
        if form.is_valid():
            reset_request(request)
            return HttpResponseRedirect(reverse_lazy('auth_login'))
    else:
        form = AxesCaptchaForm()

    return render(request, 'accounts/captcha.html', {'form': form})