1
=============================
2
User authentication in Django
3
=============================
5
Django comes with a user authentication system. It handles user accounts,
6
groups, permissions and cookie-based user sessions. This document explains how
12
The auth system consists of:
15
* Permissions: Binary (yes/no) flags designating whether a user may perform
17
* Groups: A generic way of applying labels and permissions to more than one
19
* Messages: A simple way to queue messages for given users.
24
Authentication support is bundled as a Django application in
25
``django.contrib.auth``. To install it, do the following:
27
1. Put ``'django.contrib.auth'`` in your ``INSTALLED_APPS`` setting.
28
2. Run the command ``manage.py syncdb``.
30
Note that the default ``settings.py`` file created by
31
``django-admin.py startproject`` includes ``'django.contrib.auth'`` in
32
``INSTALLED_APPS`` for convenience. If your ``INSTALLED_APPS`` already contains
33
``'django.contrib.auth'``, feel free to run ``manage.py syncdb`` again; you
34
can run that command as many times as you'd like, and each time it'll only
35
install what's needed.
37
The ``syncdb`` command creates the necessary database tables, creates
38
permission objects for all installed apps that need 'em, and prompts you to
39
create a superuser account the first time you run it.
41
Once you've taken those steps, that's it.
46
Users are represented by a standard Django model, which lives in
47
`django/contrib/auth/models.py`_.
49
.. _django/contrib/auth/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/models.py
57
``User`` objects have the following fields:
59
* ``username`` -- Required. 30 characters or fewer. Alphanumeric characters
60
only (letters, digits and underscores).
61
* ``first_name`` -- Optional. 30 characters or fewer.
62
* ``last_name`` -- Optional. 30 characters or fewer.
63
* ``email`` -- Optional. E-mail address.
64
* ``password`` -- Required. A hash of, and metadata about, the password.
65
(Django doesn't store the raw password.) Raw passwords can be arbitrarily
66
long and can contain any character. See the "Passwords" section below.
67
* ``is_staff`` -- Boolean. Designates whether this user can access the
69
* ``is_active`` -- Boolean. Designates whether this account can be used
70
to log in. Set this flag to ``False`` instead of deleting accounts.
71
* ``is_superuser`` -- Boolean. Designates that this user has all permissions
72
without explicitly assigning them.
73
* ``last_login`` -- A datetime of the user's last login. Is set to the
74
current date/time by default.
75
* ``date_joined`` -- A datetime designating when the account was created.
76
Is set to the current date/time by default when the account is created.
81
``User`` objects have two many-to-many fields: ``groups`` and
82
``user_permissions``. ``User`` objects can access their related
83
objects in the same way as any other `Django model`_::
85
myuser.groups = [group_list]
86
myuser.groups.add(group, group,...)
87
myuser.groups.remove(group, group,...)
89
myuser.user_permissions = [permission_list]
90
myuser.user_permissions.add(permission, permission, ...)
91
myuser.user_permissions.remove(permission, permission, ...]
92
myuser.user_permissions.clear()
94
In addition to those automatic API methods, ``User`` objects have the following
97
* ``is_anonymous()`` -- Always returns ``False``. This is a way of
98
differentiating ``User`` and ``AnonymousUser`` objects. Generally, you
99
should prefer using ``is_authenticated()`` to this method.
101
* ``is_authenticated()`` -- Always returns ``True``. This is a way to
102
tell if the user has been authenticated. This does not imply any
103
permissions, and doesn't check if the user is active - it only indicates
104
that the user has provided a valid username and password.
106
* ``get_full_name()`` -- Returns the ``first_name`` plus the ``last_name``,
107
with a space in between.
109
* ``set_password(raw_password)`` -- Sets the user's password to the given
110
raw string, taking care of the password hashing. Doesn't save the
113
* ``check_password(raw_password)`` -- Returns ``True`` if the given raw
114
string is the correct password for the user. (This takes care of the
115
password hashing in making the comparison.)
117
* ``get_group_permissions()`` -- Returns a list of permission strings that
118
the user has, through his/her groups.
120
* ``get_all_permissions()`` -- Returns a list of permission strings that
121
the user has, both through group and user permissions.
123
* ``has_perm(perm)`` -- Returns ``True`` if the user has the specified
124
permission, where perm is in the format ``"package.codename"``.
125
If the user is inactive, this method will always return ``False``.
127
* ``has_perms(perm_list)`` -- Returns ``True`` if the user has each of the
128
specified permissions, where each perm is in the format
129
``"package.codename"``. If the user is inactive, this method will
130
always return ``False``.
132
* ``has_module_perms(package_name)`` -- Returns ``True`` if the user has
133
any permissions in the given package (the Django app label).
134
If the user is inactive, this method will always return ``False``.
136
* ``get_and_delete_messages()`` -- Returns a list of ``Message`` objects in
137
the user's queue and deletes the messages from the queue.
139
* ``email_user(subject, message, from_email=None)`` -- Sends an e-mail to
140
the user. If ``from_email`` is ``None``, Django uses the
141
`DEFAULT_FROM_EMAIL`_ setting.
143
* ``get_profile()`` -- Returns a site-specific profile for this user.
144
Raises ``django.contrib.auth.models.SiteProfileNotAvailable`` if the current site
145
doesn't allow profiles.
147
.. _Django model: ../model_api/
148
.. _DEFAULT_FROM_EMAIL: ../settings/#default-from-email
153
The ``User`` model has a custom manager that has the following helper functions:
155
* ``create_user(username, email, password)`` -- Creates, saves and returns
156
a ``User``. The ``username``, ``email`` and ``password`` are set as
157
given, and the ``User`` gets ``is_active=True``.
159
See _`Creating users` for example usage.
161
* ``make_random_password(length=10, allowed_chars='abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789')``
162
Returns a random password with the given length and given string of
163
allowed characters. (Note that the default value of ``allowed_chars``
164
doesn't contain ``"I"`` or letters that look like it, to avoid user
173
The most basic way to create users is to use the ``create_user`` helper
174
function that comes with Django::
176
>>> from django.contrib.auth.models import User
177
>>> user = User.objects.create_user('john', 'lennon@thebeatles.com', 'johnpassword')
179
# At this point, user is a User object ready to be saved
180
# to the database. You can continue to change its attributes
181
# if you want to change other fields.
182
>>> user.is_staff = True
188
Change a password with ``set_password()``::
190
>>> from django.contrib.auth.models import User
191
>>> u = User.objects.get(username__exact='john')
192
>>> u.set_password('new password')
195
Don't set the ``password`` attribute directly unless you know what you're
196
doing. This is explained in the next section.
201
The ``password`` attribute of a ``User`` object is a string in this format::
205
That's hashtype, salt and hash, separated by the dollar-sign character.
207
Hashtype is either ``sha1`` (default) or ``md5`` -- the algorithm used to
208
perform a one-way hash of the password. Salt is a random string used to salt
209
the raw password to create the hash.
213
sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4
215
The ``User.set_password()`` and ``User.check_password()`` functions handle
216
the setting and checking of these values behind the scenes.
218
Previous Django versions, such as 0.90, used simple MD5 hashes without password
219
salts. For backwards compatibility, those are still supported; they'll be
220
converted automatically to the new style the first time ``check_password()``
221
works correctly for a given user.
226
``django.contrib.auth.models.AnonymousUser`` is a class that implements
227
the ``django.contrib.auth.models.User`` interface, with these differences:
229
* ``id`` is always ``None``.
230
* ``is_anonymous()`` returns ``True`` instead of ``False``.
231
* ``is_authenticated()`` returns ``False`` instead of ``True``.
232
* ``has_perm()`` always returns ``False``.
233
* ``set_password()``, ``check_password()``, ``save()``, ``delete()``,
234
``set_groups()`` and ``set_permissions()`` raise ``NotImplementedError``.
236
In practice, you probably won't need to use ``AnonymousUser`` objects on your
237
own, but they're used by Web requests, as explained in the next section.
242
``manage.py syncdb`` prompts you to create a superuser the first time you run
243
it after adding ``'django.contrib.auth'`` to your ``INSTALLED_APPS``. But if
244
you need to create a superuser after that via the command line, you can use the
245
``create_superuser.py`` utility. Just run this command::
247
python /path/to/django/contrib/auth/create_superuser.py
249
Make sure to substitute ``/path/to/`` with the path to the Django codebase on
252
Authentication in Web requests
253
==============================
255
Until now, this document has dealt with the low-level APIs for manipulating
256
authentication-related objects. On a higher level, Django can hook this
257
authentication framework into its system of `request objects`_.
259
First, install the ``SessionMiddleware`` and ``AuthenticationMiddleware``
260
middlewares by adding them to your ``MIDDLEWARE_CLASSES`` setting. See the
261
`session documentation`_ for more information.
263
Once you have those middlewares installed, you'll be able to access
264
``request.user`` in views. ``request.user`` will give you a ``User`` object
265
representing the currently logged-in user. If a user isn't currently logged in,
266
``request.user`` will be set to an instance of ``AnonymousUser`` (see the
267
previous section). You can tell them apart with ``is_authenticated()``, like so::
269
if request.user.is_authenticated():
270
# Do something for authenticated users.
272
# Do something for anonymous users.
274
.. _request objects: ../request_response/#httprequest-objects
275
.. _session documentation: ../sessions/
280
Django provides two functions in ``django.contrib.auth``: ``authenticate()``
283
To authenticate a given username and password, use ``authenticate()``. It
284
takes two keyword arguments, ``username`` and ``password``, and it returns
285
a ``User`` object if the password is valid for the given username. If the
286
password is invalid, ``authenticate()`` returns ``None``. Example::
288
from django.contrib.auth import authenticate
289
user = authenticate(username='john', password='secret')
292
print "You provided a correct username and password!"
294
print "Your account has been disabled!"
296
print "Your username and password were incorrect."
298
To log a user in, in a view, use ``login()``. It takes an ``HttpRequest``
299
object and a ``User`` object. ``login()`` saves the user's ID in the session,
300
using Django's session framework, so, as mentioned above, you'll need to make
301
sure to have the session middleware installed.
303
This example shows how you might use both ``authenticate()`` and ``login()``::
305
from django.contrib.auth import authenticate, login
307
def my_view(request):
308
username = request.POST['username']
309
password = request.POST['password']
310
user = authenticate(username=username, password=password)
314
# Redirect to a success page.
316
# Return a 'disabled account' error message
318
# Return an 'invalid login' error message.
320
Manually checking a user's password
321
-----------------------------------
323
If you'd like to manually authenticate a user by comparing a
324
plain-text password to the hashed password in the database, use the
325
convenience function `django.contrib.auth.models.check_password`. It
326
takes two arguments: the plain-text password to check, and the full
327
value of a user's ``password`` field in the database to check against,
328
and returns ``True`` if they match, ``False`` otherwise.
330
How to log a user out
331
---------------------
333
To log out a user who has been logged in via ``django.contrib.auth.login()``,
334
use ``django.contrib.auth.logout()`` within your view. It takes an
335
``HttpRequest`` object and has no return value. Example::
337
from django.contrib.auth import logout
339
def logout_view(request):
341
# Redirect to a success page.
343
Note that ``logout()`` doesn't throw any errors if the user wasn't logged in.
345
Limiting access to logged-in users
346
----------------------------------
351
The simple, raw way to limit access to pages is to check
352
``request.user.is_authenticated()`` and either redirect to a login page::
354
from django.http import HttpResponseRedirect
356
def my_view(request):
357
if not request.user.is_authenticated():
358
return HttpResponseRedirect('/login/?next=%s' % request.path)
361
...or display an error message::
363
def my_view(request):
364
if not request.user.is_authenticated():
365
return render_to_response('myapp/login_error.html')
368
The login_required decorator
369
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
371
As a shortcut, you can use the convenient ``login_required`` decorator::
373
from django.contrib.auth.decorators import login_required
375
def my_view(request):
377
my_view = login_required(my_view)
379
Here's an equivalent example, using the more compact decorator syntax
380
introduced in Python 2.4::
382
from django.contrib.auth.decorators import login_required
385
def my_view(request):
388
``login_required`` does the following:
390
* If the user isn't logged in, redirect to ``/accounts/login/``, passing
391
the current absolute URL in the query string as ``next``. For example:
392
``/accounts/login/?next=/polls/3/``.
393
* If the user is logged in, execute the view normally. The view code is
394
free to assume the user is logged in.
396
Note that you'll need to map the appropriate Django view to ``/accounts/login/``.
397
To do this, add the following line to your URLconf::
399
(r'^accounts/login/$', 'django.contrib.auth.views.login'),
401
Here's what ``django.contrib.auth.views.login`` does:
403
* If called via ``GET``, it displays a login form that POSTs to the same
404
URL. More on this in a bit.
406
* If called via ``POST``, it tries to log the user in. If login is
407
successful, the view redirects to the URL specified in ``next``. If
408
``next`` isn't provided, it redirects to ``/accounts/profile/`` (which is
409
currently hard-coded). If login isn't successful, it redisplays the login
412
It's your responsibility to provide the login form in a template called
413
``registration/login.html`` by default. This template gets passed three
414
template context variables:
416
* ``form``: A ``FormWrapper`` object representing the login form. See the
417
`forms documentation`_ for more on ``FormWrapper`` objects.
418
* ``next``: The URL to redirect to after successful login. This may contain
420
* ``site_name``: The name of the current ``Site``, according to the
421
``SITE_ID`` setting. See the `site framework docs`_.
423
If you'd prefer not to call the template ``registration/login.html``, you can
424
pass the ``template_name`` parameter via the extra arguments to the view in
425
your URLconf. For example, this URLconf line would use ``myapp/login.html``
428
(r'^accounts/login/$', 'django.contrib.auth.views.login', {'template_name': 'myapp/login.html'}),
430
Here's a sample ``registration/login.html`` template you can use as a starting
431
point. It assumes you have a ``base.html`` template that defines a ``content``
434
{% extends "base.html" %}
438
{% if form.has_errors %}
439
<p>Your username and password didn't match. Please try again.</p>
442
<form method="post" action=".">
444
<tr><td><label for="id_username">Username:</label></td><td>{{ form.username }}</td></tr>
445
<tr><td><label for="id_password">Password:</label></td><td>{{ form.password }}</td></tr>
448
<input type="submit" value="login" />
449
<input type="hidden" name="next" value="{{ next }}" />
454
.. _forms documentation: ../forms/
455
.. _site framework docs: ../sites/
460
In addition to the `login` view, the authentication system includes a
461
few other useful built-in views:
463
``django.contrib.auth.views.logout``
464
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
470
**Optional arguments:**
472
* ``template_name``: The full name of a template to display after
473
logging the user out. This will default to
474
``registration/logged_out.html`` if no argument is supplied.
476
**Template context:**
478
* ``title``: The string "Logged out", localized.
480
``django.contrib.auth.views.logout_then_login``
481
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
485
Logs a user out, then redirects to the login page.
487
**Optional arguments:**
489
* ``login_url``: The URL of the login page to redirect to. This
490
will default to ``/accounts/login/`` if not supplied.
492
``django.contrib.auth.views.password_change``
493
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
497
Allows a user to change their password.
499
**Optional arguments:**
501
* ``template_name``: The full name of a template to use for
502
displaying the password change form. This will default to
503
``registration/password_change_form.html`` if not supplied.
505
**Template context:**
507
* ``form``: The password change form.
509
``django.contrib.auth.views.password_change_done``
510
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
514
The page shown after a user has changed their password.
516
**Optional arguments:**
518
* ``template_name``: The full name of a template to use. This will
519
default to ``registration/password_change_done.html`` if not
522
``django.contrib.auth.views.password_reset``
523
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
527
Allows a user to reset their password, and sends them the new password
530
**Optional arguments:**
532
* ``template_name``: The full name of a template to use for
533
displaying the password reset form. This will default to
534
``registration/password_reset_form.html`` if not supplied.
536
* ``email_template_name``: The full name of a template to use for
537
generating the email with the new password. This will default to
538
``registration/password_reset_email.html`` if not supplied.
540
**Template context:**
542
* ``form``: The form for resetting the user's password.
544
``django.contrib.auth.views.password_reset_done``
545
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
549
The page shown after a user has reset their password.
551
**Optional arguments:**
553
* ``template_name``: The full name of a template to use. This will
554
default to ``registration/password_reset_done.html`` if not
557
``django.contrib.auth.views.redirect_to_login``
558
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
562
Redirects to the login page, and then back to another URL after a
565
**Required arguments:**
567
* ``next``: The URL to redirect to after a successful login.
569
**Optional arguments:**
571
* ``login_url``: The URL of the login page to redirect to. This
572
will default to ``/accounts/login/`` if not supplied.
574
Built-in manipulators
575
---------------------
577
If you don't want to use the built-in views, but want the convenience
578
of not having to write manipulators for this functionality, the
579
authentication system provides several built-in manipulators:
581
* ``django.contrib.auth.forms.AdminPasswordChangeForm``: A
582
manipulator used in the admin interface to change a user's
585
* ``django.contrib.auth.forms.AuthenticationForm``: A manipulator
586
for logging a user in.
588
* ``django.contrib.auth.forms.PasswordChangeForm``: A manipulator
589
for allowing a user to change their password.
591
* ``django.contrib.auth.forms.PasswordResetForm``: A manipulator
592
for resetting a user's password and emailing the new password to
595
* ``django.contrib.auth.forms.UserCreationForm``: A manipulator
596
for creating a new user.
598
Limiting access to logged-in users that pass a test
599
---------------------------------------------------
601
To limit access based on certain permissions or some other test, you'd do
602
essentially the same thing as described in the previous section.
604
The simple way is to run your test on ``request.user`` in the view directly.
605
For example, this view checks to make sure the user is logged in and has the
606
permission ``polls.can_vote``::
608
def my_view(request):
609
if not (request.user.is_authenticated() and request.user.has_perm('polls.can_vote')):
610
return HttpResponse("You can't vote in this poll.")
613
As a shortcut, you can use the convenient ``user_passes_test`` decorator::
615
from django.contrib.auth.decorators import user_passes_test
617
def my_view(request):
619
my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'))(my_view)
621
We're using this particular test as a relatively simple example. However, if
622
you just want to test whether a permission is available to a user, you can use
623
the ``permission_required()`` decorator, described later in this document.
625
Here's the same thing, using Python 2.4's decorator syntax::
627
from django.contrib.auth.decorators import user_passes_test
629
@user_passes_test(lambda u: u.has_perm('polls.can_vote'))
630
def my_view(request):
633
``user_passes_test`` takes a required argument: a callable that takes a
634
``User`` object and returns ``True`` if the user is allowed to view the page.
635
Note that ``user_passes_test`` does not automatically check that the ``User``
638
``user_passes_test()`` takes an optional ``login_url`` argument, which lets you
639
specify the URL for your login page (``/accounts/login/`` by default).
641
Example in Python 2.3 syntax::
643
from django.contrib.auth.decorators import user_passes_test
645
def my_view(request):
647
my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'), login_url='/login/')(my_view)
649
Example in Python 2.4 syntax::
651
from django.contrib.auth.decorators import user_passes_test
653
@user_passes_test(lambda u: u.has_perm('polls.can_vote'), login_url='/login/')
654
def my_view(request):
657
The permission_required decorator
658
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
660
**New in Django development version**
662
It's a relatively common task to check whether a user has a particular
663
permission. For that reason, Django provides a shortcut for that case: the
664
``permission_required()`` decorator. Using this decorator, the earlier example
667
from django.contrib.auth.decorators import permission_required
669
def my_view(request):
671
my_view = permission_required('polls.can_vote')(my_view)
673
Note that ``permission_required()`` also takes an optional ``login_url``
676
from django.contrib.auth.decorators import permission_required
678
def my_view(request):
680
my_view = permission_required('polls.can_vote', login_url='/loginpage/')(my_view)
682
As in the ``login_required`` decorator, ``login_url`` defaults to
683
``'/accounts/login/'``.
685
Limiting access to generic views
686
--------------------------------
688
To limit access to a `generic view`_, write a thin wrapper around the view,
689
and point your URLconf to your wrapper instead of the generic view itself.
692
from django.views.generic.date_based import object_detail
695
def limited_object_detail(*args, **kwargs):
696
return object_detail(*args, **kwargs)
698
.. _generic view: ../generic_views/
703
Django comes with a simple permissions system. It provides a way to assign
704
permissions to specific users and groups of users.
706
It's used by the Django admin site, but you're welcome to use it in your own
709
The Django admin site uses permissions as follows:
711
* Access to view the "add" form and add an object is limited to users with
712
the "add" permission for that type of object.
713
* Access to view the change list, view the "change" form and change an
714
object is limited to users with the "change" permission for that type of
716
* Access to delete an object is limited to users with the "delete"
717
permission for that type of object.
719
Permissions are set globally per type of object, not per specific object
720
instance. For example, it's possible to say "Mary may change news stories," but
721
it's not currently possible to say "Mary may change news stories, but only the
722
ones she created herself" or "Mary may only change news stories that have a
723
certain status, publication date or ID." The latter functionality is something
724
Django developers are currently discussing.
729
Three basic permissions -- add, create and delete -- are automatically created
730
for each Django model that has a ``class Admin`` set. Behind the scenes, these
731
permissions are added to the ``auth_permission`` database table when you run
732
``manage.py syncdb``.
734
Note that if your model doesn't have ``class Admin`` set when you run
735
``syncdb``, the permissions won't be created. If you initialize your database
736
and add ``class Admin`` to models after the fact, you'll need to run
737
``manage.py syncdb`` again. It will create any missing permissions for
738
all of your installed apps.
743
To create custom permissions for a given model object, use the ``permissions``
744
`model Meta attribute`_.
746
This example model creates three custom permissions::
748
class USCitizen(models.Model):
752
("can_drive", "Can drive"),
753
("can_vote", "Can vote in elections"),
754
("can_drink", "Can drink alcohol"),
757
The only thing this does is create those extra permissions when you run
760
.. _model Meta attribute: ../model_api/#meta-options
765
Just like users, permissions are implemented in a Django model that lives in
766
`django/contrib/auth/models.py`_.
768
.. _django/contrib/auth/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/models.py
773
``Permission`` objects have the following fields:
775
* ``name`` -- Required. 50 characters or fewer. Example: ``'Can vote'``.
776
* ``content_type`` -- Required. A reference to the ``django_content_type``
777
database table, which contains a record for each installed Django model.
778
* ``codename`` -- Required. 100 characters or fewer. Example: ``'can_vote'``.
783
``Permission`` objects have the standard data-access methods like any other
786
Authentication data in templates
787
================================
789
The currently logged-in user and his/her permissions are made available in the
790
`template context`_ when you use ``RequestContext``.
792
.. admonition:: Technicality
794
Technically, these variables are only made available in the template context
795
if you use ``RequestContext`` *and* your ``TEMPLATE_CONTEXT_PROCESSORS``
796
setting contains ``"django.core.context_processors.auth"``, which is default.
797
For more, see the `RequestContext docs`_.
799
.. _RequestContext docs: ../templates_python/#subclassing-context-requestcontext
804
The currently logged-in user, either a ``User`` instance or an``AnonymousUser``
805
instance, is stored in the template variable ``{{ user }}``::
807
{% if user.is_authenticated %}
808
<p>Welcome, {{ user.username }}. Thanks for logging in.</p>
810
<p>Welcome, new user. Please log in.</p>
816
The currently logged-in user's permissions are stored in the template variable
817
``{{ perms }}``. This is an instance of ``django.core.context_processors.PermWrapper``,
818
which is a template-friendly proxy of permissions.
820
In the ``{{ perms }}`` object, single-attribute lookup is a proxy to
821
``User.has_module_perms``. This example would display ``True`` if the logged-in
822
user had any permissions in the ``foo`` app::
826
Two-level-attribute lookup is a proxy to ``User.has_perm``. This example would
827
display ``True`` if the logged-in user had the permission ``foo.can_vote``::
829
{{ perms.foo.can_vote }}
831
Thus, you can check permissions in template ``{% if %}`` statements::
834
<p>You have permission to do something in the foo app.</p>
835
{% if perms.foo.can_vote %}
838
{% if perms.foo.can_drive %}
839
<p>You can drive!</p>
842
<p>You don't have permission to do anything in the foo app.</p>
845
.. _template context: ../templates_python/
850
Groups are a generic way of categorizing users so you can apply permissions, or
851
some other label, to those users. A user can belong to any number of groups.
853
A user in a group automatically has the permissions granted to that group. For
854
example, if the group ``Site editors`` has the permission
855
``can_edit_home_page``, any user in that group will have that permission.
857
Beyond permissions, groups are a convenient way to categorize users to give
858
them some label, or extended functionality. For example, you could create a
859
group ``'Special users'``, and you could write code that could, say, give them
860
access to a members-only portion of your site, or send them members-only e-mail
866
The message system is a lightweight way to queue messages for given users.
868
A message is associated with a ``User``. There's no concept of expiration or
871
Messages are used by the Django admin after successful actions. For example,
872
``"The poll Foo was created successfully."`` is a message.
876
* To create a new message, use
877
``user_obj.message_set.create(message='message_text')``.
878
* To retrieve/delete messages, use ``user_obj.get_and_delete_messages()``,
879
which returns a list of ``Message`` objects in the user's queue (if any)
880
and deletes the messages from the queue.
882
In this example view, the system saves a message for the user after creating
885
def create_playlist(request, songs):
886
# Create the playlist with the given songs.
888
request.user.message_set.create(message="Your playlist was added successfully.")
889
return render_to_response("playlists/create.html",
890
context_instance=RequestContext(request))
892
When you use ``RequestContext``, the currently logged-in user and his/her
893
messages are made available in the `template context`_ as the template variable
894
``{{ messages }}``. Here's an example of template code that displays messages::
898
{% for message in messages %}
899
<li>{{ message }}</li>
904
Note that ``RequestContext`` calls ``get_and_delete_messages`` behind the
905
scenes, so any messages will be deleted even if you don't display them.
907
Finally, note that this messages framework only works with users in the user
908
database. To send messages to anonymous users, use the `session framework`_.
910
.. _session framework: ../sessions/
912
Other authentication sources
913
============================
915
The authentication that comes with Django is good enough for most common cases,
916
but you may have the need to hook into another authentication source -- that
917
is, another source of usernames and passwords or authentication methods.
919
For example, your company may already have an LDAP setup that stores a username
920
and password for every employee. It'd be a hassle for both the network
921
administrator and the users themselves if users had separate accounts in LDAP
922
and the Django-based applications.
924
So, to handle situations like this, the Django authentication system lets you
925
plug in another authentication sources. You can override Django's default
926
database-based scheme, or you can use the default system in tandem with other
929
Specifying authentication backends
930
----------------------------------
932
Behind the scenes, Django maintains a list of "authentication backends" that it
933
checks for authentication. When somebody calls
934
``django.contrib.auth.authenticate()`` -- as described in "How to log a user in"
935
above -- Django tries authenticating across all of its authentication backends.
936
If the first authentication method fails, Django tries the second one, and so
937
on, until all backends have been attempted.
939
The list of authentication backends to use is specified in the
940
``AUTHENTICATION_BACKENDS`` setting. This should be a tuple of Python path
941
names that point to Python classes that know how to authenticate. These classes
942
can be anywhere on your Python path.
944
By default, ``AUTHENTICATION_BACKENDS`` is set to::
946
('django.contrib.auth.backends.ModelBackend',)
948
That's the basic authentication scheme that checks the Django users database.
950
The order of ``AUTHENTICATION_BACKENDS`` matters, so if the same username and
951
password is valid in multiple backends, Django will stop processing at the
952
first positive match.
954
Writing an authentication backend
955
---------------------------------
957
An authentication backend is a class that implements two methods:
958
``get_user(id)`` and ``authenticate(**credentials)``.
960
The ``get_user`` method takes an ``id`` -- which could be a username, database
961
ID or whatever -- and returns a ``User`` object.
963
The ``authenticate`` method takes credentials as keyword arguments. Most of
964
the time, it'll just look like this::
967
def authenticate(self, username=None, password=None):
968
# Check the username/password and return a User.
970
But it could also authenticate a token, like so::
973
def authenticate(self, token=None):
974
# Check the token and return a User.
976
Either way, ``authenticate`` should check the credentials it gets, and it
977
should return a ``User`` object that matches those credentials, if the
978
credentials are valid. If they're not valid, it should return ``None``.
980
The Django admin system is tightly coupled to the Django ``User`` object
981
described at the beginning of this document. For now, the best way to deal with
982
this is to create a Django ``User`` object for each user that exists for your
983
backend (e.g., in your LDAP directory, your external SQL database, etc.) You
984
can either write a script to do this in advance, or your ``authenticate``
985
method can do it the first time a user logs in.
987
Here's an example backend that authenticates against a username and password
988
variable defined in your ``settings.py`` file and creates a Django ``User``
989
object the first time a user authenticates::
991
from django.conf import settings
992
from django.contrib.auth.models import User, check_password
994
class SettingsBackend:
996
Authenticate against the settings ADMIN_LOGIN and ADMIN_PASSWORD.
998
Use the login name, and a hash of the password. For example:
1000
ADMIN_LOGIN = 'admin'
1001
ADMIN_PASSWORD = 'sha1$4e987$afbcf42e21bd417fb71db8c66b321e9fc33051de'
1003
def authenticate(self, username=None, password=None):
1004
login_valid = (settings.ADMIN_LOGIN == username)
1005
pwd_valid = check_password(password, settings.ADMIN_PASSWORD)
1006
if login_valid and pwd_valid:
1008
user = User.objects.get(username=username)
1009
except User.DoesNotExist:
1010
# Create a new user. Note that we can set password
1011
# to anything, because it won't be checked; the password
1012
# from settings.py will.
1013
user = User(username=username, password='get from settings.py')
1014
user.is_staff = True
1015
user.is_superuser = True
1020
def get_user(self, user_id):
1022
return User.objects.get(pk=user_id)
1023
except User.DoesNotExist:
added
removed
docs/authentication.txt
