From 5ab820db6ab8777862a1f8222e726e8a2835a8eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleksi=20Ha=CC=88kli?= Date: Sat, 25 May 2019 21:12:49 +0300 Subject: [PATCH] Update architecture docs for exception handling Version 5.0.5 migrated from exceptions to request flagging which alters the internal behaviour slightly. --- axes/backends.py | 5 ++--- axes/middleware.py | 12 ++++-------- docs/7_architecture.rst | 17 ++++------------- 3 files changed, 10 insertions(+), 24 deletions(-) diff --git a/axes/backends.py b/axes/backends.py index 2642e0a..f6c0a4f 100644 --- a/axes/backends.py +++ b/axes/backends.py @@ -47,8 +47,7 @@ class AxesBackend(ModelBackend): # Raise an error that stops the authentication flows at django.contrib.auth.authenticate. # This error stops bubbling up at the authenticate call which catches backend PermissionDenied errors. # After this error is caught by authenticate it emits a signal indicating user login failed, - # which is processed by axes.signals.log_user_login_failed which logs the attempt and raises - # a second exception which bubbles up the middleware stack and produces a HTTP 403 Forbidden reply - # in the axes.middleware.AxesMiddleware.process_exception middleware exception handler. + # which is processed by axes.signals.log_user_login_failed which logs and flags the failed request. + # The axes.middleware.AxesMiddleware further processes the flagged request into a readable response. raise AxesBackendPermissionDenied('AxesBackend detected that the given user is locked out') diff --git a/axes/middleware.py b/axes/middleware.py index 2b1087d..8868a6d 100644 --- a/axes/middleware.py +++ b/axes/middleware.py @@ -8,16 +8,12 @@ class AxesMiddleware: Middleware that calculates necessary HTTP request attributes for attempt monitoring and maps lockout signals into readable HTTP 403 Forbidden responses. - By default Django server returns ``PermissionDenied`` exceptions as HTTP 403 errors - with the ``django.views.defaults.permission_denied`` view that renders - the ``403.html`` template from the root template directory if found. - - This middleware recognizes the specialized attempt monitoring and lockout exceptions + This middleware recognizes a logout monitoring flag in the request and and uses the ``axes.helpers.get_lockout_response`` handler for returning - customizable and context aware lockout message to the end user. + customizable and context aware lockout message to the end user if necessary. - To customize the error handling behaviour further, you can subclass this middleware - and change the ``process_exception`` handler to your own liking. + To customize the lockout handling behaviour further, you can subclass this middleware + and change the ``__call__`` method to your own liking. Please see the following configuration flags before customizing this handler: diff --git a/docs/7_architecture.rst b/docs/7_architecture.rst index 320f148..660e9fd 100644 --- a/docs/7_architecture.rst +++ b/docs/7_architecture.rst @@ -34,10 +34,6 @@ it can raise a ``django.core.exceptions.PermissionDenied`` exception. If a login fails, Django then fires a ``from django.contrib.auth.signals.user_login_failed`` signal. -If this signal raises an exception, it is propagated through the -Django middleware stack where it can be caught, or alternatively -where it can bubble up to the default Django exception handlers. - A normal login flow for Django runs as follows: .. code-block:: text @@ -78,10 +74,6 @@ are not blocked, and allows the requests to go through if the check passes. If any of the checks fails, an exception is raised which interrupts the login process and triggers the Django login failed signal handlers. -Another exception is raised by a Axes signal handler, which is -then caught by ``AxesMiddleware`` and converted into a readable -error because the user is currently locked out of the system. - Axes implements the lockout flow as follows: .. code-block:: text @@ -113,12 +105,11 @@ Axes implements the lockout flow as follows: 7. Axes logs the failure and increments the failure counters which keep track of failure statistics. + Axes then updates the request object with a logout + status flag that can be processed by + view or middleware code as needed. - 8. AxesSignalPermissionDenied exception is raised - if appropriate and it bubbles up the middleware stack. - The exception aborts the Django authentication flow. - - 9. AxesMiddleware processes the exception + 8. AxesMiddleware processes the lockout request and response and returns a readable lockout message to the user. This plugin assumes that the login views either call