From 05fe0e306b3a19d2f9961b4856665653ff0cd00b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleksi=20Ha=CC=88kli?= Date: Sun, 19 May 2019 16:40:23 +0300 Subject: [PATCH] Improve docs for attempt tracking, resets, and customization Fixes #433 --- CHANGES.rst | 3 ++ docs/3_usage.rst | 83 +++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 81 insertions(+), 5 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 04cc5a8..0dd9c9a 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -11,6 +11,9 @@ Changes Deprecate ``axes.request.AxesHttpRequest`` object type definition. [aleksihakli] +- Improve documentation on attempt tracking, resets, and customization. + [aleksihakli] + 5.0.4 (2019-05-09) ------------------ diff --git a/docs/3_usage.rst b/docs/3_usage.rst index a430713..bdf3320 100644 --- a/docs/3_usage.rst +++ b/docs/3_usage.rst @@ -7,13 +7,82 @@ Once Axes is is installed and configured, you can login and logout of your application via the ``django.contrib.auth`` views. The attempts will be logged and visible in the Access Attempts section in admin. -By default, Axes will lock out repeated access attempts from the same IP address. -You can allow this IP to attempt again by deleting relevant AccessAttempt records. +Axes monitors the views by using the Django login and logout signals and +locks out user attempts with a custom authentication backend that checks +if requests are allowed to authenticate per the configured rules. -Records can be deleted, for example, by using the Django admin application. +By default, Axes will lock out repeated access attempts from the same IP address +by monitoring login failures and storing them into the default database. -You can also use the ``axes_reset``, ``axes_reset_ip``, and ``axes_reset_username`` -management commands with the Django ``manage.py`` command helpers: + +Authenticating users +-------------------- + +Axes needs a ``request`` attribute to be supplied to the stock Django ``authenticate`` +method in the ``django.contrib.auth`` module in order to function correctly. + +If you wish to manually supply the argument to the calls to ``authenticate``, +you can use the following snippet in your custom login views, tests, or other code:: + + + def custom_login_view(request) + username = ... + password = ... + + user = authenticate( + request=request, # this is the important custom argument + username=username, + password=password, + ) + + if user is not None: + login(request, user) + + +If your test setup has problems with the ``request`` argument, you can either +supply the argument manually with a blank `HttpRequest()`` object, +disable Axes in the test setup by excluding ``axes`` from ``INSTALLED_APPS``, +or leave out ``axes.backends.AxesBackend`` from your ``AUTHENTICATION_BACKENDS``. + +If you are using a 3rd party library that does not supply the ``request`` attribute +when calling ``authenticate`` you can implement a customized backend that inherits +from ``axes.backends.AxesBackend`` or other backend and overrides the ``authenticate`` method. + + +Resetting attempts and lockouts +------------------------------- + +When Axes locks an IP address, it is not allowed to login again. +You can allow IPs to attempt again by resetting (deleting) +the relevant AccessAttempt records. + +You can also configure automatic cool down periods, IP whitelists and blacklists +and even custom programmatic functions for the lockouts. Please check out the +configuration and customization documentation for further information. + +.. note:: + Please note that the functionality describe here concerns the default + database attempt tracker and handler. If you have customized or changed + the default handler to another class such as the cache handler, + you have to implement custom reset commands for it. + + +Resetting attempts from the Django admin UI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Records can be easily deleted by using the Django admin application. + +Go to the admin UI and check the ``Access Attempt`` view. +Select the attempts you wish the allow again and simply remove them. +The blocked user will be allowed to log in again in accordance to the rules. + + +Resetting attempts from command line +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Axes offers a command line interface with +``axes_reset``, ``axes_reset_ip``, and ``axes_reset_username`` +management commands with the Django ``manage.py`` or ``django-admin`` command helpers: - ``python manage.py axes_reset`` will reset all lockouts and access records. @@ -22,6 +91,10 @@ management commands with the Django ``manage.py`` command helpers: - ``python manage.py axes_reset_username [username ...]`` will clear lockouts and records for the given usernames. + +Resetting attempts programmatically by APIs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + In your code, you can use the ``axes.utils.reset`` function. - ``reset()`` will reset all lockouts and access records.