Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[1.5.x] Fixed #19498 -- refactored auth documentation

The auth doc was a single page which had grown unwieldy.
This refactor split and grouped the content into sub-topics.
Additional corrections and cleanups were made along the way.
  • Loading branch information...
commit 8d1b1902488855e56c93f66d5a30b3ec746ff183 1 parent 3cb87ec
Preston Holmes authored
2  docs/howto/deployment/wsgi/apache-auth.txt
@@ -4,7 +4,7 @@ Authenticating against Django's user database from Apache
4 4
 
5 5
 Since keeping multiple authentication databases in sync is a common problem when
6 6
 dealing with Apache, you can configure Apache to authenticate against Django's
7  
-:doc:`authentication system </topics/auth>` directly. This requires Apache
  7
+:doc:`authentication system </topics/auth/index>` directly. This requires Apache
8 8
 version >= 2.2 and mod_wsgi >= 2.0. For example, you could:
9 9
 
10 10
 * Serve static/media files directly from Apache only to authenticated users.
2  docs/index.txt
@@ -246,7 +246,7 @@ Common Web application tools
246 246
 Django offers multiple tools commonly needed in the development of Web
247 247
 applications:
248 248
 
249  
-* :doc:`Authentication <topics/auth>`
  249
+* :doc:`Authentication <topics/auth/index>`
250 250
 * :doc:`Caching <topics/cache>`
251 251
 * :doc:`Logging <topics/logging>`
252 252
 * :doc:`Sending emails <topics/email>`
2  docs/internals/git.txt
@@ -134,7 +134,7 @@ part of Django itself, and so are no longer separately maintained:
134 134
   of Django since the 0.95 release.
135 135
 
136 136
 * ``multi-auth``: A refactoring of :doc:`Django's bundled
137  
-  authentication framework </topics/auth>` which added support for
  137
+  authentication framework </topics/auth/index>` which added support for
138 138
   :ref:`authentication backends <authentication-backends>`. This has
139 139
   been part of Django since the 0.95 release.
140 140
 
2  docs/misc/api-stability.txt
@@ -38,7 +38,7 @@ In general, everything covered in the documentation -- with the exception of
38 38
 anything in the :doc:`internals area </internals/index>` is considered stable as
39 39
 of 1.0. This includes these APIs:
40 40
 
41  
-- :doc:`Authorization </topics/auth>`
  41
+- :doc:`Authorization </topics/auth/index>`
42 42
 
43 43
 - :doc:`Caching </topics/cache>`.
44 44
 
33  docs/ref/authbackends.txt
... ...
@@ -1,33 +0,0 @@
1  
-=======================
2  
-Authentication backends
3  
-=======================
4  
-
5  
-.. module:: django.contrib.auth.backends
6  
-   :synopsis: Django's built-in authentication backend classes.
7  
-
8  
-This document details the authentication backends that come with Django. For
9  
-information on how to use them and how to write your own authentication
10  
-backends, see the :ref:`Other authentication sources section
11  
-<authentication-backends>` of the :doc:`User authentication guide
12  
-</topics/auth>`.
13  
-
14  
-
15  
-Available authentication backends
16  
-=================================
17  
-
18  
-The following backends are available in :mod:`django.contrib.auth.backends`:
19  
-
20  
-.. class:: ModelBackend
21  
-
22  
-    This is the default authentication backend used by Django.  It
23  
-    authenticates using usernames and passwords stored in the
24  
-    :class:`~django.contrib.auth.models.User` model.
25  
-
26  
-
27  
-.. class:: RemoteUserBackend
28  
-
29  
-    Use this backend to take advantage of external-to-Django-handled
30  
-    authentication.  It authenticates using usernames passed in
31  
-    :attr:`request.META['REMOTE_USER'] <django.http.HttpRequest.META>`.  See
32  
-    the :doc:`Authenticating against REMOTE_USER </howto/auth-remote-user>`
33  
-    documentation.
428  docs/ref/contrib/auth.txt
... ...
@@ -1,4 +1,430 @@
1 1
 ``django.contrib.auth``
2 2
 =======================
3 3
 
4  
-See :doc:`/topics/auth`.
  4
+This document provides API reference material for the components of Django's
  5
+authentication system. For more details on the usage of these components or
  6
+how to customize authentication and authorization see the :doc:`authentication
  7
+topic guide </topics/auth/index>`.
  8
+
  9
+.. currentmodule:: django.contrib.auth
  10
+
  11
+User
  12
+====
  13
+
  14
+Fields
  15
+------
  16
+
  17
+.. class:: models.User
  18
+
  19
+    :class:`~django.contrib.auth.models.User` objects have the following
  20
+    fields:
  21
+
  22
+    .. attribute:: username
  23
+
  24
+        Required. 30 characters or fewer. Usernames may contain alphanumeric,
  25
+        ``_``, ``@``, ``+``, ``.`` and ``-`` characters.
  26
+
  27
+    .. attribute:: first_name
  28
+
  29
+        Optional. 30 characters or fewer.
  30
+
  31
+    .. attribute:: last_name
  32
+
  33
+        Optional. 30 characters or fewer.
  34
+
  35
+    .. attribute:: email
  36
+
  37
+        Optional. Email address.
  38
+
  39
+    .. attribute:: password
  40
+
  41
+        Required. A hash of, and metadata about, the password. (Django doesn't
  42
+        store the raw password.) Raw passwords can be arbitrarily long and can
  43
+        contain any character. See the :doc:`password documentation
  44
