| 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 |
|