From 8c4c2aaa93af568a74a91821df519c921aeaf707 Mon Sep 17 00:00:00 2001 From: "rodrigo.nogueira" Date: Sat, 21 Feb 2026 13:29:28 -0300 Subject: [PATCH 1/5] docs: Revamp and expand the configuration options documentation. --- docs/4_configuration.rst | 293 +++++++++++++++++++++++++++++---------- 1 file changed, 222 insertions(+), 71 deletions(-) diff --git a/docs/4_configuration.rst b/docs/4_configuration.rst index 36c4af5..b526581 100644 --- a/docs/4_configuration.rst +++ b/docs/4_configuration.rst @@ -14,77 +14,228 @@ Configuring project settings The following ``settings.py`` options are available for customizing Axes behaviour. -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable | Default | Explanation | -+======================================================+==============================================+===========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| AXES_ENABLED | True | Enable or disable Axes plugin functionality, for example in test runner setup | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_FAILURE_LIMIT | 3 | The integer number of login attempts allowed before a record is created for the failed logins. This can also be a callable or a dotted path to callable that returns an integer and all of the following are valid: ``AXES_FAILURE_LIMIT = 42``, ``AXES_FAILURE_LIMIT = lambda *args: 42``, and ``AXES_FAILURE_LIMIT = 'project.app.get_login_failure_limit'``. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_LOCK_OUT_AT_FAILURE | True | After the number of allowed login attempts are exceeded, should we lock out this IP (and optional user agent)? | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_COOLOFF_TIME | None | If set, defines a period of inactivity after which old failed login attempts will be cleared. Can be set to a Python timedelta object, an integer, a float, a callable, or a string path to a callable which takes the request as argument. If an integer or float, will be interpreted as a number of hours: ``AXES_COOLOFF_TIME = 2`` 2 hours, ``AXES_COOLOFF_TIME = 2.0`` 2 hours, 120 minutes, ``AXES_COOLOFF_TIME = 1.7`` 1.7 hours, 102 minutes, 6120 seconds | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_ONLY_ADMIN_SITE | False | If ``True``, lock is only enabled for admin site. Admin site is determined by checking request path against the path of ``"admin:index"`` view. If admin urls are not registered in current urlconf, all requests will not be locked. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_ONLY_USER_FAILURES | False | DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, only lock based on username, and never lock based on IP if attempts exceed the limit. Otherwise utilize the existing IP and user locking logic. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_ENABLE_ADMIN | True | If ``True``, admin views for access attempts and logins are shown in Django admin interface. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_LOCK_OUT_BY_COMBINATION_USER_AND_IP | False | DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, prevent login from IP under a particular username if the attempt limit has been exceeded, otherwise lock out based on IP. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_LOCK_OUT_BY_USER_OR_IP | False | DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, prevent login from if the attempt limit has been exceeded for IP or username. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_USE_USER_AGENT | False | DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, lock out and log based on the IP address and the user agent. This means requests from different user agents but from the same IP are treated differently. This settings has no effect if the ``AXES_ONLY_USER_FAILURES`` setting is active. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_HANDLER | 'axes.handlers.database.AxesDatabaseHandler' | The path to the handler class to use. If set, overrides the default signal handler backend. Default: ``'axes.handlers.database.AxesDatabaseHandler'`` | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_CACHE | 'default' | The name of the cache for Axes to use. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_LOCKOUT_TEMPLATE | None | If set, specifies a template to render when a user is locked out. Template receives ``cooloff_timedelta``, ``cooloff_time``, ``username`` and ``failure_limit`` as context variables. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_LOCKOUT_URL | None | If set, specifies a URL to redirect to on lockout. If both ``AXES_LOCKOUT_TEMPLATE`` and ``AXES_LOCKOUT_URL`` are set, the template will be used. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_VERBOSE | True | If ``True``, you'll see slightly more logging for Axes. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_USERNAME_FORM_FIELD | 'settings.AUTH_USER_MODEL.USERNAME_FIELD' | The name of the form field that contains your users usernames. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_USERNAME_CALLABLE | None | A callable or a string path to callable that takes two arguments for user lookups: ``def get_username(request: HttpRequest, credentials: dict) -> str: ...``. This can be any callable such as ``AXES_USERNAME_CALLABLE = lambda request, credentials: 'username'`` or a full Python module path to callable such as ``AXES_USERNAME_CALLABLE = 'example.get_username``. The ``request`` is a HttpRequest like object and the ``credentials`` is a dictionary like object. ``credentials`` are the ones that were passed to Django ``authenticate()`` in the login flow. If no function is supplied, Axes fetches the username from the ``credentials`` or ``request.POST`` dictionaries based on ``AXES_USERNAME_FORM_FIELD``. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_WHITELIST_CALLABLE | None | A callable or a string path to callable that takes two arguments for whitelisting determination and returns True, if user should be whitelisted: ``def is_whitelisted(request: HttpRequest, credentials: dict) -> bool: ...``. This can be any callable similarly to ``AXES_USERNAME_CALLABLE``. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_LOCKOUT_CALLABLE | None | A callable or a string path to callable that takes three arguments returns a response. For example: ``def generate_lockout_response(request: HttpRequest, original_response: HttpResponse, credentials: dict) -> HttpResponse: ...``. This can be any callable similarly to ``AXES_USERNAME_CALLABLE``. If not callable is defined, then the default implementation in ``axes.helpers.get_lockout_response`` is used for determining the correct lockout response that is sent to the requesting client. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_CLIENT_IP_CALLABLE | None | A callable or a string path to callable that takes HttpRequest as an argument and returns the resolved IP as a response. For example: ``def get_ip(request: HttpRequest) -> str: ...``. This can be any callable similarly to ``AXES_USERNAME_CALLABLE``. If not callable is defined, then the default implementation in ``axes.helpers.get_client_ip_address`` is used. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_PASSWORD_FORM_FIELD | 'password' | The name of the form or credentials field that contains your users password. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_SENSITIVE_PARAMETERS | ["username", "ip_address"] | Configures POST and GET parameter values (in addition to the value of ``AXES_PASSWORD_FORM_FIELD``) to mask in login attempt logging. Defaults enable privacy-by-design. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_NEVER_LOCKOUT_GET | False | If ``True``, Axes will never lock out HTTP GET requests. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_NEVER_LOCKOUT_WHITELIST | False | If ``True``, users can always login from whitelisted IP addresses. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_IP_BLACKLIST | None | An iterable of IPs to be blacklisted. Takes precedence over whitelists. For example: ``AXES_IP_BLACKLIST = ['0.0.0.0']``. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_IP_WHITELIST | None | An iterable of IPs to be whitelisted. For example: ``AXES_IP_WHITELIST = ['0.0.0.0']``. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_DISABLE_ACCESS_LOG | False | If ``True``, disable writing login and logout access logs to database, so the admin interface will not have user login trail for successful user authentication. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_ENABLE_ACCESS_FAILURE_LOG | False | If ``True``, enable writing login failure logs to database, so you will have every user login trail for unsuccessful user authentication. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_ACCESS_FAILURE_LOG_PER_USER_LIMIT | 1000 | Sets the number of failures to trail for each user. When the access failure log reach this number of records, an automatic removal is ran. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_RESET_ON_SUCCESS | False | If ``True``, a successful login will reset the number of failed logins. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_ALLOWED_CORS_ORIGINS | "*" | Configures lockout response CORS headers for XHR requests. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_HTTP_RESPONSE_CODE | 429 | Sets the http response code returned when ``AXES_FAILURE_LIMIT`` is reached. For example: ``AXES_HTTP_RESPONSE_CODE = 403`` | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_RESET_COOL_OFF_ON_FAILURE_DURING_LOCKOUT | True | If ``True``, a failed login attempt during lockout will reset the cool off period. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| AXES_LOCKOUT_PARAMETERS | ["ip_address"] | A list of parameters that Axes uses to lock out users. It can also be callable, which takes an http request or AccesAttempt object and credentials and returns a list of parameters. Each parameter can be a string (a single parameter) or a list of strings (a combined parameter). For example, if you configure ``AXES_LOCKOUT_PARAMETERS = ["ip_address", ["username", "user_agent"]]``, axes will block clients by ip and/or username and user agent combination. See :ref:`customizing-lockout-parameters` for more details. | -+------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +Lockout configuration +--------------------- + +.. list-table:: Project settings + :widths: 20 20 60 + :header-rows: 1 + + * - Variable + - Default + - Explanation + + * - AXES_ENABLED + - True + - Enable or disable Axes plugin functionality, for example in test runner setup + + * - AXES_FAILURE_LIMIT + - 3 + - The integer number of login attempts allowed before the request is considered + locked. This can also be a callable or a dotted path to callable that + returns an integer and all of the following are valid: ``AXES_FAILURE_LIMIT = + 42``, ``AXES_FAILURE_LIMIT = lambda *args: 42``, and ``AXES_FAILURE_LIMIT = + 'project.app.get_login_failure_limit'``. + + * - AXES_LOCK_OUT_AT_FAILURE + - True + - After the number of allowed login attempts are exceeded, should we lock out this + IP (and optional user agent)? + + * - AXES_COOLOFF_TIME + - None + - If set, defines a period of inactivity after which old failed login attempts + will be cleared. If ``None``, lockout is permanent until the attempts are + manually cleared. Can be set to a Python timedelta object, an integer, a float, + a callable, or a string path to a callable which takes the request as argument. + For an integer or float, it will be interpreted as a number of hours: + ``1`` is 1 hour, ``0.5`` is 30 minutes. A ``timedelta`` is recommended for clarity. + See also ``AXES_USE_ATTEMPT_EXPIRATION`` for rolling window behavior. + * - AXES_USE_ATTEMPT_EXPIRATION + - False + - If ``True``, changes the behavior of ``AXES_COOLOFF_TIME`` to a rolling window + meaning each failed attempt expires individually after the cool-off time. This + allows you to configure a "number of failed login attempts per xx minutes" + rule (e.g. 3 attempts per 15 minutes). If ``False``, ``AXES_COOLOFF_TIME`` acts + as a period of inactivity where attempts are only cleared if no new failures + occur within the cool-off limit. + + * - AXES_ONLY_ADMIN_SITE + - False + - If ``True``, lock is only enabled for admin site. Admin site is determined by + checking request path against the path of ``"admin:index"`` view. If admin urls + are not registered in current urlconf, all requests will not be locked. + + * - AXES_ONLY_USER_FAILURES + - False + - DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, only lock + based on username, and never lock based on IP if attempts exceed the limit. + Otherwise utilize the existing IP and user locking logic. + + * - AXES_ENABLE_ADMIN + - True + - If ``True``, admin views for access attempts and logins are shown in Django + admin interface. + + * - AXES_LOCK_OUT_BY_COMBINATION_USER_AND_IP + - False + - DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, prevent login + from IP under a particular username if the attempt limit has been exceeded, + otherwise lock out based on IP. + + * - AXES_LOCK_OUT_BY_USER_OR_IP + - False + - DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, prevent login + from if the attempt limit has been exceeded for IP or username. + + * - AXES_USE_USER_AGENT + - False + - DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, lock out and + log based on the IP address and the user agent. This means requests from + different user agents but from the same IP are treated differently. This + settings has no effect if the ``AXES_ONLY_USER_FAILURES`` setting is active. + + * - AXES_HANDLER + - 'axes.handlers.database.AxesDatabaseHandler' + - The path to the handler class to use. If set, overrides the default signal + handler backend. Default: ``'axes.handlers.database.AxesDatabaseHandler'`` + + * - AXES_CACHE + - 'default' + - The name of the cache for Axes to use. + + * - AXES_LOCKOUT_TEMPLATE + - None + - If set, specifies a template to render when a user is locked out. Template + receives ``cooloff_timedelta``, ``cooloff_time``, ``username`` and + ``failure_limit`` as context variables. + + * - AXES_LOCKOUT_URL + - None + - If set, specifies a URL to redirect to on lockout. If both + ``AXES_LOCKOUT_TEMPLATE`` and ``AXES_LOCKOUT_URL`` are set, the template will be + used. + + * - AXES_VERBOSE + - True + - If ``True``, you'll see slightly more logging for Axes. + + * - AXES_USERNAME_FORM_FIELD + - 'settings.AUTH_USER_MODEL.USERNAME_FIELD' + - The name of the form field that contains your users usernames. + + * - AXES_USERNAME_CALLABLE + - None + - A callable or a string path to callable that takes two arguments for user + lookups: ``def get_username(request: HttpRequest, credentials: dict) -> str: + ...``. This can be any callable such as ``AXES_USERNAME_CALLABLE = lambda + request, credentials: 'username'`` or a full Python module path to callable such + as ``AXES_USERNAME_CALLABLE = 'example.get_username``. The ``request`` is a + HttpRequest like object and the ``credentials`` is a dictionary like object. + ``credentials`` are the ones that were passed to Django ``authenticate()`` in + the login flow. If no function is supplied, Axes fetches the username from the + ``credentials`` or ``request.POST`` dictionaries based on + ``AXES_USERNAME_FORM_FIELD``. + + * - AXES_WHITELIST_CALLABLE + - None + - A callable or a string path to callable that takes two arguments for + whitelisting determination and returns True, if user should be whitelisted: + ``def is_whitelisted(request: HttpRequest, credentials: dict) -> bool: ...``. + This can be any callable similarly to ``AXES_USERNAME_CALLABLE``. + + * - AXES_LOCKOUT_CALLABLE + - None + - A callable or a string path to callable that takes three arguments returns a + response. For example: ``def generate_lockout_response(request: HttpRequest, + original_response: HttpResponse, credentials: dict) -> HttpResponse: ...``. This + can be any callable similarly to ``AXES_USERNAME_CALLABLE``. If not callable is + defined, then the default implementation in + ``axes.helpers.get_lockout_response`` is used for determining the correct + lockout response that is sent to the requesting client. + + * - AXES_CLIENT_IP_CALLABLE + - None + - A callable or a string path to callable that takes HttpRequest as an argument + and returns the resolved IP as a response. For example: ``def get_ip(request: + HttpRequest) -> str: ...``. This can be any callable similarly to + ``AXES_USERNAME_CALLABLE``. If not callable is defined, then the default + implementation in ``axes.helpers.get_client_ip_address`` is used. + + * - AXES_PASSWORD_FORM_FIELD + - 'password' + - The name of the form or credentials field that contains your users password. + + * - AXES_SENSITIVE_PARAMETERS + - ["username", "ip_address"] + - Configures POST and GET parameter values (in addition to the value of + ``AXES_PASSWORD_FORM_FIELD``) to mask in login attempt logging. Defaults enable + privacy-by-design. + + * - AXES_NEVER_LOCKOUT_GET + - False + - If ``True``, Axes will never lock out HTTP GET requests. + + * - AXES_NEVER_LOCKOUT_WHITELIST + - False + - If ``True``, users can always login from whitelisted IP addresses. + + * - AXES_IP_BLACKLIST + - None + - An iterable of IPs to be blacklisted. Takes precedence over whitelists. For + example: ``AXES_IP_BLACKLIST = ['0.0.0.0']``. + + * - AXES_IP_WHITELIST + - None + - An iterable of IPs to be whitelisted. For example: ``AXES_IP_WHITELIST = + ['0.0.0.0']``. + + * - AXES_DISABLE_ACCESS_LOG + - False + - If ``True``, disable writing login and logout access logs to database, so the + admin interface will not have user login trail for successful user + authentication. + + * - AXES_ENABLE_ACCESS_FAILURE_LOG + - False + - If ``True``, enable writing login failure logs to database, so you will have + every user login trail for unsuccessful user authentication. + + * - AXES_ACCESS_FAILURE_LOG_PER_USER_LIMIT + - 1000 + - Sets the number of failures to trail for each user. When the access failure log + reach this number of records, an automatic removal is ran. + + * - AXES_RESET_ON_SUCCESS + - False + - If ``True``, a successful login will reset the number of failed logins. + + * - AXES_ALLOWED_CORS_ORIGINS + - "*" + - Configures lockout response CORS headers for XHR requests. + + * - AXES_HTTP_RESPONSE_CODE + - 429 + - Sets the http response code returned when ``AXES_FAILURE_LIMIT`` is reached. For + example: ``AXES_HTTP_RESPONSE_CODE = 403`` + + * - AXES_RESET_COOL_OFF_ON_FAILURE_DURING_LOCKOUT + - True + - If ``True``, any new failed login attempt while the user is locked out will + reset their cool-off timer to ``now() + AXES_COOLOFF_TIME``. This means repeated + brute-force attempts will continuously extend the lockout period. + + * - AXES_LOCKOUT_PARAMETERS + - ["ip_address"] + - A list of parameters that Axes uses to lock out users. It can also be callable, + which takes an http request or AccesAttempt object and credentials and returns a + list of parameters. Each parameter can be a string (a single parameter) or a + list of strings (a combined parameter). For example, if you configure + ``AXES_LOCKOUT_PARAMETERS = ["ip_address", ["username", "user_agent"]]``, axes + will block clients by ip and/or username and user agent combination. See + :ref:`customizing-lockout-parameters` for more details. + + The configuration option precedences for the access attempt monitoring are: From a6c18f626cb48056081ebca5f0d7f7752cf12e64 Mon Sep 17 00:00:00 2001 From: "rodrigo.nogueira" Date: Sat, 21 Feb 2026 16:05:25 -0300 Subject: [PATCH 2/5] docs: clarify AXES_COOLOFF_TIME and AXES_USE_ATTEMPT_EXPIRATION descriptions and add common configuration examples. --- docs/4_configuration.rst | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/docs/4_configuration.rst b/docs/4_configuration.rst index b526581..0433728 100644 --- a/docs/4_configuration.rst +++ b/docs/4_configuration.rst @@ -44,10 +44,11 @@ Lockout configuration * - AXES_COOLOFF_TIME - None - - If set, defines a period of inactivity after which old failed login attempts - will be cleared. If ``None``, lockout is permanent until the attempts are + - If set, defines the cool-off period after which the lockout is lifted (old + attempts are ignored). If ``None``, lockout is permanent until the attempts are manually cleared. Can be set to a Python timedelta object, an integer, a float, a callable, or a string path to a callable which takes the request as argument. + Callable must accept a single request argument (Django-Axes 7.0+ signature). For an integer or float, it will be interpreted as a number of hours: ``1`` is 1 hour, ``0.5`` is 30 minutes. A ``timedelta`` is recommended for clarity. See also ``AXES_USE_ATTEMPT_EXPIRATION`` for rolling window behavior. @@ -56,7 +57,10 @@ Lockout configuration - If ``True``, changes the behavior of ``AXES_COOLOFF_TIME`` to a rolling window meaning each failed attempt expires individually after the cool-off time. This allows you to configure a "number of failed login attempts per xx minutes" - rule (e.g. 3 attempts per 15 minutes). If ``False``, ``AXES_COOLOFF_TIME`` acts + rule (e.g. 3 attempts per 15 minutes). When ``True``, only failures inside the + cool-off window are counted (sliding/rolling window behavior). + + If ``False``, ``AXES_COOLOFF_TIME`` acts as a period of inactivity where attempts are only cleared if no new failures occur within the cool-off limit. @@ -237,6 +241,23 @@ Lockout configuration +**Common configurations** + +.. code-block:: python + + # Classic: 3 failures -> 30 min lockout + AXES_FAILURE_LIMIT = 3 + AXES_COOLOFF_TIME = timedelta(minutes=30) + + # Rolling window: max 5 failures in any 15-minute period + AXES_FAILURE_LIMIT = 5 + AXES_COOLOFF_TIME = timedelta(minutes=15) + AXES_USE_ATTEMPT_EXPIRATION = True + + # Hard lockout (manual reset only) + AXES_FAILURE_LIMIT = 5 + AXES_COOLOFF_TIME = None + The configuration option precedences for the access attempt monitoring are: 1. Default: only use IP address. From c5e027a1e8cbe655ef28ce7b85797730632438a9 Mon Sep 17 00:00:00 2001 From: "rodrigo.nogueira" Date: Sat, 21 Feb 2026 16:09:42 -0300 Subject: [PATCH 3/5] docs: Update lockout configuration table title and column widths. --- docs/4_configuration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/4_configuration.rst b/docs/4_configuration.rst index 0433728..c18fef6 100644 --- a/docs/4_configuration.rst +++ b/docs/4_configuration.rst @@ -17,8 +17,8 @@ The following ``settings.py`` options are available for customizing Axes behavio Lockout configuration --------------------- -.. list-table:: Project settings - :widths: 20 20 60 +.. list-table:: Core lockout settings + :widths: 25 15 60 :header-rows: 1 * - Variable From 82f57a4d92e3fe5adb1e580df980197f86e04468 Mon Sep 17 00:00:00 2001 From: "rodrigo.nogueira" Date: Sat, 21 Feb 2026 16:39:18 -0300 Subject: [PATCH 4/5] docs: Fix typo in `AXES_LOCKOUT_PARAMETERS` description and add a blank line. --- docs/4_configuration.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/4_configuration.rst b/docs/4_configuration.rst index c18fef6..521936a 100644 --- a/docs/4_configuration.rst +++ b/docs/4_configuration.rst @@ -52,6 +52,7 @@ Lockout configuration For an integer or float, it will be interpreted as a number of hours: ``1`` is 1 hour, ``0.5`` is 30 minutes. A ``timedelta`` is recommended for clarity. See also ``AXES_USE_ATTEMPT_EXPIRATION`` for rolling window behavior. + * - AXES_USE_ATTEMPT_EXPIRATION - False - If ``True``, changes the behavior of ``AXES_COOLOFF_TIME`` to a rolling window @@ -232,7 +233,7 @@ Lockout configuration * - AXES_LOCKOUT_PARAMETERS - ["ip_address"] - A list of parameters that Axes uses to lock out users. It can also be callable, - which takes an http request or AccesAttempt object and credentials and returns a + which takes an http request or AccessAttempt object and credentials and returns a list of parameters. Each parameter can be a string (a single parameter) or a list of strings (a combined parameter). For example, if you configure ``AXES_LOCKOUT_PARAMETERS = ["ip_address", ["username", "user_agent"]]``, axes From d01eb3d41e366bcd1887acff35f93c78cd4b4e79 Mon Sep 17 00:00:00 2001 From: Rodrigo Nogueira Date: Mon, 16 Mar 2026 16:26:00 -0300 Subject: [PATCH 5/5] docs: narrow cool-off docs changes and keep table format --- docs/4_configuration.rst | 300 ++++++++++----------------------------- 1 file changed, 73 insertions(+), 227 deletions(-) diff --git a/docs/4_configuration.rst b/docs/4_configuration.rst index 521936a..7785f2d 100644 --- a/docs/4_configuration.rst +++ b/docs/4_configuration.rst @@ -14,233 +14,79 @@ Configuring project settings The following ``settings.py`` options are available for customizing Axes behaviour. -Lockout configuration ---------------------- - -.. list-table:: Core lockout settings - :widths: 25 15 60 - :header-rows: 1 - - * - Variable - - Default - - Explanation - - * - AXES_ENABLED - - True - - Enable or disable Axes plugin functionality, for example in test runner setup - - * - AXES_FAILURE_LIMIT - - 3 - - The integer number of login attempts allowed before the request is considered - locked. This can also be a callable or a dotted path to callable that - returns an integer and all of the following are valid: ``AXES_FAILURE_LIMIT = - 42``, ``AXES_FAILURE_LIMIT = lambda *args: 42``, and ``AXES_FAILURE_LIMIT = - 'project.app.get_login_failure_limit'``. - - * - AXES_LOCK_OUT_AT_FAILURE - - True - - After the number of allowed login attempts are exceeded, should we lock out this - IP (and optional user agent)? - - * - AXES_COOLOFF_TIME - - None - - If set, defines the cool-off period after which the lockout is lifted (old - attempts are ignored). If ``None``, lockout is permanent until the attempts are - manually cleared. Can be set to a Python timedelta object, an integer, a float, - a callable, or a string path to a callable which takes the request as argument. - Callable must accept a single request argument (Django-Axes 7.0+ signature). - For an integer or float, it will be interpreted as a number of hours: - ``1`` is 1 hour, ``0.5`` is 30 minutes. A ``timedelta`` is recommended for clarity. - See also ``AXES_USE_ATTEMPT_EXPIRATION`` for rolling window behavior. - - * - AXES_USE_ATTEMPT_EXPIRATION - - False - - If ``True``, changes the behavior of ``AXES_COOLOFF_TIME`` to a rolling window - meaning each failed attempt expires individually after the cool-off time. This - allows you to configure a "number of failed login attempts per xx minutes" - rule (e.g. 3 attempts per 15 minutes). When ``True``, only failures inside the - cool-off window are counted (sliding/rolling window behavior). - - If ``False``, ``AXES_COOLOFF_TIME`` acts - as a period of inactivity where attempts are only cleared if no new failures - occur within the cool-off limit. - - * - AXES_ONLY_ADMIN_SITE - - False - - If ``True``, lock is only enabled for admin site. Admin site is determined by - checking request path against the path of ``"admin:index"`` view. If admin urls - are not registered in current urlconf, all requests will not be locked. - - * - AXES_ONLY_USER_FAILURES - - False - - DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, only lock - based on username, and never lock based on IP if attempts exceed the limit. - Otherwise utilize the existing IP and user locking logic. - - * - AXES_ENABLE_ADMIN - - True - - If ``True``, admin views for access attempts and logins are shown in Django - admin interface. - - * - AXES_LOCK_OUT_BY_COMBINATION_USER_AND_IP - - False - - DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, prevent login - from IP under a particular username if the attempt limit has been exceeded, - otherwise lock out based on IP. - - * - AXES_LOCK_OUT_BY_USER_OR_IP - - False - - DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, prevent login - from if the attempt limit has been exceeded for IP or username. - - * - AXES_USE_USER_AGENT - - False - - DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, lock out and - log based on the IP address and the user agent. This means requests from - different user agents but from the same IP are treated differently. This - settings has no effect if the ``AXES_ONLY_USER_FAILURES`` setting is active. - - * - AXES_HANDLER - - 'axes.handlers.database.AxesDatabaseHandler' - - The path to the handler class to use. If set, overrides the default signal - handler backend. Default: ``'axes.handlers.database.AxesDatabaseHandler'`` - - * - AXES_CACHE - - 'default' - - The name of the cache for Axes to use. - - * - AXES_LOCKOUT_TEMPLATE - - None - - If set, specifies a template to render when a user is locked out. Template - receives ``cooloff_timedelta``, ``cooloff_time``, ``username`` and - ``failure_limit`` as context variables. - - * - AXES_LOCKOUT_URL - - None - - If set, specifies a URL to redirect to on lockout. If both - ``AXES_LOCKOUT_TEMPLATE`` and ``AXES_LOCKOUT_URL`` are set, the template will be - used. - - * - AXES_VERBOSE - - True - - If ``True``, you'll see slightly more logging for Axes. - - * - AXES_USERNAME_FORM_FIELD - - 'settings.AUTH_USER_MODEL.USERNAME_FIELD' - - The name of the form field that contains your users usernames. - - * - AXES_USERNAME_CALLABLE - - None - - A callable or a string path to callable that takes two arguments for user - lookups: ``def get_username(request: HttpRequest, credentials: dict) -> str: - ...``. This can be any callable such as ``AXES_USERNAME_CALLABLE = lambda - request, credentials: 'username'`` or a full Python module path to callable such - as ``AXES_USERNAME_CALLABLE = 'example.get_username``. The ``request`` is a - HttpRequest like object and the ``credentials`` is a dictionary like object. - ``credentials`` are the ones that were passed to Django ``authenticate()`` in - the login flow. If no function is supplied, Axes fetches the username from the - ``credentials`` or ``request.POST`` dictionaries based on - ``AXES_USERNAME_FORM_FIELD``. - - * - AXES_WHITELIST_CALLABLE - - None - - A callable or a string path to callable that takes two arguments for - whitelisting determination and returns True, if user should be whitelisted: - ``def is_whitelisted(request: HttpRequest, credentials: dict) -> bool: ...``. - This can be any callable similarly to ``AXES_USERNAME_CALLABLE``. - - * - AXES_LOCKOUT_CALLABLE - - None - - A callable or a string path to callable that takes three arguments returns a - response. For example: ``def generate_lockout_response(request: HttpRequest, - original_response: HttpResponse, credentials: dict) -> HttpResponse: ...``. This - can be any callable similarly to ``AXES_USERNAME_CALLABLE``. If not callable is - defined, then the default implementation in - ``axes.helpers.get_lockout_response`` is used for determining the correct - lockout response that is sent to the requesting client. - - * - AXES_CLIENT_IP_CALLABLE - - None - - A callable or a string path to callable that takes HttpRequest as an argument - and returns the resolved IP as a response. For example: ``def get_ip(request: - HttpRequest) -> str: ...``. This can be any callable similarly to - ``AXES_USERNAME_CALLABLE``. If not callable is defined, then the default - implementation in ``axes.helpers.get_client_ip_address`` is used. - - * - AXES_PASSWORD_FORM_FIELD - - 'password' - - The name of the form or credentials field that contains your users password. - - * - AXES_SENSITIVE_PARAMETERS - - ["username", "ip_address"] - - Configures POST and GET parameter values (in addition to the value of - ``AXES_PASSWORD_FORM_FIELD``) to mask in login attempt logging. Defaults enable - privacy-by-design. - - * - AXES_NEVER_LOCKOUT_GET - - False - - If ``True``, Axes will never lock out HTTP GET requests. - - * - AXES_NEVER_LOCKOUT_WHITELIST - - False - - If ``True``, users can always login from whitelisted IP addresses. - - * - AXES_IP_BLACKLIST - - None - - An iterable of IPs to be blacklisted. Takes precedence over whitelists. For - example: ``AXES_IP_BLACKLIST = ['0.0.0.0']``. - - * - AXES_IP_WHITELIST - - None - - An iterable of IPs to be whitelisted. For example: ``AXES_IP_WHITELIST = - ['0.0.0.0']``. - - * - AXES_DISABLE_ACCESS_LOG - - False - - If ``True``, disable writing login and logout access logs to database, so the - admin interface will not have user login trail for successful user - authentication. - - * - AXES_ENABLE_ACCESS_FAILURE_LOG - - False - - If ``True``, enable writing login failure logs to database, so you will have - every user login trail for unsuccessful user authentication. - - * - AXES_ACCESS_FAILURE_LOG_PER_USER_LIMIT - - 1000 - - Sets the number of failures to trail for each user. When the access failure log - reach this number of records, an automatic removal is ran. - - * - AXES_RESET_ON_SUCCESS - - False - - If ``True``, a successful login will reset the number of failed logins. - - * - AXES_ALLOWED_CORS_ORIGINS - - "*" - - Configures lockout response CORS headers for XHR requests. - - * - AXES_HTTP_RESPONSE_CODE - - 429 - - Sets the http response code returned when ``AXES_FAILURE_LIMIT`` is reached. For - example: ``AXES_HTTP_RESPONSE_CODE = 403`` - - * - AXES_RESET_COOL_OFF_ON_FAILURE_DURING_LOCKOUT - - True - - If ``True``, any new failed login attempt while the user is locked out will - reset their cool-off timer to ``now() + AXES_COOLOFF_TIME``. This means repeated - brute-force attempts will continuously extend the lockout period. - - * - AXES_LOCKOUT_PARAMETERS - - ["ip_address"] - - A list of parameters that Axes uses to lock out users. It can also be callable, - which takes an http request or AccessAttempt object and credentials and returns a - list of parameters. Each parameter can be a string (a single parameter) or a - list of strings (a combined parameter). For example, if you configure - ``AXES_LOCKOUT_PARAMETERS = ["ip_address", ["username", "user_agent"]]``, axes - will block clients by ip and/or username and user agent combination. See - :ref:`customizing-lockout-parameters` for more details. - - ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Variable | Default | Explanation | ++======================================================+==============================================+===========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ +| AXES_ENABLED | True | Enable or disable Axes plugin functionality, for example in test runner setup | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_FAILURE_LIMIT | 3 | The integer number of login attempts allowed before the request is considered locked. This can also be a callable or a dotted path to callable that returns an integer and all of the following are valid: ``AXES_FAILURE_LIMIT = 42``, ``AXES_FAILURE_LIMIT = lambda *args: 42``, and ``AXES_FAILURE_LIMIT = 'project.app.get_login_failure_limit'``. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_LOCK_OUT_AT_FAILURE | True | After the number of allowed login attempts are exceeded, should we lock out this IP (and optional user agent)? | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_COOLOFF_TIME | None | If set, defines the cool-off period after which old failed login attempts are cleared. If ``None``, lockout is permanent until attempts are manually reset. Can be set to a Python timedelta object, an integer, a float, a callable, or a string path to a callable that takes the request as argument. If an integer or float, this is interpreted as hours (``1`` is 1 hour, ``0.5`` is 30 minutes, ``1.7`` is 6120 seconds). ``timedelta`` is recommended for clarity. See also ``AXES_USE_ATTEMPT_EXPIRATION`` for rolling-window behavior. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_USE_ATTEMPT_EXPIRATION | False | If ``True``, changes ``AXES_COOLOFF_TIME`` to a rolling window where each failed attempt expires individually after the cool-off time. This enables policies like "3 failed login attempts per 15 minutes". If ``False``, ``AXES_COOLOFF_TIME`` acts as an inactivity period where attempts are cleared only after no new failures occur within the cool-off limit. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_ONLY_ADMIN_SITE | False | If ``True``, lock is only enabled for admin site. Admin site is determined by checking request path against the path of ``"admin:index"`` view. If admin urls are not registered in current urlconf, all requests will not be locked. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_ONLY_USER_FAILURES | False | DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, only lock based on username, and never lock based on IP if attempts exceed the limit. Otherwise utilize the existing IP and user locking logic. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_ENABLE_ADMIN | True | If ``True``, admin views for access attempts and logins are shown in Django admin interface. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_LOCK_OUT_BY_COMBINATION_USER_AND_IP | False | DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, prevent login from IP under a particular username if the attempt limit has been exceeded, otherwise lock out based on IP. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_LOCK_OUT_BY_USER_OR_IP | False | DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, prevent login from if the attempt limit has been exceeded for IP or username. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_USE_USER_AGENT | False | DEPRECATED: USE ``AXES_LOCKOUT_PARAMETERS`` INSTEAD. If ``True``, lock out and log based on the IP address and the user agent. This means requests from different user agents but from the same IP are treated differently. This settings has no effect if the ``AXES_ONLY_USER_FAILURES`` setting is active. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_HANDLER | 'axes.handlers.database.AxesDatabaseHandler' | The path to the handler class to use. If set, overrides the default signal handler backend. Default: ``'axes.handlers.database.AxesDatabaseHandler'`` | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_CACHE | 'default' | The name of the cache for Axes to use. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_LOCKOUT_TEMPLATE | None | If set, specifies a template to render when a user is locked out. Template receives ``cooloff_timedelta``, ``cooloff_time``, ``username`` and ``failure_limit`` as context variables. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_LOCKOUT_URL | None | If set, specifies a URL to redirect to on lockout. If both ``AXES_LOCKOUT_TEMPLATE`` and ``AXES_LOCKOUT_URL`` are set, the template will be used. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_VERBOSE | True | If ``True``, you'll see slightly more logging for Axes. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_USERNAME_FORM_FIELD | 'settings.AUTH_USER_MODEL.USERNAME_FIELD' | The name of the form field that contains your users usernames. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_USERNAME_CALLABLE | None | A callable or a string path to callable that takes two arguments for user lookups: ``def get_username(request: HttpRequest, credentials: dict) -> str: ...``. This can be any callable such as ``AXES_USERNAME_CALLABLE = lambda request, credentials: 'username'`` or a full Python module path to callable such as ``AXES_USERNAME_CALLABLE = 'example.get_username``. The ``request`` is a HttpRequest like object and the ``credentials`` is a dictionary like object. ``credentials`` are the ones that were passed to Django ``authenticate()`` in the login flow. If no function is supplied, Axes fetches the username from the ``credentials`` or ``request.POST`` dictionaries based on ``AXES_USERNAME_FORM_FIELD``. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_WHITELIST_CALLABLE | None | A callable or a string path to callable that takes two arguments for whitelisting determination and returns True, if user should be whitelisted: ``def is_whitelisted(request: HttpRequest, credentials: dict) -> bool: ...``. This can be any callable similarly to ``AXES_USERNAME_CALLABLE``. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_LOCKOUT_CALLABLE | None | A callable or a string path to callable that takes three arguments returns a response. For example: ``def generate_lockout_response(request: HttpRequest, original_response: HttpResponse, credentials: dict) -> HttpResponse: ...``. This can be any callable similarly to ``AXES_USERNAME_CALLABLE``. If not callable is defined, then the default implementation in ``axes.helpers.get_lockout_response`` is used for determining the correct lockout response that is sent to the requesting client. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_CLIENT_IP_CALLABLE | None | A callable or a string path to callable that takes HttpRequest as an argument and returns the resolved IP as a response. For example: ``def get_ip(request: HttpRequest) -> str: ...``. This can be any callable similarly to ``AXES_USERNAME_CALLABLE``. If not callable is defined, then the default implementation in ``axes.helpers.get_client_ip_address`` is used. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_PASSWORD_FORM_FIELD | 'password' | The name of the form or credentials field that contains your users password. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_SENSITIVE_PARAMETERS | ["username", "ip_address"] | Configures POST and GET parameter values (in addition to the value of ``AXES_PASSWORD_FORM_FIELD``) to mask in login attempt logging. Defaults enable privacy-by-design. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_NEVER_LOCKOUT_GET | False | If ``True``, Axes will never lock out HTTP GET requests. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_NEVER_LOCKOUT_WHITELIST | False | If ``True``, users can always login from whitelisted IP addresses. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_IP_BLACKLIST | None | An iterable of IPs to be blacklisted. Takes precedence over whitelists. For example: ``AXES_IP_BLACKLIST = ['0.0.0.0']``. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_IP_WHITELIST | None | An iterable of IPs to be whitelisted. For example: ``AXES_IP_WHITELIST = ['0.0.0.0']``. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_DISABLE_ACCESS_LOG | False | If ``True``, disable writing login and logout access logs to database, so the admin interface will not have user login trail for successful user authentication. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_ENABLE_ACCESS_FAILURE_LOG | False | If ``True``, enable writing login failure logs to database, so you will have every user login trail for unsuccessful user authentication. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_ACCESS_FAILURE_LOG_PER_USER_LIMIT | 1000 | Sets the number of failures to trail for each user. When the access failure log reach this number of records, an automatic removal is ran. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_RESET_ON_SUCCESS | False | If ``True``, a successful login will reset the number of failed logins. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_ALLOWED_CORS_ORIGINS | "*" | Configures lockout response CORS headers for XHR requests. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_HTTP_RESPONSE_CODE | 429 | Sets the http response code returned when ``AXES_FAILURE_LIMIT`` is reached. For example: ``AXES_HTTP_RESPONSE_CODE = 403`` | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_RESET_COOL_OFF_ON_FAILURE_DURING_LOCKOUT | True | If ``True``, any failed login attempt during lockout resets the cool-off timer to ``now() + AXES_COOLOFF_TIME``. Repeated failed attempts keep extending the lockout period. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| AXES_LOCKOUT_PARAMETERS | ["ip_address"] | A list of parameters that Axes uses to lock out users. It can also be callable, which takes an http request or AccesAttempt object and credentials and returns a list of parameters. Each parameter can be a string (a single parameter) or a list of strings (a combined parameter). For example, if you configure ``AXES_LOCKOUT_PARAMETERS = ["ip_address", ["username", "user_agent"]]``, axes will block clients by ip and/or username and user agent combination. See :ref:`customizing-lockout-parameters` for more details. | ++------------------------------------------------------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ **Common configurations**