Debian Codegraph @

docs/ref/contrib/auth.txt

raw
1 =======================
2 ``django.contrib.auth``
3 =======================
4
5 This document provides API reference material for the components of Django's
6 authentication system. For more details on the usage of these components or
7 how to customize authentication and authorization see the :doc:`authentication
8 topic guide </topics/auth/index>`.
9
10 .. currentmodule:: django.contrib.auth
11
12 ``User`` model
13 ==============
14
15 .. class:: models.User
16
17 Fields
18 ------
19
20 .. class:: models.User
21 :noindex:
22
23 :class:`~django.contrib.auth.models.User` objects have the following
24 fields:
25
26 .. attribute:: username
27
28 Required. 150 characters or fewer. Usernames may contain alphanumeric,
29 ``_``, ``@``, ``+``, ``.`` and ``-`` characters.
30
31 The ``max_length`` should be sufficient for many use cases. If you need
32 a longer length, please use a :ref:`custom user model
33 <specifying-custom-user-model>`.
34
35 .. attribute:: first_name
36
37 Optional (:attr:`blank=True <django.db.models.Field.blank>`). 150
38 characters or fewer.
39
40 .. attribute:: last_name
41
42 Optional (:attr:`blank=True <django.db.models.Field.blank>`). 150
43 characters or fewer.
44
45 .. attribute:: email
46
47 Optional (:attr:`blank=True <django.db.models.Field.blank>`). Email
48 address.
49
50 .. attribute:: password
51
52 Required. A hash of, and metadata about, the password. (Django doesn't
53 store the raw password.) Raw passwords can be arbitrarily long and can
54 contain any character. The metadata in this field may mark the password
55 as unusable. See the :doc:`password documentation
56 </topics/auth/passwords>`.
57
58 .. attribute:: groups
59
60 Many-to-many relationship to :class:`~django.contrib.auth.models.Group`
61
62 .. attribute:: user_permissions
63
64 Many-to-many relationship to :class:`~django.contrib.auth.models.Permission`
65
66 .. attribute:: is_staff
67
68 Boolean. Allows this user to access the admin site.
69
70 .. attribute:: is_active
71
72 Boolean. Marks this user account as active. We recommend that you set
73 this flag to ``False`` instead of deleting accounts. That way, if your
74 applications have any foreign keys to users, the foreign keys won't
75 break.
76
77 This doesn't necessarily control whether or not the user can log in.
78 Authentication backends aren't required to check for the ``is_active``
79 flag but the default backend
80 (:class:`~django.contrib.auth.backends.ModelBackend`) and the
81 :class:`~django.contrib.auth.backends.RemoteUserBackend` do. You can
82 use :class:`~django.contrib.auth.backends.AllowAllUsersModelBackend`
83 or :class:`~django.contrib.auth.backends.AllowAllUsersRemoteUserBackend`
84 if you want to allow inactive users to login. In this case, you'll also
85 want to customize the
86 :class:`~django.contrib.auth.forms.AuthenticationForm` used by the
87 :class:`~django.contrib.auth.views.LoginView` as it rejects inactive
88 users. Be aware that the permission-checking methods such as
89 :meth:`~django.contrib.auth.models.User.has_perm` and the
90 authentication in the Django admin all return ``False`` for inactive
91 users.
92
93 .. attribute:: is_superuser
94
95 Boolean. Treats this user as having all permissions without assigning
96 any permission to it in particular.
97
98 .. attribute:: last_login
99
100 A datetime of the user's last login.
101
102 .. attribute:: date_joined
103
104 The date/time when the account was created.
105
106 Attributes
107 ----------
108
109 .. class:: models.User
110 :noindex:
111
112 .. attribute:: is_authenticated
113
114 Read-only attribute which is always ``True`` (as opposed to
115 ``AnonymousUser.is_authenticated`` which is always ``False``). This is
116 a way to tell if the user has been authenticated. This does not imply
117 any permissions and doesn't check if the user is active or has a valid
118 session. Even though normally you will check this attribute on
119 ``request.user`` to find out whether it has been populated by the
120 :class:`~django.contrib.auth.middleware.AuthenticationMiddleware`
121 (representing the currently logged-in user), you should know this
122 attribute is ``True`` for any :class:`~models.User` instance.
123
124 .. attribute:: is_anonymous
125
126 Read-only attribute which is always ``False``. This is a way of
127 differentiating :class:`~models.User` and :class:`~models.AnonymousUser`
128 objects. Generally, you should prefer using
129 :attr:`~django.contrib.auth.models.User.is_authenticated` to this
130 attribute.
131
132 Methods
133 -------
134
135 .. class:: models.User
136 :noindex:
137
138 .. method:: get_username()
139
140 Returns the username for the user. Since the ``User`` model can be
141 swapped out, you should use this method instead of referencing the
142 username attribute directly.
143
144 .. method:: get_full_name()
145
146 Returns the :attr:`~django.contrib.auth.models.User.first_name` plus
147 the :attr:`~django.contrib.auth.models.User.last_name`, with a space in
148 between.
149
150 .. method:: get_short_name()
151
152 Returns the :attr:`~django.contrib.auth.models.User.first_name`.
153
154 .. method:: set_password(raw_password)
155
156 Sets the user's password to the given raw string, taking care of the
157 password hashing. Doesn't save the
158 :class:`~django.contrib.auth.models.User` object.
159
160 When the ``raw_password`` is ``None``, the password will be set to an
161 unusable password, as if
162 :meth:`~django.contrib.auth.models.User.set_unusable_password()`
163 were used.
164
165 .. method:: check_password(raw_password)
166 .. method:: acheck_password(raw_password)
167
168 *Asynchronous version*: ``acheck_password()``
169
170 Returns ``True`` if the given raw string is the correct password for
171 the user. (This takes care of the password hashing in making the
172 comparison.)
173
174 .. method:: set_unusable_password()
175
176 Marks the user as having no password set by updating the metadata in
177 the :attr:`~django.contrib.auth.models.User.password` field. This isn't
178 the same as having a blank string for a password.
179 :meth:`~django.contrib.auth.models.User.check_password()` for this user
180 will never return ``True``. Doesn't save the
181 :class:`~django.contrib.auth.models.User` object.
182
183 You may need this if authentication for your application takes place
184 against an existing external source such as an LDAP directory.
185
186 .. admonition:: Password reset restriction
187
188 Users having an unusable password will not able to request a
189 password reset email via
190 :class:`~django.contrib.auth.views.PasswordResetView`.
191
192 .. method:: has_usable_password()
193
194 Returns ``False`` if
195 :meth:`~django.contrib.auth.models.User.set_unusable_password()` has
196 been called for this user.
197
198 .. method:: get_user_permissions(obj=None)
199 .. method:: aget_user_permissions(obj=None)
200
201 *Asynchronous version*: ``aget_user_permissions()``
202
203 Returns a set of permission strings that the user has directly.
204
205 If ``obj`` is passed in, only returns the user permissions for this
206 specific object.
207
208 .. versionchanged:: 5.2
209
210 ``aget_user_permissions()`` method was added.
211
212 .. method:: get_group_permissions(obj=None)
213 .. method:: aget_group_permissions(obj=None)
214
215 *Asynchronous version*: ``aget_group_permissions()``
216
217 Returns a set of permission strings that the user has, through their
218 groups.
219
220 If ``obj`` is passed in, only returns the group permissions for
221 this specific object.
222
223 .. versionchanged:: 5.2
224
225 ``aget_group_permissions()`` method was added.
226
227 .. method:: get_all_permissions(obj=None)
228 .. method:: aget_all_permissions(obj=None)
229
230 *Asynchronous version*: ``aget_all_permissions()``
231
232 Returns a set of permission strings that the user has, both through
233 group and user permissions.
234
235 If ``obj`` is passed in, only returns the permissions for this
236 specific object.
237
238 .. versionchanged:: 5.2
239
240 ``aget_all_permissions()`` method was added.
241
242 .. method:: has_perm(perm, obj=None)
243 .. method:: ahas_perm(perm, obj=None)
244
245 *Asynchronous version*: ``ahas_perm()``
246
247 Returns ``True`` if the user has the specified permission, where perm
248 is in the format ``"<app label>.<permission codename>"``. (see
249 documentation on :ref:`permissions <topic-authorization>`). If the user is
250 inactive, this method will always return ``False``. For an active
251 superuser, this method will always return ``True``.
252
253 If ``obj`` is passed in, this method won't check for a permission for
254 the model, but for this specific object.
255
256 .. versionchanged:: 5.2
257
258 ``ahas_perm()`` method was added.
259
260 .. method:: has_perms(perm_list, obj=None)
261 .. method:: ahas_perms(perm_list, obj=None)
262
263 *Asynchronous version*: ``ahas_perms()``
264
265 Returns ``True`` if the user has each of the specified permissions,
266 where each perm is in the format
267 ``"<app label>.<permission codename>"``. If the user is inactive,
268 this method will always return ``False``. For an active superuser, this
269 method will always return ``True``.
270
271 If ``obj`` is passed in, this method won't check for permissions for
272 the model, but for the specific object.
273
274 .. versionchanged:: 5.2
275
276 ``ahas_perms()`` method was added.
277
278 .. method:: has_module_perms(package_name)
279 .. method:: ahas_module_perms(package_name)
280
281 *Asynchronous version*: ``ahas_module_perms()``
282
283 Returns ``True`` if the user has any permissions in the given package
284 (the Django app label). If the user is inactive, this method will
285 always return ``False``. For an active superuser, this method will
286 always return ``True``.
287
288 .. versionchanged:: 5.2
289
290 ``ahas_module_perms()`` method was added.
291
292 .. method:: email_user(subject, message, from_email=None, **kwargs)
293
294 Sends an email to the user. If ``from_email`` is ``None``, Django uses
295 the :setting:`DEFAULT_FROM_EMAIL`. Any ``**kwargs`` are passed to the
296 underlying :func:`~django.core.mail.send_mail` call.
297
298 Manager methods
299 ---------------
300
301 .. class:: models.UserManager
302
303 The :class:`~django.contrib.auth.models.User` model has a custom manager
304 that has the following helper methods (in addition to the methods provided
305 by :class:`~django.contrib.auth.models.BaseUserManager`):
306
307 .. method:: create_user(username, email=None, password=None, **extra_fields)
308 .. method:: acreate_user(username, email=None, password=None, **extra_fields)
309
310 *Asynchronous version*: ``acreate_user()``
311
312 Creates, saves and returns a :class:`~django.contrib.auth.models.User`.
313
314 The :attr:`~django.contrib.auth.models.User.username` and
315 :attr:`~django.contrib.auth.models.User.password` are set as given. The
316 domain portion of :attr:`~django.contrib.auth.models.User.email` is
317 automatically converted to lowercase, and the returned
318 :class:`~django.contrib.auth.models.User` object will have
319 :attr:`~django.contrib.auth.models.User.is_active` set to ``True``.
320
321 If no password is provided,
322 :meth:`~django.contrib.auth.models.User.set_unusable_password()` will
323 be called.
324
325 If no email is provided, :attr:`~django.contrib.auth.models.User.email`
326 will be set to an empty string.
327
328 The ``extra_fields`` keyword arguments are passed through to the
329 :class:`~django.contrib.auth.models.User`’s ``__init__`` method to
330 allow setting arbitrary fields on a :ref:`custom user model
331 <auth-custom-user>`.
332
333 See :ref:`Creating users <topics-auth-creating-users>` for example usage.
334
335 .. versionchanged:: 5.2
336
337 ``acreate_user()`` method was added.
338
339 .. method:: create_superuser(username, email=None, password=None, **extra_fields)
340 .. method:: acreate_superuser(username, email=None, password=None, **extra_fields)
341
342 *Asynchronous version*: ``acreate_superuser()``
343
344 Same as :meth:`create_user`, but sets :attr:`~models.User.is_staff` and
345 :attr:`~models.User.is_superuser` to ``True``.
346
347 .. versionchanged:: 5.2
348
349 ``acreate_superuser()`` method was added.
350
351 .. method:: with_perm(perm, is_active=True, include_superusers=True, backend=None, obj=None)
352
353 Returns users that have the given permission ``perm`` either in the
354 ``"<app label>.<permission codename>"`` format or as a
355 :class:`~django.contrib.auth.models.Permission` instance. Returns an
356 empty queryset if no users who have the ``perm`` found.
357
358 If ``is_active`` is ``True`` (default), returns only active users, or
359 if ``False``, returns only inactive users. Use ``None`` to return all
360 users irrespective of active state.
361
362 If ``include_superusers`` is ``True`` (default), the result will
363 include superusers.
364
365 If ``backend`` is passed in and it's defined in
366 :setting:`AUTHENTICATION_BACKENDS`, then this method will use it.
367 Otherwise, it will use the ``backend`` in
368 :setting:`AUTHENTICATION_BACKENDS`, if there is only one, or raise an
369 exception.
370
371 ``AnonymousUser`` object
372 ========================
373
374 .. class:: models.AnonymousUser
375
376 :class:`django.contrib.auth.models.AnonymousUser` is a class that
377 implements the :class:`django.contrib.auth.models.User` interface, with
378 these differences:
379
380 * :ref:`id <automatic-primary-key-fields>` is always ``None``.
381 * :attr:`~django.contrib.auth.models.User.username` is always the empty
382 string.
383 * :meth:`~django.contrib.auth.models.User.get_username()` always returns
384 the empty string.
385 * :attr:`~django.contrib.auth.models.User.is_anonymous` is ``True``
386 instead of ``False``.
387 * :attr:`~django.contrib.auth.models.User.is_authenticated` is
388 ``False`` instead of ``True``.
389 * :attr:`~django.contrib.auth.models.User.is_staff` and
390 :attr:`~django.contrib.auth.models.User.is_superuser` are always
391 ``False``.
392 * :attr:`~django.contrib.auth.models.User.is_active` is always ``False``.
393 * :attr:`~django.contrib.auth.models.User.groups` and
394 :attr:`~django.contrib.auth.models.User.user_permissions` are always
395 empty.
396 * :meth:`~django.contrib.auth.models.User.set_password()`,
397 :meth:`~django.contrib.auth.models.User.check_password()`,
398 :meth:`~django.db.models.Model.save` and
399 :meth:`~django.db.models.Model.delete()` raise :exc:`NotImplementedError`.
400
401 In practice, you probably won't need to use
402 :class:`~django.contrib.auth.models.AnonymousUser` objects on your own, but
403 they're used by web requests, as explained in the next section.
404
405 ``Permission`` model
406 ====================
407
408 .. class:: models.Permission
409
410 Fields
411 ------
412
413 :class:`~django.contrib.auth.models.Permission` objects have the following
414 fields:
415
416 .. class:: models.Permission
417 :noindex:
418
419 .. attribute:: name
420
421 Required. 255 characters or fewer. Example: ``'Can vote'``.
422
423 .. attribute:: content_type
424
425 Required. A foreign key to the
426 :class:`~django.contrib.contenttypes.models.ContentType` model.
427
428 .. attribute:: codename
429
430 Required. 100 characters or fewer. Example: ``'can_vote'``.
431
432 Methods
433 -------
434
435 :class:`~django.contrib.auth.models.Permission` objects have the standard
436 data-access methods like any other :doc:`Django model </ref/models/instances>`.
437
438 ``Group`` model
439 ===============
440
441 .. class:: models.Group
442
443 Fields
444 ------
445
446 :class:`~django.contrib.auth.models.Group` objects have the following fields:
447
448 .. class:: models.Group
449 :noindex:
450
451 .. attribute:: name
452
453 Required. 150 characters or fewer. Any characters are permitted.
454 Example: ``'Awesome Users'``.
455
456 .. attribute:: permissions
457
458 Many-to-many field to :class:`~django.contrib.auth.models.Permission`::
459
460 group.permissions.set([permission_list])
461 group.permissions.add(permission, permission, ...)
462 group.permissions.remove(permission, permission, ...)
463 group.permissions.clear()
464
465 Validators
466 ==========
467
468 .. class:: validators.ASCIIUsernameValidator
469
470 A field validator allowing only ASCII letters and numbers, in addition to
471 ``@``, ``.``, ``+``, ``-``, and ``_``.
472
473 .. class:: validators.UnicodeUsernameValidator
474
475 A field validator allowing Unicode characters, in addition to ``@``, ``.``,
476 ``+``, ``-``, and ``_``. The default validator for ``User.username``.
477
478 .. _topics-auth-signals:
479
480 Login and logout signals
481 ========================
482
483 .. module:: django.contrib.auth.signals
484
485 The auth framework uses the following :doc:`signals </topics/signals>` that
486 can be used for notification when a user logs in or out.
487
488 .. data:: user_logged_in
489
490 Sent when a user logs in successfully.
491
492 Arguments sent with this signal:
493
494 ``sender``
495 The class of the user that just logged in.
496
497 ``request``
498 The current :class:`~django.http.HttpRequest` instance.
499
500 ``user``
501 The user instance that just logged in.
502
503 .. data:: user_logged_out
504
505 Sent when the logout method is called.
506
507 ``sender``
508 As above: the class of the user that just logged out or ``None``
509 if the user was not authenticated.
510
511 ``request``
512 The current :class:`~django.http.HttpRequest` instance.
513
514 ``user``
515 The user instance that just logged out or ``None`` if the
516 user was not authenticated.
517
518 .. data:: user_login_failed
519
520 Sent when the user failed to login successfully
521
522 ``sender``
523 The name of the module used for authentication.
524
525 ``credentials``
526 A dictionary of keyword arguments containing the user credentials that were
527 passed to :func:`~django.contrib.auth.authenticate()` or your own custom
528 authentication backend. Credentials matching a set of 'sensitive' patterns,
529 (including password) will not be sent in the clear as part of the signal.
530
531 ``request``
532 The :class:`~django.http.HttpRequest` object, if one was provided to
533 :func:`~django.contrib.auth.authenticate`.
534
535 .. _authentication-backends-reference:
536
537 Authentication backends
538 =======================
539
540 .. module:: django.contrib.auth.backends
541 :synopsis: Django's built-in authentication backend classes.
542
543 This section details the authentication backends that come with Django. For
544 information on how to use them and how to write your own authentication
545 backends, see the :ref:`Other authentication sources section
546 <authentication-backends>` of the :doc:`User authentication guide
547 </topics/auth/index>`.
548
549 Available authentication backends
550 ---------------------------------
551
552 The following backends are available in :mod:`django.contrib.auth.backends`:
553
554 .. class:: BaseBackend
555
556 A base class that provides default implementations for all required
557 methods. By default, it will reject any user and provide no permissions.
558
559 .. method:: get_user_permissions(user_obj, obj=None)
560 .. method:: aget_user_permissions(user_obj, obj=None)
561
562 *Asynchronous version*: ``aget_user_permissions()``
563
564 Returns an empty set.
565
566 .. versionchanged:: 5.2
567
568 ``aget_user_permissions()`` function was added.
569
570 .. method:: get_group_permissions(user_obj, obj=None)
571 .. method:: aget_group_permissions(user_obj, obj=None)
572
573 *Asynchronous version*: ``aget_group_permissions()``
574
575 Returns an empty set.
576
577 .. versionchanged:: 5.2
578
579 ``aget_group_permissions()`` function was added.
580
581 .. method:: get_all_permissions(user_obj, obj=None)
582 .. method:: aget_all_permissions(user_obj, obj=None)
583
584 *Asynchronous version*: ``aget_all_permissions()``
585
586 Uses :meth:`get_user_permissions` and :meth:`get_group_permissions` to
587 get the set of permission strings the ``user_obj`` has.
588
589 .. versionchanged:: 5.2
590
591 ``aget_all_permissions()`` function was added.
592
593 .. method:: has_perm(user_obj, perm, obj=None)
594 .. method:: ahas_perm(user_obj, perm, obj=None)
595
596 *Asynchronous version*: ``ahas_perm()``
597
598 Uses :meth:`get_all_permissions` to check if ``user_obj`` has the
599 permission string ``perm``.
600
601 .. versionchanged:: 5.2
602
603 ``ahas_perm()`` function was added.
604
605 .. class:: ModelBackend
606
607 This is the default authentication backend used by Django. It
608 authenticates using credentials consisting of a user identifier and
609 password. For Django's default user model, the user identifier is the
610 username, for custom user models it is the field specified by
611 USERNAME_FIELD (see :doc:`Customizing Users and authentication
612 </topics/auth/customizing>`).
613
614 It also handles the default permissions model as defined for
615 :class:`~django.contrib.auth.models.User` and
616 :class:`~django.contrib.auth.models.PermissionsMixin`.
617
618 :meth:`has_perm`, :meth:`get_all_permissions`, :meth:`get_user_permissions`,
619 and :meth:`get_group_permissions` allow an object to be passed as a
620 parameter for object-specific permissions, but this backend does not
621 implement them other than returning an empty set of permissions if
622 ``obj is not None``.
623
624 :meth:`with_perm` also allows an object to be passed as a parameter, but
625 unlike others methods it returns an empty queryset if ``obj is not None``.
626
627 .. method:: authenticate(request, username=None, password=None, **kwargs)
628 .. method:: aauthenticate(request, username=None, password=None, **kwargs)
629
630 *Asynchronous version*: ``aauthenticate()``
631
632 Tries to authenticate ``username`` with ``password`` by calling
633 :meth:`User.check_password
634 <django.contrib.auth.models.User.check_password>`. If no ``username``
635 is provided, it tries to fetch a username from ``kwargs`` using the
636 key :attr:`CustomUser.USERNAME_FIELD
637 <django.contrib.auth.models.CustomUser.USERNAME_FIELD>`. Returns an
638 authenticated user or ``None``.
639
640 ``request`` is an :class:`~django.http.HttpRequest` and may be ``None``
641 if it wasn't provided to :func:`~django.contrib.auth.authenticate`
642 (which passes it on to the backend).
643
644 .. versionchanged:: 5.2
645
646 ``aauthenticate()`` function was added.
647
648 .. method:: get_user_permissions(user_obj, obj=None)
649 .. method:: aget_user_permissions(user_obj, obj=None)
650
651 *Asynchronous version*: ``aget_user_permissions()``
652
653 Returns the set of permission strings the ``user_obj`` has from their
654 own user permissions. Returns an empty set if
655 :attr:`~django.contrib.auth.models.AbstractBaseUser.is_anonymous` or
656 :attr:`~django.contrib.auth.models.CustomUser.is_active` is ``False``.
657
658 .. versionchanged:: 5.2
659
660 ``aget_user_permissions()`` function was added.
661
662 .. method:: get_group_permissions(user_obj, obj=None)
663 .. method:: aget_group_permissions(user_obj, obj=None)
664
665 *Asynchronous version*: ``aget_group_permissions()``
666
667 Returns the set of permission strings the ``user_obj`` has from the
668 permissions of the groups they belong. Returns an empty set if
669 :attr:`~django.contrib.auth.models.AbstractBaseUser.is_anonymous` or
670 :attr:`~django.contrib.auth.models.CustomUser.is_active` is ``False``.
671
672 .. versionchanged:: 5.2
673
674 ``aget_group_permissions()`` function was added.
675
676 .. method:: get_all_permissions(user_obj, obj=None)
677 .. method:: aget_all_permissions(user_obj, obj=None)
678
679 *Asynchronous version*: ``aget_all_permissions()``
680
681 Returns the set of permission strings the ``user_obj`` has, including both
682 user permissions and group permissions. Returns an empty set if
683 :attr:`~django.contrib.auth.models.AbstractBaseUser.is_anonymous` or
684 :attr:`~django.contrib.auth.models.CustomUser.is_active` is ``False``.
685
686 .. versionchanged:: 5.2
687
688 ``aget_all_permissions()`` function was added.
689
690 .. method:: has_perm(user_obj, perm, obj=None)
691 .. method:: ahas_perm(user_obj, perm, obj=None)
692
693 *Asynchronous version*: ``ahas_perm()``
694
695 Uses :meth:`get_all_permissions` to check if ``user_obj`` has the
696 permission string ``perm``. Returns ``False`` if the user is not
697 :attr:`~django.contrib.auth.models.CustomUser.is_active`.
698
699 .. versionchanged:: 5.2
700
701 ``ahas_perm()`` function was added.
702
703 .. method:: has_module_perms(user_obj, app_label)
704 .. method:: ahas_module_perms(user_obj, app_label)
705
706 *Asynchronous version*: ``ahas_module_perms()``
707
708 Returns whether the ``user_obj`` has any permissions on the app
709 ``app_label``.
710
711 .. versionchanged:: 5.2
712
713 ``ahas_module_perms()`` function was added.
714
715 .. method:: user_can_authenticate()
716
717 Returns whether the user is allowed to authenticate. To match the
718 behavior of :class:`~django.contrib.auth.forms.AuthenticationForm`
719 which :meth:`prohibits inactive users from logging in
720 <django.contrib.auth.forms.AuthenticationForm.confirm_login_allowed>`,
721 this method returns ``False`` for users with :attr:`is_active=False
722 <django.contrib.auth.models.User.is_active>`. Custom user models that
723 don't have an :attr:`~django.contrib.auth.models.CustomUser.is_active`
724 field are allowed.
725
726 .. method:: with_perm(perm, is_active=True, include_superusers=True, obj=None)
727
728 Returns all active users who have the permission ``perm`` either in
729 the form of ``"<app label>.<permission codename>"`` or a
730 :class:`~django.contrib.auth.models.Permission` instance. Returns an
731 empty queryset if no users who have the ``perm`` found.
732
733 If ``is_active`` is ``True`` (default), returns only active users, or
734 if ``False``, returns only inactive users. Use ``None`` to return all
735 users irrespective of active state.
736
737 If ``include_superusers`` is ``True`` (default), the result will
738 include superusers.
739
740 .. class:: AllowAllUsersModelBackend
741
742 Same as :class:`ModelBackend` except that it doesn't reject inactive users
743 because :meth:`~ModelBackend.user_can_authenticate` always returns ``True``.
744
745 When using this backend, you'll likely want to customize the
746 :class:`~django.contrib.auth.forms.AuthenticationForm` used by the
747 :class:`~django.contrib.auth.views.LoginView` by overriding the
748 :meth:`~django.contrib.auth.forms.AuthenticationForm.confirm_login_allowed`
749 method as it rejects inactive users.
750
751 .. class:: RemoteUserBackend
752
753 Use this backend to take advantage of external-to-Django-handled
754 authentication. It authenticates using usernames passed in
755 :attr:`request.META['REMOTE_USER'] <django.http.HttpRequest.META>`. See
756 the :doc:`Authenticating against REMOTE_USER </howto/auth-remote-user>`
757 documentation.
758
759 If you need more control, you can create your own authentication backend
760 that inherits from this class and override these attributes or methods:
761
762 .. attribute:: create_unknown_user
763
764 ``True`` or ``False``. Determines whether or not a user object is
765 created if not already in the database Defaults to ``True``.
766
767 .. method:: authenticate(request, remote_user)
768 .. method:: aauthenticate(request, remote_user)
769
770 *Asynchronous version*: ``aauthenticate()``
771
772 The username passed as ``remote_user`` is considered trusted. This
773 method returns the user object with the given username, creating a new
774 user object if :attr:`~RemoteUserBackend.create_unknown_user` is
775 ``True``.
776
777 Returns ``None`` if :attr:`~RemoteUserBackend.create_unknown_user` is
778 ``False`` and a ``User`` object with the given username is not found in
779 the database.
780
781 ``request`` is an :class:`~django.http.HttpRequest` and may be ``None``
782 if it wasn't provided to :func:`~django.contrib.auth.authenticate`
783 (which passes it on to the backend).
784
785 .. versionchanged:: 5.2
786
787 ``aauthenticate()`` function was added.
788
789 .. method:: clean_username(username)
790
791 Performs any cleaning on the ``username`` (e.g. stripping LDAP DN
792 information) prior to using it to get or create a user object. Returns
793 the cleaned username.
794
795 .. method:: configure_user(request, user, created=True)
796 .. method:: aconfigure_user(request, user, created=True)
797
798 *Asynchronous version*: ``aconfigure_user()``
799
800 Configures the user on each authentication attempt. This method is
801 called immediately after fetching or creating the user being
802 authenticated, and can be used to perform custom setup actions, such as
803 setting the user's groups based on attributes in an LDAP directory.
804 Returns the user object. When fetching or creating an user is called
805 from a synchronous context, ``configure_user`` is called,
806 ``aconfigure_user`` is called from async contexts.
807
808 The setup can be performed either once when the user is created
809 (``created`` is ``True``) or on existing users (``created`` is
810 ``False``) as a way of synchronizing attributes between the remote and
811 the local systems.
812
813 ``request`` is an :class:`~django.http.HttpRequest` and may be ``None``
814 if it wasn't provided to :func:`~django.contrib.auth.authenticate`
815 (which passes it on to the backend).
816
817 .. versionchanged:: 5.2
818
819 ``aconfigure_user()`` function was added.
820
821 .. method:: user_can_authenticate()
822
823 Returns whether the user is allowed to authenticate. This method
824 returns ``False`` for users with :attr:`is_active=False
825 <django.contrib.auth.models.User.is_active>`. Custom user models that
826 don't have an :attr:`~django.contrib.auth.models.CustomUser.is_active`
827 field are allowed.
828
829 .. class:: AllowAllUsersRemoteUserBackend
830
831 Same as :class:`RemoteUserBackend` except that it doesn't reject inactive
832 users because :attr:`~RemoteUserBackend.user_can_authenticate` always
833 returns ``True``.
834
835 Utility functions
836 =================
837
838 .. currentmodule:: django.contrib.auth
839
840 .. function:: get_user(request)
841 .. function:: aget_user(request)
842
843 *Asynchronous version*: ``aget_user()``
844
845 Returns the user model instance associated with the given ``request``’s
846 session.
847
848 It checks if the authentication backend stored in the session is present in
849 :setting:`AUTHENTICATION_BACKENDS`. If so, it uses the backend's
850 ``get_user()`` method to retrieve the user model instance and then verifies
851 the session by calling the user model's
852 :meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash`
853 method. If the verification fails and :setting:`SECRET_KEY_FALLBACKS` are
854 provided, it verifies the session against each fallback key using
855 :meth:`~django.contrib.auth.models.AbstractBaseUser.\
856 get_session_auth_fallback_hash`.
857
858 Returns an instance of :class:`~django.contrib.auth.models.AnonymousUser`
859 if the authentication backend stored in the session is no longer in
860 :setting:`AUTHENTICATION_BACKENDS`, if a user isn't returned by the
861 backend's ``get_user()`` method, or if the session auth hash doesn't
862 validate.
863