Small cleanups to docs/authentication.txt, but still not properly reworded/proofread

.. _session framework: http://www.djangoproject.com/documentation/sessions/

Other Authentication Sources

Other authentication sources

============================

Django supports other authentication sources as well. You can even use 

Django supports other authentication sources, as well. You can even use

multiple sources at the same time.

Using multiple backends

-----------------------

The list of backends to use is controlled by the ``AUTHENTICATION_BACKENDS``

setting. This should be a tuple of python path names. It defaults to 

``('django.contrib.auth.backends.ModelBackend',)``. To add additional backends

setting. This should be a tuple of Python path names. It defaults to

``('django.contrib.auth.backends.ModelBackend',)``. To add additional backends,

just add them to your settings.py file. Ordering matters, so if the same

username and password is valid in multiple backends, the first one in the

list will return a user object, and the remaining ones won't even get a chance.

list will return a ``User`` object, and the remaining ones won't even get a

chance.

Writing an authentication backend

---------------------------------

An authentication backend is a class that implements 2 methods: 

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, and database id, whatever, and returns 

a user object. The  ``authenticate`` method takes credentials as keyword 

arguments. Many times it will just look like this::

takes an ``id`` -- which could be a username, database ID or whatever -- and

returns a ``User`` object. The  ``authenticate`` method takes credentials as

keyword arguments. Many times it will just look like this::

    class MyBackend:

        def authenticate(username=None, password=None):

            # check the username/password and return a user

            # check the username/password and return a User

but it could also authenticate a token like so::

But it could also authenticate a token, like so::

    class MyBackend:

        def authenticate(token=None):

            # check the token and return a user

Regardless, ``authenticate`` should check the credentials it gets, and if they

are valid, it should return a user object that matches those credentials.

The Django admin system is tightly coupled to the Django User object described 

at the beginning of this document. For now, the best way to deal with this is 

to create a Django User object for each user that exists for your backend 

(i.e. in your LDAP directory, your external SQL database, etc.) You can 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 password variable defined in your 

``settings.py`` file and creates a Django user object the first time they 

authenticate::

are valid, it should return a ``User`` object that matches those credentials.

The Django admin system is tightly coupled to the Django ``User`` object

described at the beginning of this document. For now, the best way to deal with

this is to create a Django ``User`` object for each user that exists for your

backend (i.e. in your LDAP directory, your external SQL database, etc.) You can

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 password

variable 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

                try:

                    user = User.objects.get(username=username)

                except User.DoesNotExist:

                    # Create a new user. Note that we can set password to anything

                    # as it won't be checked, the password from settings.py will.

                    # 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