Django comes with a user authentication system. It handles user accounts, groups, permissions and cookie-based user sessions. This document explains how things work.
The auth system consists of:
Authentication support is bundled as a Django application in django.contrib.auth. To install it, do the following:
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; you can run that command as many times as you’d like, and each time it’ll only install what’s needed.
The syncdb command creates the necessary database tables, creates permission objects for all installed apps that need ‘em, and prompts you to create a superuser account the first time you run it.
Once you’ve taken those steps, that’s it.
User objects have the following fields:
Boolean. Designates whether this user account should be considered active. Set this flag to False instead of deleting accounts.
This doesn’t control whether or not the user can log in. Nothing in the authentication path checks the is_active flag, so if you want to reject a login based on is_active being False, it is up to you to check that in your own login view. However, permission checking using the methods like has_perm() does check this flag and will always return False for inactive users.
User objects have two many-to-many fields: models.User. groups and user_permissions. User objects can access their related objects 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 following custom methods:
Marks the user as having no password set. This isn't the same as having a blank string for a password. check_password() for this user will never return True. Doesn't save the User object.
You may need this if authentication for your application takes place against an existing external source such as an LDAP directory.
Returns False if set_unusable_password() has been called for this user.
The User model has a custom manager that has the following helper functions:
Creates, saves and returns a User. The username, email and password are set as given, and the User gets is_active=True.
If no password is provided, set_unusable_password() will be called.
See Creating users for example usage.
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 letters that can cause user confusion, including:
The most basic way to create users is to use the create_user() helper function 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 that has already been saved
# to the database. You can continue to change its attributes
# if you want to change other fields.
>>> user.is_staff = True
>>> user.save()
You can also create users using the Django admin site. Assuming you've enabled the admin site and hooked it to the URL /admin/, the "Add user" page is at /admin/auth/user/add/. You should also see a link to "Users" in the "Auth" section of the main admin index page. The "Add user" admin page is different than standard admin pages in that it requires you to choose a username and password before allowing you to edit the rest of the user's fields.
Also note: if you want your own user account to be able to create users using the Django admin site, you'll need to give yourself permission to add users and change users (i.e., the "Add user" and "Change user" permissions). If your account has permission to add users but not to change them, you won't be able to add users. Why? Because if you have permission to add users, you have the power to create superusers, which can then, in turn, change other users. So Django requires add and change permissions as a slight security measure.
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're doing. This is explained in the next section.
The password attribute of a User object is a string in this format:
hashtype$salt$hash
That's hashtype, salt and hash, separated by the dollar-sign character.
Hashtype is either sha1 (default), md5 or crypt -- the algorithm used to perform a one-way hash of the password. Salt is a random string used to salt the raw password to create the hash. Note that the crypt method is only supported on platforms that have the standard Python crypt module available.
For example:
sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4
The set_password() and check_password() functions handle the setting and checking of these values behind the scenes.
Previous Django versions, such as 0.90, used simple MD5 hashes without password salts. For backwards compatibility, those are still supported; they'll be converted automatically to the new style the first time check_password() works correctly for a given user.
django.contrib.auth.models.AnonymousUser is a class that implements the django.contrib.auth.models.User interface, with these differences:
In practice, you probably won't need to use AnonymousUser objects on your own, but they're used by Web requests, as explained in the next section.
manage.py syncdb prompts you to create a superuser the first time you run it after adding 'django.contrib.auth' to your INSTALLED_APPS. If you need to create a superuser at a later date, you can use a command line utility:
manage.py createsuperuser --username=joe --email=joe@example.com
You will be prompted for a password. After you enter one, the user will be created immediately. If you leave off the --username or the --email options, it will prompt you for those values.
If you're using an older release of Django, the old way of creating a superuser on the command line still works:
python /path/to/django/contrib/auth/create_superuser.py
...where /path/to is the path to the Django codebase on your filesystem. The manage.py command is preferred because it figures out the correct path and environment for you.
If you'd like to store additional information related to your users, Django provides a method to specify a site-specific related model -- termed a "user profile" -- for this purpose.
To make use of this feature, define a model with fields for the additional information you'd like to store, or additional methods you'd like to have available, and also add a ForeignKey from your model to the User model, specified with unique=True to ensure only one instance of your model can be created for each User.
To indicate that this model is the user profile model for a given site, fill in the setting AUTH_PROFILE_MODULE with a string consisting of the following items, separated by a dot:
For example, if the profile model was a class named UserProfile and was defined inside an application named accounts, the appropriate setting would be:
AUTH_PROFILE_MODULE = 'accounts.UserProfile'
When a user profile model has been defined and specified in this manner, each User object will have a method -- get_profile() -- which returns the instance of the user profile model associated with that User.
The method get_profile() does not create the profile, if it does not exist. You need to register a handler for the signal django.db.models.signals.post_save on the User model, and, in the handler, if created=True, create the associated user profile.
For more information, see Chapter 12 of the Django book.
Until now, this document has dealt with the low-level APIs for manipulating authentication-related objects. On a higher level, Django can hook this authentication 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 object representing the currently logged-in user. If a user isn't currently logged in, request.user will be set to an instance of AnonymousUser (see the previous 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.
Django provides two functions in django.contrib.auth: authenticate() and login().
To authenticate a given username and password, use authenticate(). It takes two keyword arguments, username and password, and it returns a User object if the password is valid for the given username. If the password 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 make sure 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.
Calling authenticate() first
When you're manually logging a user in, you must call authenticate() before you call login(). authenticate() sets an attribute on the User noting which authentication backend successfully authenticated that user (see the backends documentation for details), and this information is needed later during the login process.
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.
When you call logout(), the session data for the current request is completely cleaned out. All existing data is removed. This is to prevent another person from using the same web browser to log in and have access to the previous user's session data. If you want to put anything into the session that will be available to the user immediately after logging out, do that after calling django.contrib.auth.logout().
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')
# ...
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 syntax introduced in Python 2.4:
from django.contrib.auth.decorators import login_required
@login_required
def my_view(request):
# ...
login_required() also takes an optional redirect_field_name parameter. Example:
from django.contrib.auth.decorators import login_required
def my_view(request):
# ...
my_view = login_required(redirect_field_name='redirect_to')(my_view)
Again, an equivalent example of the more compact decorator syntax introduced in Python 2.4:
from django.contrib.auth.decorators import login_required
@login_required(redirect_field_name='redirect_to')
def my_view(request):
# ...
login_required() does the following:
Note that you'll need to map the appropriate Django view to settings.LOGIN_URL. For example, using the defaults, add the following line to your URLconf:
(r'^accounts/login/$', 'django.contrib.auth.views.login'),
Here's what django.contrib.auth.views.login does:
It's your responsibility to provide the login form in a template called registration/login.html by default. This template gets passed four template context variables:
If you'd prefer not to call the template registration/login.html, you can pass the template_name parameter via the extra arguments to the view in your 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'}),
You can also specify the name of the GET field which contains the URL to redirect to after login by passing redirect_field_name to the view. By default, the field is called next.
Here's a sample registration/login.html template you can use as a starting point. It assumes you have a base.html template that defines a content block:
{% extends "base.html" %}
{% block content %}
{% if form.errors %}
<p>Your username and password didn't match. Please try again.</p>
{% endif %}
<form method="post" action="{% url django.contrib.auth.views.login %}">
<table>
<tr>
<td>{{ form.username.label_tag }}</td>
<td>{{ form.username }}</td>
</tr>
<tr>
<td>{{ form.password.label_tag }}</td>
<td>{{ form.password }}</td>
</tr>
</table>
<input type="submit" value="login" />
<input type="hidden" name="next" value="{{ next }}" />
</form>
{% endblock %}
In addition to the login() view, the authentication system includes a few other useful built-in views located in django.contrib.auth.views:
Logs a user out.
Optional arguments:
Template context:
Logs a user out, then redirects to the login page.
Optional arguments:
Allows a user to change their password.
Optional arguments:
Template context:
The page shown after a user has changed their password.
Optional arguments:
Allows a user to reset their password, and sends them the new password in an e-mail.
Optional arguments:
Template context:
The page shown after a user has reset their password.
Optional arguments:
Redirects to the login page, and then back to another URL after a successful login.
Required arguments:
Optional arguments:
Presents a form for entering a new password.
Optional arguments:
Presents a view which informs the user that the password has been successfully changed.
Optional arguments:
If you don't want to use the built-in views, but want the convenience of not having to write forms for this functionality, the authentication system provides several built-in forms located in django.contrib.auth.forms:
To limit access based on certain permissions or some other test, you'd do essentially 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 the permission 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, if you just want to test whether a permission is available to a user, you can use the 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 you specify the URL for your login page (settings.LOGIN_URL 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):
# ...
It's a relatively common task to check whether a user has a particular permission. For that reason, Django provides a shortcut for that case: the permission_required() decorator. Using this decorator, the earlier example can be written as:
from django.contrib.auth.decorators import permission_required
def my_view(request):
# ...
my_view = permission_required('polls.can_vote')(my_view)
As for the User.has_perm() method, permission names take the form "<application name>.<lowercased model name>" (i.e. polls.choice for a Choice model in the polls application).
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 settings.LOGIN_URL.
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)
Django comes with a simple permissions system. It provides a way to assign permissions to specific users and groups of users.
It's used by the Django admin site, but you're welcome to use it in your own code.
The Django admin site uses permissions as follows:
Permissions are set globally per type of object, not per specific object instance. For example, it's possible to say "Mary may change news stories," but it's not currently possible to say "Mary may change news stories, but only the ones she created herself" or "Mary may only change news stories that have a certain status, publication date or ID." The latter functionality is something Django developers are currently discussing.
When django.contrib.auth is listed in your INSTALLED_APPS setting, it will ensure that three default permissions -- add, change and delete -- are created for each Django model defined in one of your installed applications.
These permissions will be created when you run manage.py syncdb; the first time you run syncdb after adding django.contrib.auth to INSTALLED_APPS, the default permissions will be created for all previously-installed models, as well as for any new models being installed at that time. Afterward, it will create default permissions for new models each time you run manage.py syncdb.
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 manage.py syncdb.
Permission objects have the following fields:
Permission objects have the standard data-access methods like any other Django model.
The currently logged-in user and his/her permissions are made available in the template context when you use RequestContext.
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.
When rendering a template RequestContext, 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 %}
This template context variable is not available if a RequestContext is not being used.
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-in user had any permissions in the foo app:
{{ perms.foo }}
Two-level-attribute lookup is a proxy to User.has_perm. This example would display 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 %}
Groups are a generic way of categorizing users so you can apply permissions, or some 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. For example, 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 give them some label, or extended functionality. For example, you could create a group 'Special users', and you could write code that could, say, give them access to a members-only portion of your site, or send them members-only e-mail 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 or timestamps.
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 creating a 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/her messages 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 the scenes, 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 user database. To send messages to anonymous users, use the session framework.
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 -- that is, another source of usernames and passwords or authentication methods.
For example, your company may already have an LDAP setup that stores a username and password for every employee. It'd be a hassle for both the network administrator and the users themselves if users had separate accounts in LDAP and the Django-based applications.
So, to handle situations like this, the Django authentication system lets you plug in other authentication sources. You can override Django's default database-based scheme, or you can use the default system in tandem with other systems.
See the authentication backend reference for information on the authentication backends included with Django.
Behind the scenes, Django maintains a list of "authentication backends" that it checks 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 so on, 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 path names that point to Python classes that know how to authenticate. These classes can 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 and password is valid in multiple backends, Django will stop processing at the first positive match.
Note
Once a user has authenticated, Django stores which backend was used to authenticate the user in the user's session, and re-uses the same backend for subsequent authentication attempts for that user. This effectively means that authentication sources are cached, so if you change AUTHENTICATION_BACKENDS, you'll need to clear out session data if you need to force users to re-authenticate using different methods. A simple way to do that is simply to execute Session.objects.all().delete().
An authentication backend is a class that implements two methods: get_user(user_id) and authenticate(**credentials).
The get_user method takes a user_id -- which could be a username, database ID or whatever -- and returns a User object.
The authenticate method takes credentials as keyword arguments. Most of the 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 it should return a User object that matches those credentials, if the credentials are valid. If they're not valid, it should return None.
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 (e.g., 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 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
Custom auth backends can provide their own permissions.
The user model will delegate permission lookup functions (get_group_permissions(), get_all_permissions(), has_perm(), and has_module_perms()) to any authentication backend that implements these functions.
The permissions given to the user will be the superset of all permissions returned by all backends. That is, Django grants a permission to a user that any one backend grants.
The simple backend above could implement permissions for the magic admin fairly simply:
class SettingsBackend:
# ...
def has_perm(self, user_obj, perm):
if user_obj.username == settings.ADMIN_LOGIN:
return True
else:
return False
This gives full permissions to the user granted access in the above example. Notice that the backend auth functions all take the user object as an argument, and they also accept the same arguments given to the associated django.contrib.auth.models.User functions.
A full authorization implementation can be found in django/contrib/auth/backends.py, which is the default backend and queries the auth_permission table most of the time.
Sep 20, 2009