+        </topics/auth/passwords>`.
  45
+
  46
+    .. attribute:: groups
  47
+
  48
+        Many-to-many relationship to :class:`~django.contrib.auth.models.Group`
  49
+
  50
+    .. attribute:: user_permissions
  51
+
  52
+         Many-to-many relationship to :class:`~django.contrib.auth.models.Permission`
  53
+
  54
+    .. attribute:: is_staff
  55
+
  56
+        Boolean. Designates whether this user can access the admin site.
  57
+
  58
+    .. attribute:: is_active
  59
+
  60
+        Boolean. Designates whether this user account should be considered
  61
+        active. We recommend that you set this flag to ``False`` instead of
  62
+        deleting accounts; that way, if your applications have any foreign keys
  63
+        to users, the foreign keys won't break.
  64
+
  65
+        This doesn't necessarily control whether or not the user can log in.
  66
+        Authentication backends aren't required to check for the ``is_active``
  67
+        flag, and the default backends do not. If you want to reject a login
  68
+        based on ``is_active`` being ``False``, it's up to you to check that in
  69
+        your own login view or a custom authentication backend. However, the
  70
+        :class:`~django.contrib.auth.forms.AuthenticationForm` used by the
  71
+        :func:`~django.contrib.auth.views.login` view (which is the default)
  72
+        *does* perform this check, as do the permission-checking methods such
  73
+        as :meth:`~django.contrib.auth.models.User.has_perm` and the
  74
+        authentication in the Django admin. All of those functions/methods will
  75
+        return ``False`` for inactive users.
  76
+
  77
+    .. attribute:: is_superuser
  78
+
  79
+        Boolean. Designates that this user has all permissions without
  80
+        explicitly assigning them.
  81
+
  82
+    .. attribute:: last_login
  83
+
  84
+        A datetime of the user's last login. Is set to the current date/time by
  85
+        default.
  86
+
  87
+    .. attribute:: date_joined
  88
+
  89
+        A datetime designating when the account was created. Is set to the
  90
+        current date/time by default when the account is created.
  91
+
  92
+Methods
  93
+-------
  94
+
  95
+.. class:: models.User
  96
+
  97
+    .. method:: get_username()
  98
+
  99
+        Returns the username for the user. Since the User model can be swapped
  100
+        out, you should use  this method instead of referencing the username
  101
+        attribute directly.
  102
+
  103
+    .. method:: is_anonymous()
  104
+
  105
+        Always returns ``False``. This is a way of differentiating
  106
+        :class:`~django.contrib.auth.models.User` and
  107
+        :class:`~django.contrib.auth.models.AnonymousUser` objects.
  108
+        Generally, you should prefer using
  109
+        :meth:`~django.contrib.auth.models.User.is_authenticated()` to this
  110
+        method.
  111
+
  112
+    .. method:: is_authenticated()
  113
+
  114
+        Always returns ``True``. This is a way to tell if the user has been
  115
+        authenticated. This does not imply any permissions, and doesn't check
  116
+        if the user is active - it only indicates that the user has provided a
  117
+        valid username and password.
  118
+
  119
+    .. method:: get_full_name()
  120
+
  121
+        Returns the :attr:`~django.contrib.auth.models.User.first_name` plus
  122
+        the :attr:`~django.contrib.auth.models.User.last_name`, with a space in
  123
+        between.
  124
+
  125
+    .. method:: set_password(raw_password)
  126
+
  127
+        Sets the user's password to the given raw string, taking care of the
  128
+        password hashing. Doesn't save the
  129
+        :class:`~django.contrib.auth.models.User` object.
  130
+
  131
+    .. method:: check_password(raw_password)
  132
+
  133
+        Returns ``True`` if the given raw string is the correct password for
  134
+        the user. (This takes care of the password hashing in making the
  135
+        comparison.)
  136
+
  137
+    .. method:: set_unusable_password()
  138
+
  139
+        Marks the user as having no password set.  This isn't the same as
  140
+        having a blank string for a password.
  141
+        :meth:`~django.contrib.auth.models.User.check_password()` for this user
  142
+        will never return ``True``. Doesn't save the
  143
+        :class:`~django.contrib.auth.models.User` object.
  144
+
  145
+        You may need this if authentication for your application takes place
  146
+        against an existing external source such as an LDAP directory.
  147
+
  148
+    .. method:: has_usable_password()
  149
+
  150
+        Returns ``False`` if
  151
+        :meth:`~django.contrib.auth.models.User.set_unusable_password()` has
  152
+        been called for this user.
  153
+
  154
+    .. method:: get_group_permissions(obj=None)
  155
+
  156
+        Returns a set of permission strings that the user has, through his/her
  157
+        groups.
  158
+
  159
+        If ``obj`` is passed in, only returns the group permissions for
  160
+        this specific object.
  161
+
  162
+    .. method:: get_all_permissions(obj=None)
  163
+
  164
+        Returns a set of permission strings that the user has, both through
  165
+        group and user permissions.
  166
+
  167
+        If ``obj`` is passed in, only returns the permissions for this
  168
+        specific object.
  169
+
  170
+    .. method:: has_perm(perm, obj=None)
  171
+
  172
+        Returns ``True`` if the user has the specified permission, where perm
  173
+        is in the format ``"<app label>.<permission codename>"``. (see
  174
+        documentation on :ref:`permissions <topic-authorization>`). If the user is
  175
+        inactive, this method will always return ``False``.
  176
+
  177
+        If ``obj`` is passed in, this method won't check for a permission for
  178
+        the model, but for this specific object.
  179
+
  180
+    .. method:: has_perms(perm_list, obj=None)
  181
+
  182
+        Returns ``True`` if the user has each of the specified permissions,
  183
+        where each perm is in the format
  184
+        ``"<app label>.<permission codename>"``. If the user is inactive,
  185
+        this method will always return ``False``.
  186
+
  187
+        If ``obj`` is passed in, this method won't check for permissions for
  188
+        the model, but for the specific object.
  189
+
  190
+    .. method:: has_module_perms(package_name)
  191
+
  192
+        Returns ``True`` if the user has any permissions in the given package
  193
+        (the Django app label). If the user is inactive, this method will
  194
+        always return ``False``.
  195
+
  196
+    .. method:: email_user(subject, message, from_email=None)
  197
+
  198
+        Sends an email to the user. If ``from_email`` is ``None``, Django uses
  199
+        the :setting:`DEFAULT_FROM_EMAIL`.
  200
+
  201
+    .. method:: get_profile()
  202
+
  203
+        .. deprecated:: 1.5
  204
+            With the introduction of :ref:`custom User models <auth-custom-user>`,
  205
+            the use of :setting:`AUTH_PROFILE_MODULE` to define a single profile
  206
+            model is no longer supported. See the
  207
+            :doc:`Django 1.5 release notes</releases/1.5>` for more information.
  208
+
  209
+        Returns a site-specific profile for this user. Raises
  210
+        ``django.contrib.auth.models.SiteProfileNotAvailable`` if the
  211
+        current site doesn't allow profiles, or
  212
+        :exc:`django.core.exceptions.ObjectDoesNotExist` if the user does not
  213
+        have a profile.
  214
+
  215
+Manager methods
  216
+---------------
  217
+
  218
+.. class:: models.UserManager
  219
+
  220
+    The :class:`~django.contrib.auth.models.User` model has a custom manager
  221
+    that has the following helper methods:
  222
+
  223
+    .. method:: create_user(username, email=None, password=None)
  224
+
  225
+        .. versionchanged:: 1.4
  226
+           The ``email`` parameter was made optional. The username
  227
+           parameter is now checked for emptiness and raises a
  228
+           :exc:`~exceptions.ValueError` in case of a negative result.
  229
+
  230
+        Creates, saves and returns a :class:`~django.contrib.auth.models.User`.
  231
+
  232
+        The :attr:`~django.contrib.auth.models.User.username` and
  233
+        :attr:`~django.contrib.auth.models.User.password` are set as given. The
  234
+        domain portion of :attr:`~django.contrib.auth.models.User.email` is
  235
+        automatically converted to lowercase, and the returned
  236
+        :class:`~django.contrib.auth.models.User` object will have
  237
+        :attr:`~django.contrib.auth.models.User.is_active` set to ``True``.
  238
+
  239
+        If no password is provided,
  240
+        :meth:`~django.contrib.auth.models.User.set_unusable_password()` will
  241
+        be called.
  242
+
  243
+        See :ref:`Creating users <topics-auth-creating-users>` for example usage.
  244
+
  245
+    .. method:: make_random_password(length=10, allowed_chars='abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789')
  246
+
  247
+        Returns a random password with the given length and given string of
  248
+        allowed characters. (Note that the default value of ``allowed_chars``
  249
+        doesn't contain letters that can cause user confusion, including:
  250
+
  251
+        * ``i``, ``l``, ``I``, and ``1`` (lowercase letter i, lowercase
  252
+          letter L, uppercase letter i, and the number one)
  253
+        * ``o``, ``O``, and ``0`` (uppercase letter o, lowercase letter o,
  254
+          and zero)
  255
+
  256
+
  257
+Anonymous users
  258
+===============
  259
+
  260
+.. class:: models.AnonymousUser
  261
+
  262
+    :class:`django.contrib.auth.models.AnonymousUser` is a class that
  263
+    implements the :class:`django.contrib.auth.models.User` interface, with
  264
+    these differences:
  265
+
  266
+    * :ref:`id <automatic-primary-key-fields>` is always ``None``.
  267
+    * :attr:`~django.contrib.auth.models.User.is_staff` and
  268
+      :attr:`~django.contrib.auth.models.User.is_superuser` are always
  269
+      ``False``.
  270
+    * :attr:`~django.contrib.auth.models.User.is_active` is always ``False``.
  271
+    * :attr:`~django.contrib.auth.models.User.groups` and
  272
+      :attr:`~django.contrib.auth.models.User.user_permissions` are always
  273
+      empty.
  274
+    * :meth:`~django.contrib.auth.models.User.is_anonymous()` returns ``True``
  275
+      instead of ``False``.
  276
+    * :meth:`~django.contrib.auth.models.User.is_authenticated()` returns
  277
+      ``False`` instead of ``True``.
  278
+    * :meth:`~django.contrib.auth.models.User.set_password()`,
  279
+      :meth:`~django.contrib.auth.models.User.check_password()`,
  280
+      :meth:`~django.db.models.Model.save` and
  281
+      :meth:`~django.db.models.Model.delete()` raise
  282
+      :exc:`~exceptions.NotImplementedError`.
  283
+
  284
+In practice, you probably won't need to use
  285
+:class:`~django.contrib.auth.models.AnonymousUser` objects on your own, but
  286
+they're used by Web requests, as explained in the next section.
  287
+
  288
+Permission
  289
+==========
  290
+
  291
+.. class:: models.Permission
  292
+
  293
+Fields
  294
+------
  295
+
  296
+:class:`~django.contrib.auth.models.Permission` objects have the following
  297
+fields:
  298
+
  299
+.. attribute:: name
  300
+
  301
+    Required. 50 characters or fewer. Example: ``'Can vote'``.
  302
+
  303
+.. attribute:: content_type
  304
+
  305
+    Required. A reference to the ``django_content_type`` database table, which
  306
+    contains a record for each installed Django model.
  307
+
  308
+.. attribute:: codename
  309
+
  310
+    Required. 100 characters or fewer. Example: ``'can_vote'``.
  311
+
  312
+Methods
  313
+-------
  314
+
  315
+:class:`~django.contrib.auth.models.Permission` objects have the standard
  316
+data-access methods like any other :doc:`Django model </ref/models/instances>`.
  317
+
  318
+Group
  319
+=====
  320
+
  321
+.. class:: models.Group
  322
+
  323
+Fields
  324
+------
  325
+
  326
+:class:`~django.contrib.auth.models.Group` objects have the following fields:
  327
+
  328
+.. attribute:: name
  329
+
  330
+    Required. 80 characters or fewer. Any characters are permitted. Example:
  331
+    ``'Awesome Users'``.
  332
+
  333
+.. attribute:: permissions
  334
+
  335
+    Many-to-many field to :class:`~django.contrib.auth.models.Permission`::
  336
+
  337
+        group.permissions = [permission_list]
  338
+        group.permissions.add(permission, permission, ...)
  339
+        group.permissions.remove(permission, permission, ...)
  340
+        group.permissions.clear()
  341
+
  342
+.. _topics-auth-signals:
  343
+
  344
+Login and logout signals
  345
+========================
  346
+
  347
+.. module:: django.contrib.auth.signals
  348
+
  349
+The auth framework uses two :doc:`signals </topics/signals>` that can be used
  350
+for notification when a user logs in or out.
  351
+
  352
+.. function:: django.contrib.auth.signals.user_logged_in
  353
+
  354
+    Sent when a user logs in successfully.
  355
+
  356
+    Arguments sent with this signal:
  357
+
  358
+    ``sender``
  359
+        The class of the user that just logged in.
  360
+
  361
+    ``request``
  362
+        The current :class:`~django.http.HttpRequest` instance.
  363
+
  364
+    ``user``
  365
+        The user instance that just logged in.
  366
+
  367
+.. function:: django.contrib.auth.signals.user_logged_out
  368
+
  369
+    Sent when the logout method is called.
  370
+
  371
+    ``sender``
  372
+        As above: the class of the user that just logged out or ``None``
  373
+        if the user was not authenticated.
  374
+
  375
+    ``request``
  376
+        The current :class:`~django.http.HttpRequest` instance.
  377
+
  378
+    ``user``
  379
+        The user instance that just logged out or ``None`` if the
  380
+        user was not authenticated.
  381
+
  382
+.. function:: django.contrib.auth.signals.user_login_failed
  383
+
  384
+.. versionadded:: 1.5
  385
+
  386
+    Sent when the user failed to login successfully
  387
+
  388
+    ``sender``
  389
+        The name of the module used for authentication.
  390
+
  391
+    ``credentials``
  392
+        A dictionary of keyword arguments containing the user credentials that were
  393
+        passed to :func:`~django.contrib.auth.authenticate()` or your own custom
  394
+        authentication backend. Credentials matching a set of 'sensitive' patterns,
  395
+        (including password) will not be sent in the clear as part of the signal.
  396
+
  397
+.. _authentication-backends-reference:
  398
+
  399
+Authentication backends
  400
+=======================
  401
+
  402
+.. module:: django.contrib.auth.backends
  403
+   :synopsis: Django's built-in authentication backend classes.
  404
+
  405
+This section details the authentication backends that come with Django. For
  406
+information on how to use them and how to write your own authentication
  407
+backends, see the :ref:`Other authentication sources section
  408
