Changeset 2918

Timestamp:

05/16/06 11:23:49 (2 years ago)

Author:

jkocherhans

Message:

multi-auth: Updated docs to cover new authentication api.

Files:

• django/branches/multi-auth/docs/authentication.txt (modified) (2 diffs)

django/branches/multi-auth/docs/authentication.txt

@@ -268 +268 @@
---------------------
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-Limiting access to logged-in users
@@ -612 +620 @@
-
-.. _session framework: http://www.djangoproject.com/documentation/sessions/
+
+Other Authentication Sources
+============================
+
+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
+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.
+
+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::
+
+    class MyBackend:
+        def authenticate(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(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. `django.contrib.auth.backends.SettingsBackend`_
+is an example of the latter approach. Note that you don't have to save a user's
+password in the Django User object. Your backend can still check the password
+against an external source, and return a Django User object.
+
+.. _django.contrib.auth.backends.SettingsBackend: http://code.djangoproject.com/browser/django/branches/magic-removal/django/contrib/auth/backends.py