Source

django / docs / authentication.txt

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
=============================
User authentication in Django
=============================

Django comes with a user authentication system. It handles user accounts,
groups, permissions and cookie-based user sessions. This document explains how
things work.

The basics
==========

Django supports authentication out of the box. The ``django-admin.py init``
command, used to initialize a database with Django's core database tables,
creates the infrastructure for the auth system. You don't have to do anything
else to use authentication.

The auth system consists of:

    * Users
    * Permissions: Binary (yes/no) flags designating whether a user may perform
      a certain task.
    * Groups: A generic way of applying labels and permissions to more than one
      user.
    * Messages: A simple way to queue messages for given users.

Users
=====

Users are represented by a standard Django model, which lives in
`django/models/auth.py`_.

.. _django/models/auth.py: http://code.djangoproject.com/browser/django/trunk/django/models/auth.py

API reference
-------------

Fields
~~~~~~

``User`` objects have the following fields:

    * ``username`` -- Required. 30 characters or fewer. Alphanumeric characters
      only (letters, digits and underscores).
    * ``first_name`` -- Optional. 30 characters or fewer.
    * ``last_name`` -- Optional. 30 characters or fewer.
    * ``email`` -- Optional. E-mail address.
    * ``password`` -- Required. A hash of, and metadata about, the password.
      (Django doesn't store the raw password.) Raw passwords can be arbitrarily
      long and can contain any character. See the "Passwords" section below.
    * ``is_staff`` -- Boolean. Designates whether this user can access the
      admin site.
    * ``is_active`` -- Boolean. Designates whether this user can log into the
      Django admin. Set this to ``False`` instead of deleting accounts.
    * ``is_superuser`` -- Boolean. Designates that this user has all permissions
      without explicitly assigning them.
    * ``last_login`` -- A datetime of the user's last login. Is set to the
      current date/time by default.
    * ``date_joined`` -- A datetime designating when the account was created.
      Is set to the current date/time by default when the account is created.

Methods
~~~~~~~

``User`` objects have two many-to-many fields: ``groups`` and
``user_permissions``. Because of those relationships, ``User`` objects get
data-access methods like any other `Django model`_:

    * ``get_group_list(**kwargs)``
    * ``set_groups(id_list)``
    * ``get_permission_list(**kwargs)``
    * ``set_user_permissions(id_list)``

In addition to those automatic API methods, ``User`` objects have the following
methods:

    * ``is_anonymous()`` -- Always returns ``False``. This is a way of
      comparing ``User`` objects to anonymous users.

    * ``get_full_name()`` -- Returns the ``first_name`` plus the ``last_name``,
      with a space in between.

    * ``set_password(raw_password)`` -- Sets the user's password to the given
      raw string, taking care of the MD5 hashing. Doesn't save the ``User``
      object.

    * ``check_password(raw_password)`` -- Returns ``True`` if the given raw
      string is the correct password for the user.

    * ``get_group_permissions()`` -- Returns a list of permission strings that
      the user has, through his/her groups.

    * ``get_all_permissions()`` -- Returns a list of permission strings that
      the user has, both through group and user permissions.

    * ``has_perm(perm)`` -- Returns ``True`` if the user has the specified
      permission, where perm is in the format ``"package.codename"``.

    * ``has_perms(perm_list)`` -- Returns ``True`` if the user has each of the
      specified permissions, where each perm is in the format
      ``"package.codename"``.

    * ``has_module_perms(package_name)`` -- Returns ``True`` if the user has
      any permissions in the given package (the Django app label).

    * ``get_and_delete_messages()`` -- Returns a list of ``Message`` objects in
      the user's queue and deletes the messages from the queue.

    * ``email_user(subject, message, from_email=None)`` -- Sends an e-mail to
      the user. If ``from_email`` is ``None``, Django uses the
      `DEFAULT_FROM_EMAIL`_ setting.

    * ``get_profile()`` -- Returns a site-specific profile for this user.
      Raises ``django.models.auth.SiteProfileNotAvailable`` if the current site
      doesn't allow profiles.

.. _Django model: http://www.djangoproject.com/documentation/model_api/
.. _DEFAULT_FROM_EMAIL: http://www.djangoproject.com/documentation/settings/#default-from-email

Module functions
~~~~~~~~~~~~~~~~

The ``django.models.auth.users`` module has the following helper functions:

    * ``create_user(username, email, password)`` -- Creates, saves and returns
      a ``User``. The ``username``, ``email`` and ``password`` are set as
      given, and the ``User`` gets ``is_active=True``.

    * ``make_random_password(length=10, allowed_chars='abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789')``
      -- Returns a random password with the given length and given string of
      allowed characters. (Note that the default value of ``allowed_chars``
      doesn't contain ``"I"`` or letters that look like it, to avoid user
      confusion.

Basic usage
-----------

Creating users
~~~~~~~~~~~~~~

The most basic way to create users is to use the ``create_user`` helper
function that comes with Django::

    >>> from django.models.auth import users
    >>> user = users.create_user('john', 'lennon@thebeatles.com', 'johnpassword')

    # Now, user is a User object already saved to the database.
    # You can continue to change its attributes if you want to change other fields.
    >>> user.is_staff = True
    >>> user.save()

Changing passwords
~~~~~~~~~~~~~~~~~~

Change a password with ``set_password()``::

    >>> from django.models.auth import users
    >>> u = users.get_object(username__exact='john')
    >>> u.set_password('new password')
    >>> u.save()

Don't set the password field directly unless you know what you're doing. This
is explained in the next section.

Passwords
---------

Previous versions, such as Django 0.90, used simple MD5 hashes without password
salts.

The ``password`` field of a ``User`` object is a string in this format::

    hashtype$salt$hash

That's hashtype, salt and hash, separated by the dollar-sign character.

Hashtype is either ``sha1`` (default) or ``md5``. Salt is a random string
used to salt the raw password to create the hash.

For example::

    sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4

The ``User.set_password()`` and ``User.check_password()`` functions handle
the setting and checking of these values behind the scenes.

Anonymous users
---------------

``django.parts.auth.anonymoususers.AnonymousUser`` is a class that implements
the ``django.models.auth.users.User`` interface, with these differences:

    * ``id`` is always ``None``.
    * ``is_anonymous()`` returns ``True`` instead of ``False``.
    * ``has_perm()`` always returns ``False``.
    * ``set_password()``, ``check_password()``, ``set_groups()`` and
      ``set_permissions()`` raise ``NotImplementedError``.

In practice, you probably won't need to use ``AnonymousUser`` objects on your
own, but they're used by Web requests, as explained in the next section.

Authentication in Web requests
==============================

Until now, this document has dealt with the low-level APIs for manipulating
authentication-related objects. On a higher level, Django hooks this
authentication framework into its system of `request objects`_.

In any Django view, ``request.user`` will give you a ``User`` object
representing the currently logged-in user. If a user isn't currently logged in,
``request.user`` will be set to an instance of ``AnonymousUser`` (see the
previous section). You can tell them apart with ``is_anonymous()``, like so::

    if request.user.is_anonymous():
        # Do something for anonymous users.
    else:
        # Do something for logged-in users.

If you want to use ``request.user`` in your view code, make sure you have
``SessionMiddleware`` enabled. See the `session documentation`_ for more
information.

.. _request objects: http://www.djangoproject.com/documentation/request_response/#httprequest-objects
.. _session documentation: http://www.djangoproject.com/documentation/sessions/

How to log a user in
--------------------

To log a user in, do the following within a view::

    from django.models.auth import users
    request.session[users.SESSION_KEY] = some_user.id

Because this uses sessions, you'll need to make sure you have
``SessionMiddleware`` enabled. See the `session documentation`_ for more
information.

This assumes ``some_user`` is your ``User`` instance. Depending on your task,
you'll probably want to make sure to validate the user's username and password.

Limiting access to logged-in users
----------------------------------

The raw way
~~~~~~~~~~~

The simple, raw way to limit access to pages is to check
``request.user.is_anonymous()`` and either redirect to a login page::

    from django.utils.httpwrappers import HttpResponseRedirect

    def my_view(request):
        if request.user.is_anonymous():
            return HttpResponseRedirect('/login/?next=%s' % request.path)
        # ...

...or display an error message::

    def my_view(request):
        if request.user.is_anonymous():
            return render_to_response('myapp/login_error')
        # ...

The login_required decorator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As a shortcut, you can use the convenient ``login_required`` decorator::

    from django.views.decorators.auth import login_required

    def my_view(request):
        # ...
    my_view = login_required(my_view)

Here's the same thing, using Python 2.4's decorator syntax::

    from django.views.decorators.auth import login_required

    @login_required
    def my_view(request):
        # ...

``login_required`` does the following:

    * If the user isn't logged in, redirect to ``/accounts/login/``, passing
      the current absolute URL in the query string as ``next``. For example:
      ``/accounts/login/?next=/polls/3/``.
    * If the user is logged in, execute the view normally. The view code is
      free to assume the user is logged in.

Limiting access to logged-in users that pass a test
---------------------------------------------------

To limit access based on certain permissions or some other test, you'd do
essentially the same thing as described in the previous section.

The simple way is to run your test on ``request.user`` in the view directly.
For example, this view checks to make sure the user is logged in and has the
permission ``polls.can_vote``::

    def my_view(request):
        if request.user.is_anonymous() or not request.user.has_perm('polls.can_vote'):
            return HttpResponse("You can't vote in this poll.")
        # ...

As a shortcut, you can use the convenient ``user_passes_test`` decorator::

    from django.views.decorators.auth import user_passes_test

    def my_view(request):
        # ...
    my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'))(my_view)

Here's the same thing, using Python 2.4's decorator syntax::

    from django.views.decorators.auth import user_passes_test

    @user_passes_test(lambda u: u.has_perm('polls.can_vote'))
    def my_view(request):
        # ...

``user_passes_test`` takes a required argument: a callable that takes a
``User`` object and returns ``True`` if the user is allowed to view the page.
Note that ``user_passes_test`` does not automatically check that the ``User``
is not anonymous.

``user_passes_test()`` takes an optional ``login_url`` argument, which lets you
specify the URL for your login page (``/accounts/login/`` by default).

Example in Python 2.3 syntax::

    from django.views.decorators.auth import user_passes_test

    def my_view(request):
        # ...
    my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'), login_url='/login/')(my_view)

Example in Python 2.4 syntax::

    from django.views.decorators.auth import user_passes_test

    @user_passes_test(lambda u: u.has_perm('polls.can_vote'), login_url='/login/')
    def my_view(request):
        # ...

Limiting access to generic views
--------------------------------

To limit access to a `generic view`_, write a thin wrapper around the view,
and point your URLconf to your wrapper instead of the generic view itself.
For example::

    from django.views.generic.date_based import object_detail

    @login_required
    def limited_object_detail(*args, **kwargs):
        return object_detail(*args, **kwargs)

.. _generic view: http://www.djangoproject.com/documentation/generic_views/

Permissions
===========

Django comes with a simple permissions system. It provides a way to assign
permissions to specific users and groups of users.

It's used by the Django admin site, but you're welcome to use it in your own
code.

The Django admin site uses permissions as follows:

    * Access to view the "add" form and add an object is limited to users with
      the "add" permission for that type of object.
    * Access to view the change list, view the "change" form and change an
      object is limited to users with the "change" permission for that type of
      object.
    * Access to delete an object is limited to users with the "delete"
      permission for that type of object.

Permissions are set globally per type of object, not per specific object
instance. For example, it's possible to say "Mary may change news stories," but
it's not currently possible to say "Mary may change news stories, but only the
ones she created herself" or "Mary may only change news stories that have a
certain status or publication date." The latter functionality is something
Django developers are currently discussing.

Default permissions
-------------------

Three basic permissions -- add, create and delete -- are automatically created
for each Django model that has ``admin`` set. Behind the scenes, these
permissions are added to the ``auth_permissions`` database table when you run
``django-admin.py install [app]``. You can view the exact SQL ``INSERT``
statements by running ``django-admin.py sqlinitialdata [app]``.

Note that if your model doesn't have ``admin`` set when you run
``django-admin.py install``, the permissions won't be created. If you
initialize your database and add ``admin`` to models after the fact, you'll
need to add the permissions to the database manually. Do this by running
``django-admin.py installperms [app]``, which creates any missing permissions
for the given app.

Custom permissions
------------------

To create custom permissions for a given model object, use the ``permissions``
`model META attribute`_.

This example model creates three custom permissions::

    class USCitizen(meta.Model):
        # ...
        class META:
            permissions = (
                ("can_drive", "Can drive"),
                ("can_vote", "Can vote in elections"),
                ("can_drink", "Can drink alcohol"),
            )

.. _model META attribute: http://www.djangoproject.com/documentation/model_api/#meta-options

API reference
-------------

Just like users, permissions are implemented in a Django model that lives in
`django/models/auth.py`_.

Fields
~~~~~~

``Permission`` objects have the following fields:

    * ``name`` -- Required. 50 characters or fewer. Example: ``'Can vote'``.
    * ``package`` -- Required. A reference to the ``packages`` database table,
      which contains a record for each installed Django application.
    * ``codename`` -- Required. 100 characters or fewer. Example: ``'can_vote'``.

Methods
~~~~~~~

``Permission`` objects have the standard data-access methods like any other
`Django model`_:

Authentication data in templates
================================

The currently logged-in user and his/her permissions are made available in the
`template context`_ when you use ``DjangoContext``.

.. admonition:: Technicality

   Technically, these variables are only made available in the template context
   if you use ``DjangoContext`` *and* your ``TEMPLATE_CONTEXT_PROCESSORS``
   setting contains ``"django.core.context_processors.auth"``, which is default.
   For more, see the `DjangoContext docs`_.

   .. _DjangoContext docs: http://www.djangoproject.com/documentation/templates_python/#subclassing-context-djangocontext

Users
-----

The currently logged-in user, either a ``User`` object or an``AnonymousUser``
instance, is stored in the template variable ``{{ user }}``::

    {% if user.is_anonymous %}
        <p>Welcome, new user. Please log in.</p>
    {% else %}
        <p>Welcome, {{ user.username }}. Thanks for logging in.</p>
    {% endif %}

Permissions
-----------

The currently logged-in user's permissions are stored in the template variable
``{{ perms }}``. This is an instance of ``django.core.context_processors.PermWrapper``,
which is a template-friendly proxy of permissions.

In the ``{{ perms }}`` object, single-attribute lookup is a proxy to
``User.has_module_perms``. This example would display ``True`` if the logged-in
user had any permissions in the ``foo`` app::

    {{ perms.foo }}

Two-level-attribute lookup is a proxy to ``User.has_perm``. This example would
display ``True`` if the logged-in user had the permission ``foo.can_vote``::

    {{ perms.foo.can_vote }}

Thus, you can check permissions in template ``{% if %}`` statements::

    {% if perms.foo %}
        <p>You have permission to do something in the foo app.</p>
        {% if perms.foo.can_vote %}
            <p>You can vote!</p>
        {% endif %}
        {% if perms.foo.can_drive %}
            <p>You can drive!</p>
        {% endif %}
    {% else %}
        <p>You don't have permission to do anything in the foo app.</p>
    {% endif %}

.. _template context: http://www.djangoproject.com/documentation/templates_python/

Groups
======

Groups are a generic way of categorizing users to apply permissions, or some
other label, to those users. A user can belong to any number of groups.

A user in a group automatically has the permissions granted to that group. For
example, if the group ``Site editors`` has the permission
``can_edit_home_page``, any user in that group will have that permission.

Beyond permissions, groups are a convenient way to categorize users to apply
some label, or extended functionality, to them. For example, you could create
a group ``'Special users'``, and you could write code that would do special
things to those users -- such as giving them access to a members-only portion
of your site, or sending them members-only e-mail messages.

Messages
========

The message system is a lightweight way to queue messages for given users.

A message is associated with a User. There's no concept of expiration or
timestamps.

Messages are used by the Django admin after successful actions. For example,
``"The poll Foo was created successfully."`` is a message.

The API is simple::

    * To add messages, use ``user.add_message(message_text)``.
    * To retrieve/delete messages, use ``user.get_and_delete_messages()``,
      which returns a list of ``Message`` objects in the user's queue (if any)
      and deletes the messages from the queue.

In this example view, the system saves a message for the user after creating
a playlist::

    def create_playlist(request, songs):
        # Create the playlist with the given songs.
        # ...
        request.user.add_message("Your playlist was added successfully.")
        return render_to_response("playlists/create", context_instance=DjangoContext(request))

When you use ``DjangoContext``, the currently logged-in user and his/her
messages are made available in the `template context`_ as the template variable
``{{ messages }}``. Here's an example of template code that displays messages::

    {% if messages %}
    <ul>
        {% for message in messages %}
        <li>{{ message.message }}</li>
        {% endfor %}
    </ul>
    {% endif %}

Note that ``DjangoContext`` calls ``get_and_delete_messages`` behind the
scenes, so any messages will be deleted even if you don't display them.

Finally, note that this messages framework only works with users in the user
database. To send messages to anonymous users, use the `session framework`_.

.. _session framework: http://www.djangoproject.com/documentation/sessions/
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.