+<authentication-backends>` of the :doc:`User authentication guide
  409
+</topics/auth/index>`.
  410
+
  411
+
  412
+Available authentication backends
  413
+---------------------------------
  414
+
  415
+The following backends are available in :mod:`django.contrib.auth.backends`:
  416
+
  417
+.. class:: ModelBackend
  418
+
  419
+    This is the default authentication backend used by Django.  It
  420
+    authenticates using usernames and passwords stored in the
  421
+    :class:`~django.contrib.auth.models.User` model.
  422
+
  423
+
  424
+.. class:: RemoteUserBackend
  425
+
  426
+    Use this backend to take advantage of external-to-Django-handled
  427
+    authentication.  It authenticates using usernames passed in
  428
+    :attr:`request.META['REMOTE_USER'] <django.http.HttpRequest.META>`.  See
  429
+    the :doc:`Authenticating against REMOTE_USER </howto/auth-remote-user>`
  430
+    documentation.
2  docs/ref/contrib/index.txt
@@ -56,7 +56,7 @@ auth
56 56
 
57 57
 Django's authentication framework.
58 58
 
59  
-See :doc:`/topics/auth`.
  59
+See :doc:`/topics/auth/index`.
60 60
 
61 61
 comments
62 62
 ========
4  docs/ref/django-admin.txt
@@ -1145,7 +1145,7 @@ changepassword
1145 1145
 .. django-admin:: changepassword
1146 1146
 
1147 1147
 This command is only available if Django's :doc:`authentication system
