8. API reference¶
Axes offers extensible APIs that you can customize to your liking. You can specialize the following base classes or alternatively use third party modules as long as they implement the following APIs.
-
class
axes.handlers.base.
AxesHandler
¶ Handler API definition for implementations that are used by the
AxesProxyHandler
.If you wish to specialize your own handler class, override the necessary methods and configure the class for use by setting
settings.AXES_HANDLER = 'module.path.to.YourClass'
.The default implementation that is actually used by Axes is
axes.handlers.database.AxesDatabaseHandler
.Note
This is a virtual class and can not be used without specialization.
-
get_failures
(request, credentials: dict = None) → int¶ Checks the number of failures associated to the given request and credentials.
This is a virtual method that needs an implementation in the handler subclass if the
settings.AXES_LOCK_OUT_AT_FAILURE
flag is set toTrue
.
-
is_allowed
(request, credentials: dict = None) → bool¶ Checks if the user is allowed to access or use given functionality such as a login view or authentication.
This method is abstract and other backends can specialize it as needed, but the default implementation checks if the user has attempted to authenticate into the site too many times through the Django authentication backends and returns
False
if user exceeds the configured Axes thresholds.This checker can implement arbitrary checks such as IP whitelisting or blacklisting, request frequency checking, failed attempt monitoring or similar functions.
Please refer to the
axes.handlers.database.AxesDatabaseHandler
for the default implementation and inspiration on some common checks and access restrictions before writing your own implementation.
-
is_blacklisted
(request, credentials: dict = None) → bool¶ Checks if the request or given credentials are blacklisted from access.
-
is_locked
(request, credentials: dict = None) → bool¶ Checks if the request or given credentials are locked.
-
is_whitelisted
(request, credentials: dict = None) → bool¶ Checks if the request or given credentials are whitelisted for access.
-
post_delete_access_attempt
(instance, **kwargs)¶ Handles the
axes.models.AccessAttempt
object post delete signal.
-
post_save_access_attempt
(instance, **kwargs)¶ Handles the
axes.models.AccessAttempt
object post save signal.
-
user_logged_in
(sender, request, user, **kwargs)¶ Handles the Django
django.contrib.auth.signals.user_logged_in
authentication signal.
-
user_logged_out
(sender, request, user, **kwargs)¶ Handles the Django
django.contrib.auth.signals.user_logged_out
authentication signal.
-
user_login_failed
(sender, credentials: dict, request=None, **kwargs)¶ Handles the Django
django.contrib.auth.signals.user_login_failed
authentication signal.
-
-
class
axes.backends.
AxesBackend
¶ Bases:
django.contrib.auth.backends.ModelBackend
Authentication backend class that forbids login attempts for locked out users.
Use this class as the first item of
AUTHENTICATION_BACKENDS
to prevent locked out users from being logged in by the Django authentication flow.Note
This backend does not log your user in. It monitors login attempts. Authentication is handled by the following backends that are configured in
AUTHENTICATION_BACKENDS
.
-
class
axes.middleware.
AxesMiddleware
(get_response: Callable)¶ Middleware that calculates necessary HTTP request attributes for attempt monitoring and maps lockout signals into readable HTTP 403 Forbidden responses.
This middleware recognizes a logout monitoring flag in the request and and uses the
axes.helpers.get_lockout_response
handler for returning customizable and context aware lockout message to the end user if necessary.To customize the lockout handling behaviour further, you can subclass this middleware and change the
__call__
method to your own liking.Please see the following configuration flags before customizing this handler:
AXES_LOCKOUT_TEMPLATE
,AXES_LOCKOUT_URL
,AXES_COOLOFF_MESSAGE
, andAXES_PERMALOCK_MESSAGE
.