4. Configuration¶
Minimal Axes configuration is done with just settings.py
updates.
More advanced configuration and integrations might require updates on source code level depending on your project implementation.
Configuring project settings¶
The following settings.py
options are available for customizing Axes behaviour.
The configuration option precedences for the access attempt monitoring are:
Default: only use IP address.
AXES_ONLY_USER_FAILURES
: only user username (AXES_USE_USER_AGENT
has no effect).AXES_LOCK_OUT_BY_COMBINATION_USER_AND_IP
: use username and IP address.
The AXES_USE_USER_AGENT
setting can be used with username and IP address or just IP address monitoring,
but does nothing when the AXES_ONLY_USER_FAILURES
setting is set.
Configuring reverse proxies¶
Axes makes use of django-ipware
package to detect the IP address of the client
and uses some conservative configuration parameters by default for security.
If you are using reverse proxies, you will need to configure one or more of the following settings to suit your set up to correctly resolve client IP addresses:
AXES_IPWARE_PROXY_COUNT
: The number of reverse proxies in front of Django as an integer. Default:None
AXES_IPWARE_META_PRECEDENCE_ORDER
: The names ofrequest.META
attributes as a tuple of strings to check to get the client IP address. Check the Django documentation for header naming conventions. Default:IPWARE_META_PRECEDENCE_ORDER
setting if set, else('REMOTE_ADDR', )
Note
For reverse proxies or e.g. Heroku, you might also want to fetch IP addresses from a HTTP header such as X-Forwarded-For
. To configure this, you can fetch IPs through the HTTP_X_FORWARDED_FOR
key from the request.META
property which contains all the HTTP headers in Django:
# refer to the Django request and response objects documentation
AXES_IPWARE_META_PRECEDENCE_ORDER = [
'HTTP_X_FORWARDED_FOR',
'REMOTE_ADDR',
]
Please note that proxies have different behaviours with the HTTP headers. Make sure that your proxy either strips the incoming value or otherwise makes sure of the validity of the header that is used because any header values used in application configuration must be secure and trusted. Otherwise the client can spoof IP addresses by just setting the header in their request and circumvent the IP address monitoring. Normal proxy server behaviours include overriding and appending the header value depending on the platform. Different platforms and gateway services utilize different headers, please refer to your deployment target documentation for up-to-date information on correct configuration.
Configuring handlers¶
Axes uses handlers for processing signals and events from Django authentication and login attempts.
The following handlers are implemented by Axes and can be configured
with the AXES_HANDLER
setting in project configuration:
axes.handlers.database.AxesDatabaseHandler
logs attempts to database and creates AccessAttempt and AccessLog records that persist until removed from the database manually or automatically after their cool offs expire (checked on each login event).
Note
To keep track of concurrent sessions AccessLog stores an hash of session_key
if the session engine is configured.
When no session engine is configured each access is stored with the same dummy value, then a logout will cause each not-logged-out yet logs to set a logout time.
Due to how django.contrib.auth
works it is not possible to correctly track the logout of a session in which the user changed its password, since it will create a new session without firing any logout event.
axes.handlers.cache.AxesCacheHandler
only uses the cache for monitoring attempts and does not persist data other than in the cache backend; this data can be purged automatically depending on your cache configuration, so the cache handler is by design less secure than the database backend but offers higher throughput and can perform better with less bottlenecks. The cache backend should ideally be used with a central cache system such as a Memcached cache and should not rely on individual server state such as the local memory or file based cache does.axes.handlers.dummy.AxesDummyHandler
does nothing with attempts and can be used to disable Axes handlers if the user does not wish Axes to execute any logic on login signals. Please note that this effectively disables any Axes security features, and is meant to be used on e.g. local development setups and testing deployments where login monitoring is not wanted.
To switch to cache based attempt tracking you can do the following:
AXES_HANDLER = 'axes.handlers.cache.AxesCacheHandler'
See the cache configuration section for suitable cache backends.
Configuring caches¶
If you are running Axes with the cache based handler on a deployment with a local Django cache, the Axes lockout and reset functionality might not work predictably if the cache in use is not the same for all the Django processes.
Axes needs to cache access attempts application-wide, and e.g. the in-memory cache only caches access attempts per Django process, so for example resets made in the command line might not remove lock-outs that are in a separate process’s in-memory cache such as the web server serving your login or admin page.
To circumvent this problem, please use somethings else than
django.core.cache.backends.dummy.DummyCache
,
django.core.cache.backends.locmem.LocMemCache
, or
django.core.cache.backends.filebased.FileBasedCache
as your cache backend in Django cache BACKEND
setting.
If changing the 'default'
cache is not an option, you can add a cache
specifically for use with Axes. This is a two step process. First you need to
add an extra cache to CACHES
with a name of your choice:
CACHES = {
'axes': {
'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
'LOCATION': '127.0.0.1:11211',
}
}
The next step is to tell Axes to use this cache through adding AXES_CACHE
to your settings.py
file:
AXES_CACHE = 'axes'
There are no known problems in e.g. MemcachedCache
or Redis based caches.
Configuring authentication backends¶
Axes requires authentication backends to pass request objects with the authentication requests for performing monitoring.
If you get AxesBackendRequestParameterRequired
exceptions,
make sure any libraries and middleware you use pass the request object.
Please check the integration documentation for further information.
Configuring 3rd party apps¶
Refer to the integration documentation for Axes configuration with third party applications and plugins such as
Django REST Framework
Django Allauth
Django Simple Captcha