1148  
-</topics/auth>` (``django.contrib.auth``) is installed.
  1148
+</topics/auth/index>` (``django.contrib.auth``) is installed.
1149 1149
 
1150 1150
 Allows changing a user's password. It prompts you to enter twice the password of
1151 1151
 the user given as parameter. If they both match, the new password will be
@@ -1167,7 +1167,7 @@ createsuperuser
1167 1167
 .. django-admin:: createsuperuser
1168 1168
 
1169 1169
 This command is only available if Django's :doc:`authentication system
1170  
-</topics/auth>` (``django.contrib.auth``) is installed.
  1170
+</topics/auth/index>` (``django.contrib.auth``) is installed.
1171 1171
 
1172 1172
 Creates a superuser account (a user who has all permissions). This is
1173 1173
 useful if you need to create an initial superuser account but did not
1  docs/ref/index.txt
@@ -5,7 +5,6 @@ API Reference
5 5
 .. toctree::
6 6
    :maxdepth: 1
7 7
 
8  
-   authbackends
9 8
    class-based-views/index
10 9
    clickjacking
11 10
    contrib/index
4  docs/ref/middleware.txt
@@ -179,8 +179,8 @@ Authentication middleware
179 179
 .. class:: AuthenticationMiddleware
180 180
 
181 181
 Adds the ``user`` attribute, representing the currently-logged-in user, to
182  
-every incoming ``HttpRequest`` object. See :doc:`Authentication in Web requests
183  
-</topics/auth>`.
  182
+every incoming ``HttpRequest`` object. See :ref:`Authentication in Web requests
  183
+<auth-web-requests>`.
184 184
 
185 185
 CSRF protection middleware
186 186
 --------------------------
2  docs/ref/request-response.txt
@@ -181,7 +181,7 @@ All attributes should be considered read-only, unless stated otherwise below.
181 181
 
182 182
     ``user`` is only available if your Django installation has the
183 183
     ``AuthenticationMiddleware`` activated. For more, see
184  
-    :doc:`/topics/auth`.
  184
+    :doc:`/topics/auth/index`.
185 185
 
186 186
 .. attribute:: HttpRequest.session
187 187
 
6  docs/ref/settings.txt
@@ -107,8 +107,8 @@ AUTHENTICATION_BACKENDS
107 107
 Default: ``('django.contrib.auth.backends.ModelBackend',)``
108 108
 
109 109
 A tuple of authentication backend classes (as strings) to use when attempting to
110  
-authenticate a user. See the :doc:`authentication backends documentation
111  
-</ref/authbackends>` for details.
  110
+authenticate a user. See the :ref:`authentication backends documentation
  111
+<authentication-backends>` for details.
112 112
 
113 113
 .. setting:: AUTH_USER_MODEL
114 114
 
@@ -2256,7 +2256,7 @@ AUTH_PROFILE_MODULE
2256 2256
 Default: Not defined
2257 2257
 
