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 * ``set_unusable_password()`` -- **New in Django development version.**
118 Marks the user as having no password set. This isn't the same as having
119 a blank string for a password. ``check_password()`` for this user will
120 never return ``True``. Doesn't save the ``User`` object.
122 You may need this if authentication for your application takes place
123 against an existing external source such as an LDAP directory.
125 * ``has_usable_password()`` -- **New in Django development version.**
126 Returns ``False`` if ``set_unusable_password()`` has been called for this
129 * ``get_group_permissions()`` -- Returns a list of permission strings that
130 the user has, through his/her groups.
132 * ``get_all_permissions()`` -- Returns a list of permission strings that
133 the user has, both through group and user permissions.
135 * ``has_perm(perm)`` -- Returns ``True`` if the user has the specified
136 permission, where perm is in the format ``"package.codename"``.
137 If the user is inactive, this method will always return ``False``.
139 * ``has_perms(perm_list)`` -- Returns ``True`` if the user has each of the
140 specified permissions, where each perm is in the format
141 ``"package.codename"``. If the user is inactive, this method will
142 always return ``False``.
144 * ``has_module_perms(package_name)`` -- Returns ``True`` if the user has
145 any permissions in the given package (the Django app label).
146 If the user is inactive, this method will always return ``False``.
148 * ``get_and_delete_messages()`` -- Returns a list of ``Message`` objects in
149 the user's queue and deletes the messages from the queue.
151 * ``email_user(subject, message, from_email=None)`` -- Sends an e-mail to
152 the user. If ``from_email`` is ``None``, Django uses the
153 `DEFAULT_FROM_EMAIL`_ setting.
155 * ``get_profile()`` -- Returns a site-specific profile for this user.
156 Raises ``django.contrib.auth.models.SiteProfileNotAvailable`` if the current site
157 doesn't allow profiles. For information on how to define a
158 site-specific user profile, see the section on `storing additional
159 user information`_ below.
161 .. _Django model: ../model-api/
162 .. _DEFAULT_FROM_EMAIL: ../settings/#default-from-email
163 .. _storing additional user information: #storing-additional-information-about-users
168 The ``User`` model has a custom manager that has the following helper functions:
170 * ``create_user(username, email, password=None)`` -- Creates, saves and
171 returns a ``User``. The ``username``, ``email`` and ``password`` are set
172 as given, and the ``User`` gets ``is_active=True``.
174 If no password is provided, ``set_unusable_password()`` will be called.
176 See `Creating users`_ for example usage.
178 * ``make_random_password(length=10, allowed_chars='abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789')``
179 Returns a random password with the given length and given string of
180 allowed characters. (Note that the default value of ``allowed_chars``
181 doesn't contain letters that can cause user confusion, including
182 ``1``, ``I`` and ``0``).
190 The most basic way to create users is to use the ``create_user`` helper
191 function that comes with Django::
193 >>> from django.contrib.auth.models import User
194 >>> user = User.objects.create_user('john', 'lennon@thebeatles.com', 'johnpassword')
196 # At this point, user is a User object that has already been saved
197 # to the database. You can continue to change its attributes
198 # if you want to change other fields.
199 >>> user.is_staff = True
205 Change a password with ``set_password()``::
207 >>> from django.contrib.auth.models import User
208 >>> u = User.objects.get(username__exact='john')
209 >>> u.set_password('new password')
212 Don't set the ``password`` attribute directly unless you know what you're
213 doing. This is explained in the next section.
218 The ``password`` attribute of a ``User`` object is a string in this format::
222 That's hashtype, salt and hash, separated by the dollar-sign character.
224 Hashtype is either ``sha1`` (default), ``md5`` or ``crypt`` -- the algorithm
225 used to perform a one-way hash of the password. Salt is a random string used
226 to salt the raw password to create the hash. Note that the ``crypt`` method is
227 only supported on platforms that have the standard Python ``crypt`` module
228 available, and ``crypt`` support is only available in the Django development
233 sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4
235 The ``User.set_password()`` and ``User.check_password()`` functions handle
236 the setting and checking of these values behind the scenes.
238 Previous Django versions, such as 0.90, used simple MD5 hashes without password
239 salts. For backwards compatibility, those are still supported; they'll be
240 converted automatically to the new style the first time ``User.check_password()``
241 works correctly for a given user.
246 ``django.contrib.auth.models.AnonymousUser`` is a class that implements
247 the ``django.contrib.auth.models.User`` interface, with these differences:
249 * ``id`` is always ``None``.
250 * ``is_staff`` and ``is_superuser`` are always ``False``.
251 * ``is_active`` is always ``False``.
252 * ``groups`` and ``user_permissions`` are always empty.
253 * ``is_anonymous()`` returns ``True`` instead of ``False``.
254 * ``is_authenticated()`` returns ``False`` instead of ``True``.
255 * ``has_perm()`` always returns ``False``.
256 * ``set_password()``, ``check_password()``, ``save()``, ``delete()``,
257 ``set_groups()`` and ``set_permissions()`` raise ``NotImplementedError``.
259 In practice, you probably won't need to use ``AnonymousUser`` objects on your
260 own, but they're used by Web requests, as explained in the next section.
265 ``manage.py syncdb`` prompts you to create a superuser the first time you run
266 it after adding ``'django.contrib.auth'`` to your ``INSTALLED_APPS``. If you need
267 to create a superuser at a later date, you can use a command line utility.
269 **New in Django development version.**::
271 manage.py createsuperuser --username=joe --email=joe@example.com
273 You will be prompted for a password. After you enter one, the user will be
274 created immediately. If you leave off the ``--username`` or the ``--email``
275 options, it will prompt you for those values.
277 If you're using an older release of Django, the old way of creating a superuser
278 on the command line still works::
280 python /path/to/django/contrib/auth/create_superuser.py
282 ...where ``/path/to`` is the path to the Django codebase on your filesystem. The
283 ``manage.py`` command is preferred because it figures out the correct path and
286 Storing additional information about users
287 ------------------------------------------
289 If you'd like to store additional information related to your users,
290 Django provides a method to specify a site-specific related model --
291 termed a "user profile" -- for this purpose.
293 To make use of this feature, define a model with fields for the
294 additional information you'd like to store, or additional methods
295 you'd like to have available, and also add a ``ForeignKey`` from your
296 model to the ``User`` model, specified with ``unique=True`` to ensure
297 only one instance of your model can be created for each ``User``.
299 To indicate that this model is the user profile model for a given
300 site, fill in the setting ``AUTH_PROFILE_MODULE`` with a string
301 consisting of the following items, separated by a dot:
303 1. The (normalized to lower-case) name of the application in which the
304 user profile model is defined (in other words, an all-lowercase
305 version of the name which was passed to ``manage.py startapp`` to
306 create the application).
308 2. The (normalized to lower-case) name of the model class.
310 For example, if the profile model was a class named ``UserProfile``
311 and was defined inside an application named ``accounts``, the
312 appropriate setting would be::
314 AUTH_PROFILE_MODULE = 'accounts.userprofile'
316 When a user profile model has been defined and specified in this
317 manner, each ``User`` object will have a method -- ``get_profile()``
318 -- which returns the instance of the user profile model associated
321 For more information, see `Chapter 12 of the Django book`_.
323 .. _Chapter 12 of the Django book: http://www.djangobook.com/en/1.0/chapter12/#cn222
325 Authentication in Web requests
326 ==============================
328 Until now, this document has dealt with the low-level APIs for manipulating
329 authentication-related objects. On a higher level, Django can hook this
330 authentication framework into its system of `request objects`_.
332 First, install the ``SessionMiddleware`` and ``AuthenticationMiddleware``
333 middlewares by adding them to your ``MIDDLEWARE_CLASSES`` setting. See the
334 `session documentation`_ for more information.
336 Once you have those middlewares installed, you'll be able to access
337 ``request.user`` in views. ``request.user`` will give you a ``User`` object
338 representing the currently logged-in user. If a user isn't currently logged in,
339 ``request.user`` will be set to an instance of ``AnonymousUser`` (see the
340 previous section). You can tell them apart with ``is_authenticated()``, like so::
342 if request.user.is_authenticated():
343 # Do something for authenticated users.
345 # Do something for anonymous users.
347 .. _request objects: ../request_response/#httprequest-objects
348 .. _session documentation: ../sessions/
353 Django provides two functions in ``django.contrib.auth``: ``authenticate()``
356 To authenticate a given username and password, use ``authenticate()``. It
357 takes two keyword arguments, ``username`` and ``password``, and it returns
358 a ``User`` object if the password is valid for the given username. If the
359 password is invalid, ``authenticate()`` returns ``None``. Example::
361 from django.contrib.auth import authenticate
362 user = authenticate(username='john', password='secret')
365 print "You provided a correct username and password!"
367 print "Your account has been disabled!"
369 print "Your username and password were incorrect."
371 To log a user in, in a view, use ``login()``. It takes an ``HttpRequest``
372 object and a ``User`` object. ``login()`` saves the user's ID in the session,
373 using Django's session framework, so, as mentioned above, you'll need to make
374 sure to have the session middleware installed.
376 This example shows how you might use both ``authenticate()`` and ``login()``::
378 from django.contrib.auth import authenticate, login
380 def my_view(request):
381 username = request.POST['username']
382 password = request.POST['password']
383 user = authenticate(username=username, password=password)
387 # Redirect to a success page.
389 # Return a 'disabled account' error message
391 # Return an 'invalid login' error message.
393 .. admonition:: Calling ``authenticate()`` first
395 When you're manually logging a user in, you *must* call
396 ``authenticate()`` before you call ``login()``. ``authenticate()``
397 sets an attribute on the ``User`` noting which authentication
398 backend successfully authenticated that user (see the `backends
399 documentation`_ for details), and this information is needed later
400 during the login process.
402 .. _backends documentation: #other-authentication-sources
404 Manually checking a user's password
405 -----------------------------------
407 If you'd like to manually authenticate a user by comparing a
408 plain-text password to the hashed password in the database, use the
409 convenience function ``django.contrib.auth.models.check_password``. It
410 takes two arguments: the plain-text password to check, and the full
411 value of a user's ``password`` field in the database to check against,
412 and returns ``True`` if they match, ``False`` otherwise.
414 How to log a user out
415 ---------------------
417 To log out a user who has been logged in via ``django.contrib.auth.login()``,
418 use ``django.contrib.auth.logout()`` within your view. It takes an
419 ``HttpRequest`` object and has no return value. Example::
421 from django.contrib.auth import logout
423 def logout_view(request):
425 # Redirect to a success page.
427 Note that ``logout()`` doesn't throw any errors if the user wasn't logged in.
429 **New in Django development version:** When you call ``logout()``, the session
430 data for the current request is completely cleaned out. All existing data is
431 removed. This is to prevent another person from using the same web browser to
432 log in and have access to the previous user's session data. If you want to put
433 anything into the session that will be available to the user immediately after
434 logging out, do that *after* calling ``django.contrib.auth.logout()``.
436 Limiting access to logged-in users
437 ----------------------------------
442 The simple, raw way to limit access to pages is to check
443 ``request.user.is_authenticated()`` and either redirect to a login page::
445 from django.http import HttpResponseRedirect
447 def my_view(request):
448 if not request.user.is_authenticated():
449 return HttpResponseRedirect('/login/?next=%s' % request.path)
452 ...or display an error message::
454 def my_view(request):
455 if not request.user.is_authenticated():
456 return render_to_response('myapp/login_error.html')
459 The login_required decorator
460 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
462 As a shortcut, you can use the convenient ``login_required`` decorator::
464 from django.contrib.auth.decorators import login_required
466 def my_view(request):
468 my_view = login_required(my_view)
470 Here's an equivalent example, using the more compact decorator syntax
471 introduced in Python 2.4::
473 from django.contrib.auth.decorators import login_required
476 def my_view(request):
479 In the Django development version, ``login_required`` also takes an optional
480 ``redirect_field_name`` parameter. Example::
482 from django.contrib.auth.decorators import login_required
484 def my_view(request):
486 my_view = login_required(redirect_field_name='redirect_to')(my_view)
488 Again, an equivalent example of the more compact decorator syntax introduced in Python 2.4::
490 from django.contrib.auth.decorators import login_required
492 @login_required(redirect_field_name='redirect_to')
493 def my_view(request):
496 ``login_required`` does the following:
498 * If the user isn't logged in, redirect to ``settings.LOGIN_URL``
499 (``/accounts/login/`` by default), passing the current absolute URL
500 in the query string as ``next`` or the value of ``redirect_field_name``.
502 ``/accounts/login/?next=/polls/3/``.
503 * If the user is logged in, execute the view normally. The view code is
504 free to assume the user is logged in.
506 Note that you'll need to map the appropriate Django view to ``settings.LOGIN_URL``.
507 For example, using the defaults, add the following line to your URLconf::
509 (r'^accounts/login/$', 'django.contrib.auth.views.login'),
511 Here's what ``django.contrib.auth.views.login`` does:
513 * If called via ``GET``, it displays a login form that POSTs to the same
514 URL. More on this in a bit.
516 * If called via ``POST``, it tries to log the user in. If login is
517 successful, the view redirects to the URL specified in ``next``. If
518 ``next`` isn't provided, it redirects to ``settings.LOGIN_REDIRECT_URL``
519 (which defaults to ``/accounts/profile/``). If login isn't successful,
520 it redisplays the login form.
522 It's your responsibility to provide the login form in a template called
523 ``registration/login.html`` by default. This template gets passed three
524 template context variables:
526 * ``form``: A ``Form`` object representing the login form. See the
527 `forms documentation`_ for more on ``FormWrapper`` objects.
528 * ``next``: The URL to redirect to after successful login. This may contain
530 * ``site_name``: The name of the current ``Site``, according to the
531 ``SITE_ID`` setting. If you're using the Django development version and
532 you don't have the site framework installed, this will be set to the
533 value of ``request.META['SERVER_NAME']``. For more on sites, see the
534 `site framework docs`_.
536 If you'd prefer not to call the template ``registration/login.html``, you can
537 pass the ``template_name`` parameter via the extra arguments to the view in
538 your URLconf. For example, this URLconf line would use ``myapp/login.html``
541 (r'^accounts/login/$', 'django.contrib.auth.views.login', {'template_name': 'myapp/login.html'}),
543 Here's a sample ``registration/login.html`` template you can use as a starting
544 point. It assumes you have a ``base.html`` template that defines a ``content``
547 {% extends "base.html" %}
552 <p>Your username and password didn't match. Please try again.</p>
555 <form method="post" action=".">
557 <tr><td>{{ form.username.label_tag }}</td><td>{{ form.username }}</td></tr>
558 <tr><td>{{ form.password.label_tag }}</td><td>{{ form.password }}</td></tr>
561 <input type="submit" value="login" />
562 <input type="hidden" name="next" value="{{ next }}" />
567 .. _forms documentation: ../forms/
568 .. _site framework docs: ../sites/
573 In addition to the ``login`` view, the authentication system includes a
574 few other useful built-in views:
576 ``django.contrib.auth.views.logout``
577 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
583 **Optional arguments:**
585 * ``template_name``: The full name of a template to display after
586 logging the user out. This will default to
587 ``registration/logged_out.html`` if no argument is supplied.
589 **Template context:**
591 * ``title``: The string "Logged out", localized.
593 ``django.contrib.auth.views.logout_then_login``
594 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
598 Logs a user out, then redirects to the login page.
600 **Optional arguments:**
602 * ``login_url``: The URL of the login page to redirect to. This
603 will default to ``settings.LOGIN_URL`` if not supplied.
605 ``django.contrib.auth.views.password_change``
606 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
610 Allows a user to change their password.
612 **Optional arguments:**
614 * ``template_name``: The full name of a template to use for
615 displaying the password change form. This will default to
616 ``registration/password_change_form.html`` if not supplied.
618 **Template context:**
620 * ``form``: The password change form.
622 ``django.contrib.auth.views.password_change_done``
623 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
627 The page shown after a user has changed their password.
629 **Optional arguments:**
631 * ``template_name``: The full name of a template to use. This will
632 default to ``registration/password_change_done.html`` if not
635 ``django.contrib.auth.views.password_reset``
636 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
640 Allows a user to reset their password, and sends them the new password
643 **Optional arguments:**
645 * ``template_name``: The full name of a template to use for
646 displaying the password reset form. This will default to
647 ``registration/password_reset_form.html`` if not supplied.
649 * ``email_template_name``: The full name of a template to use for
650 generating the e-mail with the new password. This will default to
651 ``registration/password_reset_email.html`` if not supplied.
653 **Template context:**
655 * ``form``: The form for resetting the user's password.
657 ``django.contrib.auth.views.password_reset_done``
658 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
662 The page shown after a user has reset their password.
664 **Optional arguments:**
666 * ``template_name``: The full name of a template to use. This will
667 default to ``registration/password_reset_done.html`` if not
670 ``django.contrib.auth.views.redirect_to_login``
671 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
675 Redirects to the login page, and then back to another URL after a
678 **Required arguments:**
680 * ``next``: The URL to redirect to after a successful login.
682 **Optional arguments:**
684 * ``login_url``: The URL of the login page to redirect to. This
685 will default to ``settings.LOGIN_URL`` if not supplied.
690 **New in Django development version.**
692 If you don't want to use the built-in views, but want the convenience
693 of not having to write forms for this functionality, the authentication
694 system provides several built-in forms:
696 * ``django.contrib.auth.forms.AdminPasswordChangeForm``: A form used in
697 the admin interface to change a user's password.
699 * ``django.contrib.auth.forms.AuthenticationForm``: A form for logging a
702 * ``django.contrib.auth.forms.PasswordChangeForm``: A form for allowing a
703 user to change their password.
705 * ``django.contrib.auth.forms.PasswordResetForm``: A form for resetting a
706 user's password and e-mailing the new password to them.
708 * ``django.contrib.auth.forms.UserCreationForm``: A form for creating a
711 Limiting access to logged-in users that pass a test
712 ---------------------------------------------------
714 To limit access based on certain permissions or some other test, you'd do
715 essentially the same thing as described in the previous section.
717 The simple way is to run your test on ``request.user`` in the view directly.
718 For example, this view checks to make sure the user is logged in and has the
719 permission ``polls.can_vote``::
721 def my_view(request):
722 if not (request.user.is_authenticated() and request.user.has_perm('polls.can_vote')):
723 return HttpResponse("You can't vote in this poll.")
726 As a shortcut, you can use the convenient ``user_passes_test`` decorator::
728 from django.contrib.auth.decorators import user_passes_test
730 def my_view(request):
732 my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'))(my_view)
734 We're using this particular test as a relatively simple example. However, if
735 you just want to test whether a permission is available to a user, you can use
736 the ``permission_required()`` decorator, described later in this document.
738 Here's the same thing, using Python 2.4's decorator syntax::
740 from django.contrib.auth.decorators import user_passes_test
742 @user_passes_test(lambda u: u.has_perm('polls.can_vote'))
743 def my_view(request):
746 ``user_passes_test`` takes a required argument: a callable that takes a
747 ``User`` object and returns ``True`` if the user is allowed to view the page.
748 Note that ``user_passes_test`` does not automatically check that the ``User``
751 ``user_passes_test()`` takes an optional ``login_url`` argument, which lets you
752 specify the URL for your login page (``settings.LOGIN_URL`` by default).
754 Example in Python 2.3 syntax::
756 from django.contrib.auth.decorators import user_passes_test
758 def my_view(request):
760 my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'), login_url='/login/')(my_view)
762 Example in Python 2.4 syntax::
764 from django.contrib.auth.decorators import user_passes_test
766 @user_passes_test(lambda u: u.has_perm('polls.can_vote'), login_url='/login/')
767 def my_view(request):
770 The permission_required decorator
771 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
773 It's a relatively common task to check whether a user has a particular
774 permission. For that reason, Django provides a shortcut for that case: the
775 ``permission_required()`` decorator. Using this decorator, the earlier example
778 from django.contrib.auth.decorators import permission_required
780 def my_view(request):
782 my_view = permission_required('polls.can_vote')(my_view)
784 Note that ``permission_required()`` also takes an optional ``login_url``
787 from django.contrib.auth.decorators import permission_required
789 def my_view(request):
791 my_view = permission_required('polls.can_vote', login_url='/loginpage/')(my_view)
793 As in the ``login_required`` decorator, ``login_url`` defaults to
794 ``settings.LOGIN_URL``.
796 Limiting access to generic views
797 --------------------------------
799 To limit access to a `generic view`_, write a thin wrapper around the view,
800 and point your URLconf to your wrapper instead of the generic view itself.
803 from django.views.generic.date_based import object_detail
806 def limited_object_detail(*args, **kwargs):
807 return object_detail(*args, **kwargs)
809 .. _generic view: ../generic_views/
814 Django comes with a simple permissions system. It provides a way to assign
815 permissions to specific users and groups of users.
817 It's used by the Django admin site, but you're welcome to use it in your own
820 The Django admin site uses permissions as follows:
822 * Access to view the "add" form and add an object is limited to users with
823 the "add" permission for that type of object.
824 * Access to view the change list, view the "change" form and change an
825 object is limited to users with the "change" permission for that type of
827 * Access to delete an object is limited to users with the "delete"
828 permission for that type of object.
830 Permissions are set globally per type of object, not per specific object
831 instance. For example, it's possible to say "Mary may change news stories," but
832 it's not currently possible to say "Mary may change news stories, but only the
833 ones she created herself" or "Mary may only change news stories that have a
834 certain status, publication date or ID." The latter functionality is something
835 Django developers are currently discussing.
840 When ``django.contrib.auth`` is listed in your ``INSTALLED_APPS``
841 setting, it will ensure that three default permissions -- add, change
842 and delete -- are created for each Django model defined in one of your
843 installed applications.
845 These permissions will be created when you run ``manage.py syncdb``;
846 the first time you run ``syncdb`` after adding ``django.contrib.auth``
847 to ``INSTALLED_APPS``, the default permissions will be created for all
848 previously-installed models, as well as for any new models being
849 installed at that time. Afterward, it will create default permissions
850 for new models each time you run ``manage.py syncdb``.
855 To create custom permissions for a given model object, use the ``permissions``
856 `model Meta attribute`_.
858 This example model creates three custom permissions::
860 class USCitizen(models.Model):
864 ("can_drive", "Can drive"),
865 ("can_vote", "Can vote in elections"),
866 ("can_drink", "Can drink alcohol"),
869 The only thing this does is create those extra permissions when you run
872 .. _model Meta attribute: ../model-api/#meta-options
877 Just like users, permissions are implemented in a Django model that lives in
878 `django/contrib/auth/models.py`_.
880 .. _django/contrib/auth/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/models.py
885 ``Permission`` objects have the following fields:
887 * ``name`` -- Required. 50 characters or fewer. Example: ``'Can vote'``.
888 * ``content_type`` -- Required. A reference to the ``django_content_type``
889 database table, which contains a record for each installed Django model.
890 * ``codename`` -- Required. 100 characters or fewer. Example: ``'can_vote'``.
895 ``Permission`` objects have the standard data-access methods like any other
898 Authentication data in templates
899 ================================
901 The currently logged-in user and his/her permissions are made available in the
902 `template context`_ when you use ``RequestContext``.
904 .. admonition:: Technicality
906 Technically, these variables are only made available in the template context
907 if you use ``RequestContext`` *and* your ``TEMPLATE_CONTEXT_PROCESSORS``
908 setting contains ``"django.core.context_processors.auth"``, which is default.
909 For more, see the `RequestContext docs`_.
911 .. _RequestContext docs: ../templates_python/#subclassing-context-requestcontext
916 The currently logged-in user, either a ``User`` instance or an``AnonymousUser``
917 instance, is stored in the template variable ``{{ user }}``::
919 {% if user.is_authenticated %}
920 <p>Welcome, {{ user.username }}. Thanks for logging in.</p>
922 <p>Welcome, new user. Please log in.</p>
928 The currently logged-in user's permissions are stored in the template variable
929 ``{{ perms }}``. This is an instance of ``django.core.context_processors.PermWrapper``,
930 which is a template-friendly proxy of permissions.
932 In the ``{{ perms }}`` object, single-attribute lookup is a proxy to
933 ``User.has_module_perms``. This example would display ``True`` if the logged-in
934 user had any permissions in the ``foo`` app::
938 Two-level-attribute lookup is a proxy to ``User.has_perm``. This example would
939 display ``True`` if the logged-in user had the permission ``foo.can_vote``::
941 {{ perms.foo.can_vote }}
943 Thus, you can check permissions in template ``{% if %}`` statements::
946 <p>You have permission to do something in the foo app.</p>
947 {% if perms.foo.can_vote %}
950 {% if perms.foo.can_drive %}
951 <p>You can drive!</p>
954 <p>You don't have permission to do anything in the foo app.</p>
957 .. _template context: ../templates_python/
962 Groups are a generic way of categorizing users so you can apply permissions, or
963 some other label, to those users. A user can belong to any number of groups.
965 A user in a group automatically has the permissions granted to that group. For
966 example, if the group ``Site editors`` has the permission
967 ``can_edit_home_page``, any user in that group will have that permission.
969 Beyond permissions, groups are a convenient way to categorize users to give
970 them some label, or extended functionality. For example, you could create a
971 group ``'Special users'``, and you could write code that could, say, give them
972 access to a members-only portion of your site, or send them members-only e-mail
978 The message system is a lightweight way to queue messages for given users.
980 A message is associated with a ``User``. There's no concept of expiration or
983 Messages are used by the Django admin after successful actions. For example,
984 ``"The poll Foo was created successfully."`` is a message.
988 * To create a new message, use
989 ``user_obj.message_set.create(message='message_text')``.
990 * To retrieve/delete messages, use ``user_obj.get_and_delete_messages()``,
991 which returns a list of ``Message`` objects in the user's queue (if any)
992 and deletes the messages from the queue.
994 In this example view, the system saves a message for the user after creating
997 def create_playlist(request, songs):
998 # Create the playlist with the given songs.
1000 request.user.message_set.create(message="Your playlist was added successfully.")
1001 return render_to_response("playlists/create.html",
1002 context_instance=RequestContext(request))
1004 When you use ``RequestContext``, the currently logged-in user and his/her
1005 messages are made available in the `template context`_ as the template variable
1006 ``{{ messages }}``. Here's an example of template code that displays messages::
1010 {% for message in messages %}
1011 <li>{{ message }}</li>
1016 Note that ``RequestContext`` calls ``get_and_delete_messages`` behind the
1017 scenes, so any messages will be deleted even if you don't display them.
1019 Finally, note that this messages framework only works with users in the user
1020 database. To send messages to anonymous users, use the `session framework`_.
1022 .. _session framework: ../sessions/
1024 Other authentication sources
1025 ============================
1027 The authentication that comes with Django is good enough for most common cases,
1028 but you may have the need to hook into another authentication source -- that
1029 is, another source of usernames and passwords or authentication methods.
1031 For example, your company may already have an LDAP setup that stores a username
1032 and password for every employee. It'd be a hassle for both the network
1033 administrator and the users themselves if users had separate accounts in LDAP
1034 and the Django-based applications.
1036 So, to handle situations like this, the Django authentication system lets you
1037 plug in another authentication sources. You can override Django's default
1038 database-based scheme, or you can use the default system in tandem with other
1041 Specifying authentication backends
1042 ----------------------------------
1044 Behind the scenes, Django maintains a list of "authentication backends" that it
1045 checks for authentication. When somebody calls
1046 ``django.contrib.auth.authenticate()`` -- as described in "How to log a user in"
1047 above -- Django tries authenticating across all of its authentication backends.
1048 If the first authentication method fails, Django tries the second one, and so
1049 on, until all backends have been attempted.
1051 The list of authentication backends to use is specified in the
1052 ``AUTHENTICATION_BACKENDS`` setting. This should be a tuple of Python path
1053 names that point to Python classes that know how to authenticate. These classes
1054 can be anywhere on your Python path.
1056 By default, ``AUTHENTICATION_BACKENDS`` is set to::
1058 ('django.contrib.auth.backends.ModelBackend',)
1060 That's the basic authentication scheme that checks the Django users database.
1062 The order of ``AUTHENTICATION_BACKENDS`` matters, so if the same username and
1063 password is valid in multiple backends, Django will stop processing at the
1064 first positive match.
1066 Writing an authentication backend
1067 ---------------------------------
1069 An authentication backend is a class that implements two methods:
1070 ``get_user(user_id)`` and ``authenticate(**credentials)``.
1072 The ``get_user`` method takes a ``user_id`` -- which could be a username,
1073 database ID or whatever -- and returns a ``User`` object.
1075 The ``authenticate`` method takes credentials as keyword arguments. Most of
1076 the time, it'll just look like this::
1079 def authenticate(self, username=None, password=None):
1080 # Check the username/password and return a User.
1082 But it could also authenticate a token, like so::
1085 def authenticate(self, token=None):
1086 # Check the token and return a User.
1088 Either way, ``authenticate`` should check the credentials it gets, and it
1089 should return a ``User`` object that matches those credentials, if the
1090 credentials are valid. If they're not valid, it should return ``None``.
1092 The Django admin system is tightly coupled to the Django ``User`` object
1093 described at the beginning of this document. For now, the best way to deal with
1094 this is to create a Django ``User`` object for each user that exists for your
1095 backend (e.g., in your LDAP directory, your external SQL database, etc.) You
1096 can either write a script to do this in advance, or your ``authenticate``
1097 method can do it the first time a user logs in.
1099 Here's an example backend that authenticates against a username and password
1100 variable defined in your ``settings.py`` file and creates a Django ``User``
1101 object the first time a user authenticates::
1103 from django.conf import settings
1104 from django.contrib.auth.models import User, check_password
1106 class SettingsBackend:
1108 Authenticate against the settings ADMIN_LOGIN and ADMIN_PASSWORD.
1110 Use the login name, and a hash of the password. For example:
1112 ADMIN_LOGIN = 'admin'
1113 ADMIN_PASSWORD = 'sha1$4e987$afbcf42e21bd417fb71db8c66b321e9fc33051de'
1115 def authenticate(self, username=None, password=None):
1116 login_valid = (settings.ADMIN_LOGIN == username)
1117 pwd_valid = check_password(password, settings.ADMIN_PASSWORD)
1118 if login_valid and pwd_valid:
1120 user = User.objects.get(username=username)
1121 except User.DoesNotExist:
1122 # Create a new user. Note that we can set password
1123 # to anything, because it won't be checked; the password
1124 # from settings.py will.
1125 user = User(username=username, password='get from settings.py')
1126 user.is_staff = True
1127 user.is_superuser = True
1132 def get_user(self, user_id):
1134 return User.objects.get(pk=user_id)
1135 except User.DoesNotExist:
1138 Handling authorization in custom backends
1139 -----------------------------------------
1141 Custom auth backends can provide their own permissions.
1143 The user model will delegate permission lookup functions
1144 (``get_group_permissions()``, ``get_all_permissions()``, ``has_perm()``, and
1145 ``has_module_perms()``) to any authentication backend that implements these
1148 The permissions given to the user will be the superset of all permissions
1149 returned by all backends. That is, Django grants a permission to a user that any
1152 The simple backend above could implement permissions for the magic admin fairly
1155 class SettingsBackend:
1159 def has_perm(self, user_obj, perm):
1160 if user_obj.username == settings.ADMIN_LOGIN:
1165 This gives full permissions to the user granted access in the above example. Notice
1166 that the backend auth functions all take the user object as an argument, and
1167 they also accept the same arguments given to the associated ``User`` functions.
1169 A full authorization implementation can be found in
1170 ``django/contrib/auth/backends.py`` _, which is the default backend and queries
1171 the ``auth_permission`` table most of the time.
1173 .. _django/contrib/auth/backends.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/backends.py