Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Small cleanups to docs/authentication.txt, but still not properly rew…

…orded/proofread

git-svn-id: http://code.djangoproject.com/svn/django/trunk@3255 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit b3debd80ed02a0f6e4c055ca4e0989655831fece 1 parent 08cac47
@adrianholovaty adrianholovaty authored
Showing with 38 additions and 35 deletions.
  1. +38 −35 docs/authentication.txt
View
73 docs/authentication.txt
@@ -267,9 +267,9 @@ previous section). You can tell them apart with ``is_anonymous()``, like so::
How to log a user in
--------------------
-Depending on your task, you'll probably want to make sure to validate the
-user's username and password before you log them in. The easiest way to do so
-is to use the built-in ``authenticate`` and ``login`` functions from within a
+Depending on your task, you'll probably want to make sure to validate the
+user's username and password before you log them in. The easiest way to do so
+is to use the built-in ``authenticate`` and ``login`` functions from within a
view::
from django.contrib.auth import authenticate, login
@@ -279,11 +279,11 @@ view::
if user is not None:
login(request, user)
-``authenticate`` checks the username and password. If they are valid it
-returns a user object, otherwise it returns ``None``. ``login`` makes it so
-your users don't have send a username and password for every request. Because
-the ``login`` function uses sessions, you'll need to make sure you have
-``SessionMiddleware`` enabled. See the `session documentation`_ for
+``authenticate`` checks the username and password. If they are valid it
+returns a user object, otherwise it returns ``None``. ``login`` makes it so
+your users don't have send a username and password for every request. Because
+the ``login`` function uses sessions, you'll need to make sure you have
+``SessionMiddleware`` enabled. See the `session documentation`_ for
more information.
@@ -681,60 +681,62 @@ database. To send messages to anonymous users, use the `session framework`_.
.. _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
+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,
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:
-``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::
+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, 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.
+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::
+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
class SettingsBackend:
"""
- Authenticate against vars in settings.py Use the login name, and a hash
+ Authenticate against vars in settings.py Use the login name, and a hash
of the password. For example:
ADMIN_LOGIN = 'admin'
@@ -747,8 +749,9 @@ authenticate::
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
Please sign in to comment.
Something went wrong with that request. Please try again.