2258 2258
 The site-specific user profile model used by this site. See
2259  
-:ref:`auth-profiles`.
  2259
+:ref:`User profiles <auth-profiles>`.
2260 2260
 
2261 2261
 .. setting:: IGNORABLE_404_ENDS
2262 2262
 
2  docs/ref/signals.txt
@@ -12,7 +12,7 @@ A list of all the signals that Django sends.
12 12
     The :doc:`comment framework </ref/contrib/comments/index>` sends a :doc:`set
13 13
     of comment-related signals </ref/contrib/comments/signals>`.
14 14
 
15  
-    The :doc:`authentication framework </topics/auth>` sends :ref:`signals when
  15
+    The :doc:`authentication framework </topics/auth/index>` sends :ref:`signals when
16 16
     a user is logged in / out <topics-auth-signals>`.
17 17
 
18 18
 Model signals
4  docs/releases/1.2-beta-1.txt
@@ -91,7 +91,7 @@ added in Django 1.2 alpha but not documented with the alpha release.
91 91
 
92 92
 The default authentication backends shipped with Django do not
93 93
 currently make use of this, but third-party authentication backends
94  
-are free to do so. See the :doc:`authentication docs </topics/auth>`
  94
+are free to do so. See the :doc:`authentication docs </topics/auth/index>`
95 95
 for more information.
96 96
 
97 97
 
@@ -104,7 +104,7 @@ class will check the backend for permissions, just as the normal
104 104
 ``User`` does. This is intended to help centralize permission
105 105
 handling; apps can always delegate the question of whether something
106 106
 is allowed or not to the authorization/authentication system. See the
107  
-:doc:`authentication docs </topics/auth>` for more details.
  107
+:doc:`authentication docs </topics/auth/index>` for more details.
108 108
 
109 109
 
110 110
 ``select_related()`` improvements
4  docs/releases/1.2.txt
@@ -165,7 +165,7 @@ A foundation for specifying permissions at the per-object level has been added.
165 165
 Although there is no implementation of this in core, a custom authentication
166 166
 backend can provide this implementation and it will be used by
167 167
 :class:`django.contrib.auth.models.User`. See the :doc:`authentication docs
168  
-</topics/auth>` for more information.
  168
+</topics/auth/index>` for more information.
169 169
 
170 170
 Permissions for anonymous users
171 171
 -------------------------------
@@ -175,7 +175,7 @@ If you provide a custom auth backend with ``supports_anonymous_user`` set to
175 175
 User already did.  This is useful for centralizing permission handling - apps
176 176
 can always delegate the question of whether something is allowed or not to
177 177
 the authorization/authentication backend. See the :doc:`authentication
178  
-docs </topics/auth>` for more details.
  178
+docs </topics/auth/index>` for more details.
179 179
 
180 180
 Relaxed requirements for usernames
181 181
 ----------------------------------
2  docs/releases/1.3-beta-1.txt
@@ -61,7 +61,7 @@ Permissions for inactive users
61 61
 If you provide a custom auth backend with ``supports_inactive_user`` set to
62 62
 ``True``, an inactive user model will check the backend for permissions.
63 63
 This is useful for further centralizing the permission handling. See the
64  
-:doc:`authentication docs </topics/auth>` for more details.
  64
+:doc:`authentication docs </topics/auth/index>` for more details.
65 65
 
66 66
 Backwards-incompatible changes in 1.3 alpha 2
67 67
 =============================================
2  docs/releases/1.3.txt
@@ -254,7 +254,7 @@ Permissions for inactive users
254 254
 If you provide a custom auth backend with ``supports_inactive_user``
255 255
 set to ``True``, an inactive ``User`` instance will check the backend
256 256
 for permissions.  This is useful for further centralizing the
257  
-permission handling. See the :doc:`authentication docs </topics/auth>`
  257
+permission handling. See the :doc:`authentication docs </topics/auth/index>`
258 258
 for more details.
259 259
 
260 260
 GeoDjango
2,690  docs/topics/auth.txt
0 additions, 2690 deletions not shown
1,068  docs/topics/auth/customizing.txt
... ...
@@ -0,0 +1,1068 @@
  1
+====================================
  2
+Customizing authentication in Django
  3
+====================================
  4
+
  5
+The authentication that comes with Django is good enough for most common cases,
  6
+but you may have needs not met by the out-of-the-box defaults. To customize
  7
+authentication to your projects needs involves understanding what points of the
  8
+provided system are extendible or replaceable. This document provides details
  9
+about how the auth system can be customized.
  10
+
  11
+:ref:`Authentication backends <authentication-backends>` provide an extensible
  12
+system for when a username and password stored with the User model need
  13
+to be authenticated against a different service than Django's default.
  14
+
  15
+You can give your models :ref:`custom permissions <custom-permissions>` that can be
  16
+checked through Django's authorization system.
  17
+
  18
+You can :ref:`extend <extending-user>` the default User model, or :ref:`substitute
  19
+<auth-custom-user>` a completely customized model.
  20
+
  21
+.. _authentication-backends:
  22
+
  23
+Other authentication sources
  24
+============================
  25
+
  26
+There may be times you have the need to hook into another authentication source
  27
+-- that is, another source of usernames and passwords or authentication
  28
+methods.
  29
+
  30
+For example, your company may already have an LDAP setup that stores a username
  31
+and password for every employee. It'd be a hassle for both the network
  32
+administrator and the users themselves if users had separate accounts in LDAP
  33
+and the Django-based applications.
  34
+
  35
+So, to handle situations like this, the Django authentication system lets you
  36
+plug in other authentication sources. You can override Django's default
  37
+database-based scheme, or you can use the default system in tandem with other
  38
+systems.
  39
+
  40
+See the `authentication backend reference
  41
+<authentication-backends-reference>` for information on the authentication
  42
+backends included with Django.
  43
+
  44
+Specifying authentication backends
  45
+----------------------------------
  46
+
  47
+Behind the scenes, Django maintains a list of "authentication backends" that it
  48
+checks for authentication. When somebody calls
  49
+:func:`django.contrib.auth.authenticate()` -- as described in :ref:`How to log
  50
