Initial thoughts on a Linkable Model class. Please comment.
Patch by: Todd Larsen
=============================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 howthings work.Overview========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.Installation============Authentication support is bundled as a Django application in``django.contrib.auth``. To install it, do the following: 1. Put ``'django.contrib.auth'`` in your ``INSTALLED_APPS`` setting. 2. Run the command ``manage.py syncdb``.Note that the default ``settings.py`` file created by``django-admin.py startproject`` includes ``'django.contrib.auth'`` in``INSTALLED_APPS`` for convenience. If your ``INSTALLED_APPS`` already contains``'django.contrib.auth'``, feel free to run ``manage.py syncdb`` again; youcan run that command as many times as you'd like, and each time it'll onlyinstall what's needed.The ``syncdb`` command creates the necessary database tables, createspermission objects for all installed apps that need 'em, and prompts you tocreate a superuser account the first time you run it.Once you've taken those steps, that's it.Users=====Users are represented by a standard Django model, which lives in`django/contrib/auth/models.py`_... _django/contrib/auth/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/models.pyAPI 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 account can be used to log in. Set this flag 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``. ``User`` objects can access their relatedobjects in the same way as any other `Django model`_:: myuser.groups = [group_list] myuser.groups.add(group, group,...) myuser.groups.remove(group, group,...) myuser.groups.clear() myuser.user_permissions = [permission_list] myuser.user_permissions.add(permission, permission, ...) myuser.user_permissions.remove(permission, permission, ...] myuser.user_permissions.clear()In addition to those automatic API methods, ``User`` objects have the followingcustom methods: * ``is_anonymous()`` -- Always returns ``False``. This is a way of differentiating ``User`` and ``AnonymousUser`` objects. Generally, you should prefer using ``is_authenticated()`` to this method. * ``is_authenticated()`` -- Always returns ``True``. This is a way to tell if the user has been authenticated. This does not imply any permissions, and doesn't check if the user is active - it only indicates that the user has provided a valid username and password. * ``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 password 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. (This takes care of the password hashing in making the comparison.) * ``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"``. If the user is inactive, this method will always return ``False``. * ``has_perms(perm_list)`` -- Returns ``True`` if the user has each of the specified permissions, where each perm is in the format ``"package.codename"``. If the user is inactive, this method will always return ``False``. * ``has_module_perms(package_name)`` -- Returns ``True`` if the user has any permissions in the given package (the Django app label). If the user is inactive, this method will always return ``False``. * ``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.contrib.auth.models.SiteProfileNotAvailable`` if the current site doesn't allow profiles... _Django model: ../model_api/.. _DEFAULT_FROM_EMAIL: ../settings/#default-from-emailManager functions~~~~~~~~~~~~~~~~~The ``User`` model has a custom manager that 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``. See _`Creating users` for example usage. * ``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`` helperfunction that comes with Django:: >>> from django.contrib.auth.models import User >>> user = User.objects.create_user('john', 'lennon@thebeatles.com', 'johnpassword') # At this point, user is a User object ready to be 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.contrib.auth.models import User >>> u = User.objects.get(username__exact='john') >>> u.set_password('new password') >>> u.save()Don't set the ``password`` attribute directly unless you know what you'redoing. This is explained in the next section.Passwords---------The ``password`` attribute of a ``User`` object is a string in this format:: hashtype$salt$hashThat's hashtype, salt and hash, separated by the dollar-sign character.Hashtype is either ``sha1`` (default) or ``md5`` -- the algorithm used toperform a one-way hash of the password. Salt is a random string used to saltthe raw password to create the hash.For example:: sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4The ``User.set_password()`` and ``User.check_password()`` functions handlethe setting and checking of these values behind the scenes.Previous Django versions, such as 0.90, used simple MD5 hashes without passwordsalts. For backwards compatibility, those are still supported; they'll beconverted automatically to the new style the first time ``check_password()``works correctly for a given user.Anonymous users---------------``django.contrib.auth.models.AnonymousUser`` is a class that implementsthe ``django.contrib.auth.models.User`` interface, with these differences: * ``id`` is always ``None``. * ``is_anonymous()`` returns ``True`` instead of ``False``. * ``is_authenticated()`` returns ``False`` instead of ``True``. * ``has_perm()`` always returns ``False``. * ``set_password()``, ``check_password()``, ``save()``, ``delete()``, ``set_groups()`` and ``set_permissions()`` raise ``NotImplementedError``.In practice, you probably won't need to use ``AnonymousUser`` objects on yourown, but they're used by Web requests, as explained in the next section.Creating superusers-------------------``manage.py syncdb`` prompts you to create a superuser the first time you runit after adding ``'django.contrib.auth'`` to your ``INSTALLED_APPS``. But ifyou need to create a superuser after that via the command line, you can use the``create_superuser.py`` utility. Just run this command:: python /path/to/django/contrib/auth/create_superuser.pyMake sure to substitute ``/path/to/`` with the path to the Django codebase onyour filesystem.Authentication in Web requests==============================Until now, this document has dealt with the low-level APIs for manipulatingauthentication-related objects. On a higher level, Django can hook thisauthentication framework into its system of `request objects`_.First, install the ``SessionMiddleware`` and ``AuthenticationMiddleware``middlewares by adding them to your ``MIDDLEWARE_CLASSES`` setting. See the`session documentation`_ for more information.Once you have those middlewares installed, you'll be able to access``request.user`` in views. ``request.user`` will give you a ``User`` objectrepresenting the currently logged-in user. If a user isn't currently logged in,``request.user`` will be set to an instance of ``AnonymousUser`` (see theprevious section). You can tell them apart with ``is_authenticated()``, like so:: if request.user.is_authenticated(): # Do something for authenticated users. else: # Do something for anonymous users... _request objects: ../request_response/#httprequest-objects.. _session documentation: ../sessions/How to log a user in--------------------Django provides two functions in ``django.contrib.auth``: ``authenticate()``and ``login()``.To authenticate a given username and password, use ``authenticate()``. Ittakes two keyword arguments, ``username`` and ``password``, and it returnsa ``User`` object if the password is valid for the given username. If thepassword is invalid, ``authenticate()`` returns ``None``. Example:: from django.contrib.auth import authenticate user = authenticate(username='john', password='secret') if user is not None: if user.is_active: print "You provided a correct username and password!" else: print "Your account has been disabled!" else: print "Your username and password were incorrect."To log a user in, in a view, use ``login()``. It takes an ``HttpRequest``object and a ``User`` object. ``login()`` saves the user's ID in the session,using Django's session framework, so, as mentioned above, you'll need to makesure to have the session middleware installed.This example shows how you might use both ``authenticate()`` and ``login()``:: from django.contrib.auth import authenticate, login def my_view(request): username = request.POST['username'] password = request.POST['password'] user = authenticate(username=username, password=password) if user is not None: if user.is_active: login(request, user) # Redirect to a success page. else: # Return a 'disabled account' error message else: # Return an 'invalid login' error message.Manually checking a user's password-----------------------------------If you'd like to manually authenticate a user by comparing aplain-text password to the hashed password in the database, use theconvenience function `django.contrib.auth.models.check_password`. Ittakes two arguments: the plain-text password to check, and the fullvalue of a user's ``password`` field in the database to check against,and returns ``True`` if they match, ``False`` otherwise.How to log a user out---------------------To log out a user who has been logged in via ``django.contrib.auth.login()``,use ``django.contrib.auth.logout()`` within your view. It takes an``HttpRequest`` object and has no return value. Example:: from django.contrib.auth import logout def logout_view(request): logout(request) # Redirect to a success page.Note that ``logout()`` doesn't throw any errors if the user wasn't logged in.Limiting access to logged-in users----------------------------------The raw way~~~~~~~~~~~The simple, raw way to limit access to pages is to check``request.user.is_authenticated()`` and either redirect to a login page:: from django.http import HttpResponseRedirect def my_view(request): if not request.user.is_authenticated(): return HttpResponseRedirect('/login/?next=%s' % request.path) # ......or display an error message:: def my_view(request): if not request.user.is_authenticated(): return render_to_response('myapp/login_error.html') # ...The login_required decorator~~~~~~~~~~~~~~~~~~~~~~~~~~~~As a shortcut, you can use the convenient ``login_required`` decorator:: from django.contrib.auth.decorators import login_required def my_view(request): # ... my_view = login_required(my_view)Here's an equivalent example, using the more compact decorator syntaxintroduced in Python 2.4:: from django.contrib.auth.decorators 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.Note that you'll need to map the appropriate Django view to ``/accounts/login/``.To do this, add the following line to your URLconf:: (r'^accounts/login/$', 'django.contrib.auth.views.login'),Here's what ``django.contrib.auth.views.login`` does: * If called via ``GET``, it displays a login form that POSTs to the same URL. More on this in a bit. * If called via ``POST``, it tries to log the user in. If login is successful, the view redirects to the URL specified in ``next``. If ``next`` isn't provided, it redirects to ``/accounts/profile/`` (which is currently hard-coded). If login isn't successful, it redisplays the login form.It's your responsibility to provide the login form in a template called``registration/login.html`` by default. This template gets passed threetemplate context variables: * ``form``: A ``FormWrapper`` object representing the login form. See the `forms documentation`_ for more on ``FormWrapper`` objects. * ``next``: The URL to redirect to after successful login. This may contain a query string, too. * ``site_name``: The name of the current ``Site``, according to the ``SITE_ID`` setting. See the `site framework docs`_.If you'd prefer not to call the template ``registration/login.html``, you canpass the ``template_name`` parameter via the extra arguments to the view inyour URLconf. For example, this URLconf line would use ``myapp/login.html``instead:: (r'^accounts/login/$', 'django.contrib.auth.views.login', {'template_name': 'myapp/login.html'}),Here's a sample ``registration/login.html`` template you can use as a startingpoint. It assumes you have a ``base.html`` template that defines a ``content``block:: {% extends "base.html" %} {% block content %} {% if form.has_errors %} <p>Your username and password didn't match. Please try again.</p> {% endif %} <form method="post" action="."> <table> <tr><td><label for="id_username">Username:</label></td><td>{{ form.username }}</td></tr> <tr><td><label for="id_password">Password:</label></td><td>{{ form.password }}</td></tr> </table> <input type="submit" value="login" /> <input type="hidden" name="next" value="{{ next }}" /> </form> {% endblock %}.. _forms documentation: ../forms/.. _site framework docs: ../sites/Other built-in views--------------------In addition to the `login` view, the authentication system includes afew other useful built-in views:``django.contrib.auth.views.logout``~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~**Description:**Logs a user out.**Optional arguments:** * ``template_name``: The full name of a template to display after logging the user out. This will default to ``registration/logged_out.html`` if no argument is supplied.**Template context:** * ``title``: The string "Logged out", localized.``django.contrib.auth.views.logout_then_login``~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~**Description:**Logs a user out, then redirects to the login page.**Optional arguments:** * ``login_url``: The URL of the login page to redirect to. This will default to ``/accounts/login/`` if not supplied.``django.contrib.auth.views.password_change``~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~**Description:**Allows a user to change their password.**Optional arguments:** * ``template_name``: The full name of a template to use for displaying the password change form. This will default to ``registration/password_change_form.html`` if not supplied.**Template context:** * ``form``: The password change form.``django.contrib.auth.views.password_change_done``~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~**Description:**The page shown after a user has changed their password.**Optional arguments:** * ``template_name``: The full name of a template to use. This will default to ``registration/password_change_done.html`` if not supplied.``django.contrib.auth.views.password_reset``~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~**Description:**Allows a user to reset their password, and sends them the new passwordin an email.**Optional arguments:** * ``template_name``: The full name of a template to use for displaying the password reset form. This will default to ``registration/password_reset_form.html`` if not supplied. * ``email_template_name``: The full name of a template to use for generating the email with the new password. This will default to ``registration/password_reset_email.html`` if not supplied.**Template context:** * ``form``: The form for resetting the user's password.``django.contrib.auth.views.password_reset_done``~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~**Description:**The page shown after a user has reset their password.**Optional arguments:** * ``template_name``: The full name of a template to use. This will default to ``registration/password_reset_done.html`` if not supplied.``django.contrib.auth.views.redirect_to_login``~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~**Description:**Redirects to the login page, and then back to another URL after asuccessful login.**Required arguments:** * ``next``: The URL to redirect to after a successful login.**Optional arguments:** * ``login_url``: The URL of the login page to redirect to. This will default to ``/accounts/login/`` if not supplied.Built-in manipulators---------------------If you don't want to use the built-in views, but want the convenienceof not having to write manipulators for this functionality, theauthentication system provides several built-in manipulators: * ``django.contrib.auth.forms.AdminPasswordChangeForm``: A manipulator used in the admin interface to change a user's password. * ``django.contrib.auth.forms.AuthenticationForm``: A manipulator for logging a user in. * ``django.contrib.auth.forms.PasswordChangeForm``: A manipulator for allowing a user to change their password. * ``django.contrib.auth.forms.PasswordResetForm``: A manipulator for resetting a user's password and emailing the new password to them. * ``django.contrib.auth.forms.UserCreationForm``: A manipulator for creating a new user.Limiting access to logged-in users that pass a test---------------------------------------------------To limit access based on certain permissions or some other test, you'd doessentially 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 thepermission ``polls.can_vote``:: def my_view(request): if not (request.user.is_authenticated() and 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.contrib.auth.decorators import user_passes_test def my_view(request): # ... my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'))(my_view)We're using this particular test as a relatively simple example. However, ifyou just want to test whether a permission is available to a user, you can usethe ``permission_required()`` decorator, described later in this document.Here's the same thing, using Python 2.4's decorator syntax:: from django.contrib.auth.decorators 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 youspecify the URL for your login page (``/accounts/login/`` by default).Example in Python 2.3 syntax:: from django.contrib.auth.decorators 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.contrib.auth.decorators import user_passes_test @user_passes_test(lambda u: u.has_perm('polls.can_vote'), login_url='/login/') def my_view(request): # ...The permission_required decorator~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~**New in Django development version**It's a relatively common task to check whether a user has a particularpermission. For that reason, Django provides a shortcut for that case: the``permission_required()`` decorator. Using this decorator, the earlier examplecan be written as:: from django.contrib.auth.decorators import permission_required def my_view(request): # ... my_view = permission_required('polls.can_vote')(my_view)Note that ``permission_required()`` also takes an optional ``login_url``parameter. Example:: from django.contrib.auth.decorators import permission_required def my_view(request): # ... my_view = permission_required('polls.can_vote', login_url='/loginpage/')(my_view)As in the ``login_required`` decorator, ``login_url`` defaults to``'/accounts/login/'``.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: ../generic_views/Permissions===========Django comes with a simple permissions system. It provides a way to assignpermissions to specific users and groups of users.It's used by the Django admin site, but you're welcome to use it in your owncode.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 objectinstance. For example, it's possible to say "Mary may change news stories," butit's not currently possible to say "Mary may change news stories, but only theones she created herself" or "Mary may only change news stories that have acertain status, publication date or ID." The latter functionality is somethingDjango developers are currently discussing.Default permissions-------------------Three basic permissions -- add, create and delete -- are automatically createdfor each Django model that has a ``class Admin`` set. Behind the scenes, thesepermissions are added to the ``auth_permission`` database table when you run``manage.py syncdb``.Note that if your model doesn't have ``class Admin`` set when you run``syncdb``, the permissions won't be created. If you initialize your databaseand add ``class Admin`` to models after the fact, you'll need to run``manage.py syncdb`` again. It will create any missing permissions forall of your installed apps.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(models.Model): # ... class Meta: permissions = ( ("can_drive", "Can drive"), ("can_vote", "Can vote in elections"), ("can_drink", "Can drink alcohol"), )The only thing this does is create those extra permissions when you run``syncdb``... _model Meta attribute: ../model_api/#meta-optionsAPI reference-------------Just like users, permissions are implemented in a Django model that lives in`django/contrib/auth/models.py`_... _django/contrib/auth/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/models.pyFields~~~~~~``Permission`` objects have the following fields: * ``name`` -- Required. 50 characters or fewer. Example: ``'Can vote'``. * ``content_type`` -- Required. A reference to the ``django_content_type`` database table, which contains a record for each installed Django model. * ``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 ``RequestContext``... admonition:: Technicality Technically, these variables are only made available in the template context if you use ``RequestContext`` *and* your ``TEMPLATE_CONTEXT_PROCESSORS`` setting contains ``"django.core.context_processors.auth"``, which is default. For more, see the `RequestContext docs`_. .. _RequestContext docs: ../templates_python/#subclassing-context-requestcontextUsers-----The currently logged-in user, either a ``User`` instance or an``AnonymousUser``instance, is stored in the template variable ``{{ user }}``:: {% if user.is_authenticated %} <p>Welcome, {{ user.username }}. Thanks for logging in.</p> {% else %} <p>Welcome, new user. Please log 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-inuser had any permissions in the ``foo`` app:: {{ perms.foo }}Two-level-attribute lookup is a proxy to ``User.has_perm``. This example woulddisplay ``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: ../templates_python/Groups======Groups are a generic way of categorizing users so you can apply permissions, orsome 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. Forexample, 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 givethem some label, or extended functionality. For example, you could create agroup ``'Special users'``, and you could write code that could, say, give themaccess to a members-only portion of your site, or send them members-only e-mailmessages.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 ortimestamps.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 create a new message, use ``user_obj.message_set.create(message='message_text')``. * To retrieve/delete messages, use ``user_obj.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 creatinga playlist:: def create_playlist(request, songs): # Create the playlist with the given songs. # ... request.user.message_set.create(message="Your playlist was added successfully.") return render_to_response("playlists/create.html", context_instance=RequestContext(request))When you use ``RequestContext``, the currently logged-in user and his/hermessages 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 }}</li> {% endfor %} </ul> {% endif %}Note that ``RequestContext`` calls ``get_and_delete_messages`` behind thescenes, 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 userdatabase. To send messages to anonymous users, use the `session framework`_... _session framework: ../sessions/Other authentication sources============================The authentication that comes with Django is good enough for most common cases,but you may have the need to hook into another authentication source -- thatis, another source of usernames and passwords or authentication methods.For example, your company may already have an LDAP setup that stores a usernameand password for every employee. It'd be a hassle for both the networkadministrator and the users themselves if users had separate accounts in LDAPand the Django-based applications.So, to handle situations like this, the Django authentication system lets youplug in another authentication sources. You can override Django's defaultdatabase-based scheme, or you can use the default system in tandem with othersystems.Specifying authentication backends----------------------------------Behind the scenes, Django maintains a list of "authentication backends" that itchecks for authentication. When somebody calls``django.contrib.auth.authenticate()`` -- as described in "How to log a user in"above -- Django tries authenticating across all of its authentication backends.If the first authentication method fails, Django tries the second one, and soon, until all backends have been attempted.The list of authentication backends to use is specified in the``AUTHENTICATION_BACKENDS`` setting. This should be a tuple of Python pathnames that point to Python classes that know how to authenticate. These classescan be anywhere on your Python path.By default, ``AUTHENTICATION_BACKENDS`` is set to:: ('django.contrib.auth.backends.ModelBackend',)That's the basic authentication scheme that checks the Django users database.The order of ``AUTHENTICATION_BACKENDS`` matters, so if the same username andpassword is valid in multiple backends, Django will stop processing at thefirst positive match.Writing an authentication backend---------------------------------An authentication backend is a class that implements two methods:``get_user(id)`` and ``authenticate(**credentials)``.The ``get_user`` method takes an ``id`` -- which could be a username, databaseID or whatever -- and returns a ``User`` object.The ``authenticate`` method takes credentials as keyword arguments. Most ofthe time, it'll just look like this:: class MyBackend: def authenticate(self, username=None, password=None): # Check the username/password and return a User.But it could also authenticate a token, like so:: class MyBackend: def authenticate(self, token=None): # Check the token and return a User.Either way, ``authenticate`` should check the credentials it gets, and itshould return a ``User`` object that matches those credentials, if thecredentials are valid. If they're not valid, it should return ``None``.The Django admin system is tightly coupled to the Django ``User`` objectdescribed at the beginning of this document. For now, the best way to deal withthis is to create a Django ``User`` object for each user that exists for yourbackend (e.g., in your LDAP directory, your external SQL database, etc.) Youcan either write a script to do this in advance, or your ``authenticate``method can do it the first time a user logs in.Here's an example backend that authenticates against a username and passwordvariable defined in your ``settings.py`` file and creates a Django ``User``object the first time a user authenticates:: from django.conf import settings from django.contrib.auth.models import User, check_password class SettingsBackend: """ Authenticate against the settings ADMIN_LOGIN and ADMIN_PASSWORD. Use the login name, and a hash of the password. For example: ADMIN_LOGIN = 'admin' ADMIN_PASSWORD = 'sha1$4e987$afbcf42e21bd417fb71db8c66b321e9fc33051de' """ def authenticate(self, username=None, password=None): login_valid = (settings.ADMIN_LOGIN == username) pwd_valid = check_password(password, settings.ADMIN_PASSWORD) if login_valid and pwd_valid: try: user = User.objects.get(username=username) except User.DoesNotExist: # Create a new user. Note that we can set password # to anything, because it won't be checked; the password # from settings.py will. user = User(username=username, password='get from settings.py') user.is_staff = True user.is_superuser = True user.save() return user return None def get_user(self, user_id): try: return User.objects.get(pk=user_id) except User.DoesNotExist: return None