diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index c762457839e..4aab186c8b9 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -502,26 +502,50 @@ every incoming ``HttpRequest`` object. See :ref:`Authentication in web requests .. versionadded:: 5.1 -Redirects all unauthenticated requests to a login page. For admin views, this -redirects to the admin login. For all other views, this will redirect to -:setting:`settings.LOGIN_URL `. This can be customized by using the -:func:`~.django.contrib.auth.decorators.login_required` decorator and setting -``login_url`` or ``redirect_field_name`` for the view. For example:: +Redirects all unauthenticated requests to a login page, except for views +excluded with :func:`~.django.contrib.auth.decorators.login_not_required`. The +login page defaults to :setting:`settings.LOGIN_URL `, but can be +customized. + +Enable this middleware by adding it to the :setting:`MIDDLEWARE` setting +**after** :class:`~django.contrib.auth.middleware.AuthenticationMiddleware`:: + + MIDDLEWARE = [ + "...", + "django.contrib.auth.middleware.AuthenticationMiddleware", + "django.contrib.auth.middleware.LoginRequiredMiddleware", + "...", + ] + +Make a view public, allowing unauthenticated requests, with +:func:`~.django.contrib.auth.decorators.login_not_required`. For example:: + + from django.contrib.auth.decorators import login_not_required + + + @login_not_required + def contact_us(request): ... + +Customize the login URL or field name for authenticated views with the +:func:`~.django.contrib.auth.decorators.login_required` decorator to set +``login_url`` or ``redirect_field_name`` respectively. For example:: + + from django.contrib.auth.decorators import login_required + from django.utils.decorators import method_decorator + from django.views.generic import View + + + @login_required(login_url="/books/login/", redirect_field_name="redirect_to") + def book_dashboard(request): ... + @method_decorator( - login_required(login_url="/login/", redirect_field_name="redirect_to"), + login_required(login_url="/books/login/", redirect_field_name="redirect_to"), name="dispatch", ) - class MyView(View): + class BookMetrics(View): pass - - @login_required(login_url="/login/", redirect_field_name="redirect_to") - def my_view(request): ... - -Views using the :func:`~django.contrib.auth.decorators.login_not_required` -decorator are exempt from this requirement. - .. admonition:: Ensure that your login view does not require a login. To prevent infinite redirects, ensure you have @@ -530,6 +554,9 @@ decorator are exempt from this requirement. **Methods and Attributes** +Subclass the middleware and override these to customize behavior for +unauthenticated requests. + .. attribute:: redirect_field_name Defaults to ``"next"``. diff --git a/docs/releases/5.1.txt b/docs/releases/5.1.txt index 40b59eb0911..f47fa8bd3ff 100644 --- a/docs/releases/5.1.txt +++ b/docs/releases/5.1.txt @@ -91,12 +91,15 @@ redirects all unauthenticated requests to a login page. Views can allow unauthenticated requests by using the new :func:`~django.contrib.auth.decorators.login_not_required` decorator. -The :class:`~django.contrib.auth.middleware.LoginRequiredMiddleware` respects -the ``login_url`` and ``redirect_field_name`` values set via the +``LoginRequiredMiddleware`` respects the ``login_url`` and +``redirect_field_name`` values set via the :func:`~.django.contrib.auth.decorators.login_required` decorator, but does not support setting ``login_url`` or ``redirect_field_name`` via the :class:`~django.contrib.auth.mixins.LoginRequiredMixin`. +To enable this, add ``"django.contrib.auth.middleware.LoginRequiredMiddleware"`` +to your :setting:`MIDDLEWARE` setting. + Minor features -------------- diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt index 56f867ede50..b0599e4be2e 100644 --- a/docs/topics/auth/default.txt +++ b/docs/topics/auth/default.txt @@ -655,7 +655,7 @@ login view, may need to disable this behavior. .. function:: login_not_required() - Allows unauthenticated requests without redirecting to the login page when + Allows unauthenticated requests to this view when :class:`~django.contrib.auth.middleware.LoginRequiredMiddleware` is installed.