+a user in <how-to-log-a-user-in>` above -- Django tries authenticating across
  51
+all of its authentication backends. If the first authentication method fails,
  52
+Django tries the second one, and so on, until all backends have been attempted.
  53
+
  54
+The list of authentication backends to use is specified in the
  55
+:setting:`AUTHENTICATION_BACKENDS` setting. This should be a tuple of Python
  56
+path names that point to Python classes that know how to authenticate. These
  57
+classes can be anywhere on your Python path.
  58
+
  59
+By default, :setting:`AUTHENTICATION_BACKENDS` is set to::
  60
+
  61
+    ('django.contrib.auth.backends.ModelBackend',)
  62
+
  63
+That's the basic authentication backend that checks the Django users database
  64
+and queries the built-in permissions. It does not provide protection against
  65
+brute force attacks via any rate limiting mechanism. You may either implement
  66
+your own rate limiting mechanism in a custom auth backend, or use the
  67
+mechanisms provided by most Web servers.
  68
+
  69
+The order of :setting:`AUTHENTICATION_BACKENDS` matters, so if the same
  70
+username and password is valid in multiple backends, Django will stop
  71
+processing at the first positive match.
  72
+
  73
+.. note::
  74
+
  75
+    Once a user has authenticated, Django stores which backend was used to
  76
+    authenticate the user in the user's session, and re-uses the same backend
  77
+    for the duration of that session whenever access to the currently
  78
+    authenticated user is needed. This effectively means that authentication
  79
+    sources are cached on a per-session basis, so if you change
  80
+    :setting:`AUTHENTICATION_BACKENDS`, you'll need to clear out session data if
  81
+    you need to force users to re-authenticate using different methods. A simple
  82
+    way to do that is simply to execute ``Session.objects.all().delete()``.
  83
+
  84
+Writing an authentication backend
  85
+---------------------------------
  86
+
  87
+An authentication backend is a class that implements two required methods:
  88
+``get_user(user_id)`` and ``authenticate(**credentials)``, as well as a set of
  89
+optional permission related :ref:`authorization methods <authorization_methods>`.
  90
+
  91
+The ``get_user`` method takes a ``user_id`` -- which could be a username,
  92
+database ID or whatever -- and returns a ``User`` object.
  93
+
  94
+The ``authenticate`` method takes credentials as keyword arguments. Most of
  95
+the time, it'll just look like this::
  96
+
  97
+    class MyBackend(object):
  98
+        def authenticate(self, username=None, password=None):
  99
+            # Check the username/password and return a User.
  100
+
  101
+But it could also authenticate a token, like so::
  102
+
  103
+    class MyBackend(object):
  104
+        def authenticate(self, token=None):
  105
+            # Check the token and return a User.
  106
+
  107
+Either way, ``authenticate`` should check the credentials it gets, and it
  108
+should return a ``User`` object that matches those credentials, if the
  109
+credentials are valid. If they're not valid, it should return ``None``.
  110
+
  111
+The Django admin system is tightly coupled to the Django ``User`` object
  112
+described at the beginning of this document. For now, the best way to deal with
  113
+this is to create a Django ``User`` object for each user that exists for your
  114
+backend (e.g., in your LDAP directory, your external SQL database, etc.) You
  115
+can either write a script to do this in advance, or your ``authenticate``
  116
+method can do it the first time a user logs in.
  117
+
  118
+Here's an example backend that authenticates against a username and password
  119
+variable defined in your ``settings.py`` file and creates a Django ``User``
  120
+object the first time a user authenticates::
  121
+
  122
+    from django.conf import settings
  123
+    from django.contrib.auth.models import User, check_password
  124
+
  125
+    class SettingsBackend(object):
  126
+        """
  127
+        Authenticate against the settings ADMIN_LOGIN and ADMIN_PASSWORD.
  128
+
  129
+        Use the login name, and a hash of the password. For example:
  130
+
  131
+        ADMIN_LOGIN = 'admin'
  132
+        ADMIN_PASSWORD = 'sha1$4e987$afbcf42e21bd417fb71db8c66b321e9fc33051de'
  133
+        """
  134
+
  135
+        def authenticate(self, username=None, password=None):
  136
+            login_valid = (settings.ADMIN_LOGIN == username)
  137
+            pwd_valid = check_password(password, settings.ADMIN_PASSWORD)
  138
+            if login_valid and pwd_valid:
  139
+                try:
  140
+                    user = User.objects.get(username=username)
  141
+                except User.DoesNotExist:
  142
+                    # Create a new user. Note that we can set password
  143
+                    # to anything, because it won't be checked; the password
  144
+                    # from settings.py will.
  145
+                    user = User(username=username, password='get from settings.py')
  146
+                    user.is_staff = True
  147
+                    user.is_superuser = True
  148
+                    user.save()
  149
+                return user
  150
+            return None
  151
+
  152
+        def get_user(self, user_id):
  153
+            try:
  154
+                return User.objects.get(pk=user_id)
  155
+            except User.DoesNotExist:
  156
+                return None
  157
+
  158
+.. _authorization_methods:
  159
+
  160
+Handling authorization in custom backends
  161
+-----------------------------------------
  162
+
  163
+Custom auth backends can provide their own permissions.
  164
+
  165
+The user model will delegate permission lookup functions
  166
+(:meth:`~django.contrib.auth.models.User.get_group_permissions()`,
  167
+:meth:`~django.contrib.auth.models.User.get_all_permissions()`,
  168
+:meth:`~django.contrib.auth.models.User.has_perm()`, and
  169
+:meth:`~django.contrib.auth.models.User.has_module_perms()`) to any
  170
+authentication backend that implements these functions.
  171
+
  172
+The permissions given to the user will be the superset of all permissions
  173
+returned by all backends. That is, Django grants a permission to a user that
  174
+any one backend grants.
  175
+
  176
+The simple backend above could implement permissions for the magic admin
  177
+fairly simply::
  178
+
  179
+    class SettingsBackend(object):
  180
+
  181
+        # ...
  182
+
  183
+        def has_perm(self, user_obj, perm, obj=None):
  184
+            if user_obj.username == settings.ADMIN_LOGIN:
  185
+                return True
  186
+            else:
  187
+                return False
  188
+
  189
+This gives full permissions to the user granted access in the above example.
  190
+Notice that in addition to the same arguments given to the associated
  191
+:class:`django.contrib.auth.models.User` functions, the backend auth functions
  192
+all take the user object, which may be an anonymous user, as an argument.
  193
+
  194
+A full authorization implementation can be found in the ``ModelBackend`` class
  195
+in `django/contrib/auth/backends.py`_, which is the default backend and queries
  196
+the ``auth_permission`` table most of the time. If you wish to provide
  197
+custom behavior for only part of the backend API, you can take advantage of
  198
+Python inheritance and subclass ``ModelBackend`` instead of implementing the
  199
+complete API in a custom backend.
  200
+
  201
+.. _django/contrib/auth/backends.py: https://github.com/django/django/blob/master/django/contrib/auth/backends.py
  202
+
  203
+.. _anonymous_auth:
  204
+
  205
+Authorization for anonymous users
  206
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  207
+
  208
+An anonymous user is one that is not authenticated i.e. they have provided no
  209
+valid authentication details. However, that does not necessarily mean they are
  210
+not authorized to do anything. At the most basic level, most Web sites
  211
+authorize anonymous users to browse most of the site, and many allow anonymous
  212
+posting of comments etc.
  213
+
  214
+Django's permission framework does not have a place to store permissions for
  215
+anonymous users. However, the user object passed to an authentication backend
  216
+may be an :class:`django.contrib.auth.models.AnonymousUser` object, allowing
  217
+the backend to specify custom authorization behavior for anonymous users. This
  218
+is especially useful for the authors of re-usable apps, who can delegate all
  219
+questions of authorization to the auth backend, rather than needing settings,
  220
+for example, to control anonymous access.
  221
+
  222
+.. _inactive_auth:
  223
+
  224
+Authorization for inactive users
  225
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  226
+
  227
+An inactive user is a one that is authenticated but has its attribute
  228
+``is_active`` set to ``False``. However this does not mean they are not
  229
+authorized to do anything. For example they are allowed to activate their
  230
+account.
  231
+
  232
+The support for anonymous users in the permission system allows for a scenario
  233
+where anonymous users have permissions to do something while inactive
  234
+authenticated users do not.
  235
+
  236
+Do not forget to test for the ``is_active`` attribute of the user in your own
  237
+backend permission methods.
  238
+
  239
+
  240
+Handling object permissions
  241
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
  242
+
  243
+Django's permission framework has a foundation for object permissions, though
  244
+there is no implementation for it in the core. That means that checking for
  245
+object permissions will always return ``False`` or an empty list (depending on
  246
+the check performed). An authentication backend will receive the keyword
  247
+parameters ``obj`` and ``user_obj`` for each object related authorization
  248
+method and can return the object level permission as appropriate.
  249
+
  250
+.. _custom-permissions:
  251
+
  252
+Custom permissions
  253
+==================
  254
+
  255
+To create custom permissions for a given model object, use the ``permissions``
  256
+:ref:`model Meta attribute <meta-options>`.
  257
+
  258
+This example Task model creates three custom permissions, i.e., actions users
  259
+can or cannot do with Task instances, specific to your application::
  260
+
  261
+    class Task(models.Model):
  262
+        ...
  263
+        class Meta:
  264
+            permissions = (
  265
+                ("view_task", "Can see available tasks"),
  266
+                ("change_task_status", "Can change the status of tasks"),
  267
+                ("close_task", "Can remove a task by setting its status as closed"),
  268
+            )
  269
+
  270
+The only thing this does is create those extra permissions when you run
  271
+:djadmin:`manage.py syncdb <syncdb>`. Your code is in charge of checking the
  272
+value of these permissions when an user is trying to access the functionality
  273
+provided by the application (viewing tasks, changing the status of tasks,
  274
+closing tasks.) Continuing the above example, the following checks if a user may
  275
+view tasks::
  276
+
  277
+    user.has_perm('app.view_task')
  278
+
  279
+.. _extending-user:
  280
+
  281
+Extending the existing User model
  282
+=================================
  283
+
  284
+There are two ways to extend the default
  285
+:class:`~django.contrib.auth.models.User` model without substituting your own
  286
+model. If the changes you need are purely behavioral, and don't require any
  287
+change to what is stored in the database, you can create a :ref:`proxy model
  288
