Fixed #18763 -- Added ModelBackend/UserManager.with_perm() methods.

Co-authored-by: Nick Pope <nick.pope@flightdataservices.com>

3 files changed, 48 insertions, 3 deletions

diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt
index 666208b28c..75202ebe4b 100644
--- a/docs/ref/contrib/auth.txt
+++ b/docs/ref/contrib/auth.txt
@@ -291,6 +291,28 @@ Manager methods
 
             The ``email`` and ``password`` parameters were made optional.
 
+    .. method:: with_perm(perm, is_active=True, include_superusers=True, backend=None, obj=None)
+
+        .. versionadded:: 3.0
+
+        Returns users that have the given permission ``perm`` either in the
+        ``"<app label>.<permission codename>"`` format or as a
+        :class:`~django.contrib.auth.models.Permission` instance. Returns an
+        empty queryset if no users who have the ``perm`` found.
+
+        If ``is_active`` is ``True`` (default), returns only active users, or
+        if ``False``, returns only inactive users. Use ``None`` to return all
+        users irrespective of active state.
+
+        If ``include_superusers`` is ``True`` (default), the result will
+        include superusers.
+
+        If ``backend`` is passed in and it's defined in
+        :setting:`AUTHENTICATION_BACKENDS`, then this method will use it.
+        Otherwise, it will use the ``backend`` in
+        :setting:`AUTHENTICATION_BACKENDS`, if there is only one, or raise an
+        exception.
+
 ``AnonymousUser`` object
 ========================
 
@@ -520,6 +542,9 @@ The following backends are available in :mod:`django.contrib.auth.backends`:
     implement them other than returning an empty set of permissions if
     ``obj is not None``.
 
+    :meth:`with_perm` also allows an object to be passed as a parameter, but
+    unlike others methods it returns an empty queryset if ``obj is not None``.
+
     .. method:: authenticate(request, username=None, password=None, **kwargs)
 
         Tries to authenticate ``username`` with ``password`` by calling
@@ -577,6 +602,22 @@ The following backends are available in :mod:`django.contrib.auth.backends`:
         don't have an :attr:`~django.contrib.auth.models.CustomUser.is_active`
         field are allowed.
 
+    .. method:: with_perm(perm, is_active=True, include_superusers=True, obj=None)
+
+        .. versionadded:: 3.0
+
+        Returns all active users who have the permission ``perm`` either in
+        the form of ``"<app label>.<permission codename>"`` or a
+        :class:`~django.contrib.auth.models.Permission` instance. Returns an
+        empty queryset if no users who have the ``perm`` found.
+
+        If ``is_active`` is ``True`` (default), returns only active users, or
+        if ``False``, returns only inactive users. Use ``None`` to return all
+        users irrespective of active state.
+
+        If ``include_superusers`` is ``True`` (default), the result will
+        include superusers.
+
 .. class:: AllowAllUsersModelBackend
 
     Same as :class:`ModelBackend` except that it doesn't reject inactive users
diff --git a/docs/releases/3.0.txt b/docs/releases/3.0.txt
index f6ec8f8cc7..7a9adb3b39 100644
--- a/docs/releases/3.0.txt
+++ b/docs/releases/3.0.txt
@@ -128,6 +128,9 @@ Minor features
 * :attr:`~django.contrib.auth.models.CustomUser.REQUIRED_FIELDS` now supports
   :class:`~django.db.models.ManyToManyField`\s.
 
+* The new :meth:`.UserManager.with_perm` method returns users that have the
+  specified permission.
+
 :mod:`django.contrib.contenttypes`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt
index d2a4746e03..4c9515fe53 100644
--- a/docs/topics/auth/customizing.txt
+++ b/docs/topics/auth/customizing.txt
@@ -179,12 +179,13 @@ Handling authorization in custom backends
 
 Custom auth backends can provide their own permissions.
 
-The user model will delegate permission lookup functions
+The user model and its manager will delegate permission lookup functions
 (:meth:`~django.contrib.auth.models.User.get_user_permissions()`,
 :meth:`~django.contrib.auth.models.User.get_group_permissions()`,
 :meth:`~django.contrib.auth.models.User.get_all_permissions()`,
-:meth:`~django.contrib.auth.models.User.has_perm()`, and
-:meth:`~django.contrib.auth.models.User.has_module_perms()`) to any
+:meth:`~django.contrib.auth.models.User.has_perm()`,
+:meth:`~django.contrib.auth.models.User.has_module_perms()`, and
+:meth:`~django.contrib.auth.models.UserManager.with_perm()`) to any
 authentication backend that implements these functions.
 
 The permissions given to the user will be the superset of all permissions