+<proxy-models>` based on :class:`~django.contrib.auth.models.User`. This
  289
+allows for any of the features offered by proxy models including default
  290
+ordering, custom managers, or custom model methods.
  291
+
  292
+If you wish to store information related to ``User``, you can use a :ref:`one-to-one
  293
+relationship <ref-onetoone>` to a model containing the fields for
  294
+additional information. This one-to-one model is often called a profile model,
  295
+as it might store non-auth related information about a site user. For example
  296
+you might create an Employee model::
  297
+
  298
+    from django.contrib.auth.models import User
  299
+
  300
+    class Employee(models.Model):
  301
+        user = models.OneToOneField(User)
  302
+        department = models.CharField(max_length=100)
  303
+
  304
+Assuming an existing Employee Fred Smith who has both a User and Employee
  305
+model, you can access the related information using Django's standard related
  306
+model conventions::
  307
+
  308
+    >>> u = User.objects.get(username='fsmith')
  309
+    >>> freds_department = u.employee.department
  310
+
  311
+To add a profile model's fields to the user page in the admin, define an
  312
+:class:`~django.contrib.admin.InlineModelAdmin` (for this example, we'll use a
  313
+:class:`~django.contrib.admin.StackedInline`) in your app's ``admin.py`` and
  314
+add it to a ``UserAdmin`` class which is registered with the
  315
+:class:`~django.contrib.auth.models.User` class::
  316
+
  317
+    from django.contrib import admin
  318
+    from django.contrib.auth.admin import UserAdmin
  319
+    from django.contrib.auth.models import User
  320
+
  321
+    from my_user_profile_app.models import Employee
  322
+
  323
+    # Define an inline admin descriptor for Employee model
  324
+    # which acts a bit like a singleton
  325
+    class EmployeeInline(admin.StackedInline):
  326
+        model = Employee
  327
+        can_delete = False
  328
+        verbose_name_plural = 'employee'
  329
+
  330
+    # Define a new User admin
  331
+    class UserAdmin(UserAdmin):
  332
+        inlines = (EmployeeInline, )
  333
+
  334
+    # Re-register UserAdmin
  335
+    admin.site.unregister(User)
  336
+    admin.site.register(User, UserAdmin)
  337
+
  338
+These profile models are not special in any way - they are just Django models that
  339
+happen to have a one-to-one link with a User model. As such, they do not get
  340
+auto created when a user is created, but
  341
+a :attr:`django.db.models.signals.post_save` could be used to create or update
  342
+related models as appropriate.
  343
+
  344
+Note that using related models results in additional queries or joins to
  345
+retrieve the related data, and depending on your needs substituting the User
  346
+model and adding the related fields may be your better option.  However
  347
+existing links to the default User model within your project's apps may justify
  348
+the extra database load.
  349
+
  350
+.. _auth-profiles:
  351
+
  352
+.. deprecated:: 1.5
  353
+    With the introduction of :ref:`custom User models <auth-custom-user>`,
  354
+    the use of :setting:`AUTH_PROFILE_MODULE` to define a single profile
  355
+    model is no longer supported. See the
  356
+    :doc:`Django 1.5 release notes</releases/1.5>` for more information.
  357
+
  358
+Prior to 1.5, a single profile model could be specified site-wide with the
  359
+setting :setting:`AUTH_PROFILE_MODULE` with a string consisting of the
  360
+following items, separated by a dot:
  361
+
  362
+1. The name of the application (case sensitive) in which the user
  363
+   profile model is defined (in other words, the
  364
+   name which was passed to :djadmin:`manage.py startapp <startapp>` to create
  365
+   the application).
  366
+
  367
+2. The name of the model (not case sensitive) class.
  368
+
  369
+For example, if the profile model was a class named ``UserProfile`` and was
  370
+defined inside an application named ``accounts``, the appropriate setting would
  371
+be::
  372
+
  373
+    AUTH_PROFILE_MODULE = 'accounts.UserProfile'
  374
+
  375
+When a user profile model has been defined and specified in this manner, each
  376
+:class:`~django.contrib.auth.models.User` object will have a method --
  377
+:class:`~django.contrib.auth.models.User.get_profile()` -- which returns the
  378
+instance of the user profile model associated with that
  379
+:class:`~django.contrib.auth.models.User`.
  380
+
  381
+The method :class:`~django.contrib.auth.models.User.get_profile()`
  382
+does not create a profile if one does not exist.
  383
+
  384
+.. _auth-custom-user:
  385
+
  386
+Substituting a custom User model
  387
+================================
  388
+
  389
+.. versionadded:: 1.5
  390
+
  391
+Some kinds of projects may have authentication requirements for which Django's
  392
+built-in :class:`~django.contrib.auth.models.User` model is not always
  393
+appropriate. For instance, on some sites it makes more sense to use an email
  394
+address as your identification token instead of a username.
  395
+
  396
+Django allows you to override the default User model by providing a value for
  397
+the :setting:`AUTH_USER_MODEL` setting that references a custom model::
  398
+
  399
+     AUTH_USER_MODEL = 'myapp.MyUser'
  400
+
  401
+This dotted pair describes the name of the Django app, and the name of the Django
  402
+model that you wish to use as your User model.
  403
+
  404
+.. admonition:: Warning
  405
+
  406
+   Changing :setting:`AUTH_USER_MODEL` has a big effect on your database
  407
+   structure. It changes the tables that are available, and it will affect the
  408
+   construction of foreign keys and many-to-many relationships. If you intend
  409
+   to set :setting:`AUTH_USER_MODEL`, you should set it before running
  410
+   ``manage.py syncdb`` for the first time.
  411
+
  412
+   If you have an existing project and you want to migrate to using a custom
  413
+   User model, you may need to look into using a migration tool like South_
  414
+   to ease the transition.
  415
+
  416
+.. _South: http://south.aeracode.org
  417
+
  418
+Referencing the User model
  419
+--------------------------
  420
+
  421
+.. currentmodule:: django.contrib.auth
  422
+
  423
+If you reference :class:`~django.contrib.auth.models.User` directly (for
  424
+example, by referring to it in a foreign key), your code will not work in
  425
+projects where the :setting:`AUTH_USER_MODEL` setting has been changed to a
  426
+different User model.
  427
+
  428
+.. function:: get_user_model()
  429
+
  430
+    Instead of referring to :class:`~django.contrib.auth.models.User` directly,
  431
+    you should reference the user model using
  432
+    ``django.contrib.auth.get_user_model()``. This method will return the
  433
+    currently active User model -- the custom User model if one is specified, or
  434
+    :class:`~django.contrib.auth.models.User` otherwise.
  435
+
  436
+    When you define a foreign key or many-to-many relations to the User model,
  437
+    you should specify the custom model using the :setting:`AUTH_USER_MODEL`
  438
+    setting. For example::
  439
+
  440
+
  441
+        from django.conf import settings
  442
+        from django.db import models
  443
+
  444
+        class Article(models.Model)
  445
+            author = models.ForeignKey(settings.AUTH_USER_MODEL)
  446
+
  447
+Specifying a custom User model
  448
+------------------------------
  449
+
  450
+.. admonition:: Model design considerations
  451
+
  452
+    Think carefully before handling information not directly related to
  453
+    authentication in your custom User Model.
  454
+
  455
+    It may be better to store app-specific user information in a model
  456
+    that has a relation with the User model. That allows each app to specify
  457
+    its own user data requirements without risking conflicts with other
  458
+    apps. On the other hand, queries to retrieve this related information
  459
+    will involve a database join, which may have an effect on performance.
  460
+
  461
+Django expects your custom User model to meet some minimum requirements.
  462
+
  463
+1. Your model must have a single unique field that can be used for
  464
+   identification purposes. This can be a username, an email address,
  465
+   or any other unique attribute.
  466
+
  467
+2. Your model must provide a way to address the user in a "short" and
  468
+   "long" form. The most common interpretation of this would be to use
  469
+   the user's given name as the "short" identifier, and the user's full
  470
+   name as the "long" identifier. However, there are no constraints on