There are a few other bits of the authentication framework that we’ve only dealt with in passing. We’ll take a closer look at them in the following sections.
Permissions and Authorization
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:
- 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 can be set not only per type of object, but also per specific object instance. By using the has_add_permission(), has_change_permission() and has_delete_permission() methods provided by the ModelAdmin class, it’s possible to customize permissions for different object instances of the same type. User objects have two many-to-many fields: groups and user_permissions. User objects can access their related objects in the same way as any other Django model.
Default Permissions
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 for all new models each time you run manage.py migrate.
Groups
django.contrib.auth.models.Group models 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 email messages.
Programmatically Creating Permissions
While custom permissions can be defined within a model’s Meta class, you can also create permissions directly. For example, you can create the can_publish permission for a BookReview model in books:
from books.models import BookReview
from django.contrib.auth.models import Group, Permission
from django.contrib.contenttypes.models import ContentType
content_type = ContentType.objects.get_for_model(BookReview)
permission = Permission.objects.create(codename=’can_publish’,
name=’Can Publish Reviews’,
content_type=content_type)
The permission can then be assigned to a User via its user_permissions attribute or to a Group via its permissions attribute.
Permission Caching
The ModelBackend caches permissions on the User object after the first time they need to be fetched for a permissions check. This is typically fine for the request-response cycle since permissions are not typically checked immediately after they are added (in the admin, for example).
If you are adding permissions and checking them immediately afterward, in a test or view for example, the easiest solution is to re-fetch the User from the database. For example:
from django.contrib.auth.models import Permission, User
from django.shortcuts import get_object_or_404
def user_gains_perms(request, user_id):
user = get_object_or_404(User, pk=user_id)
# any permission check will cache the current set of permissions
user.has_perm(‘books.change_bar’)
permission = Permission.objects.get(codename=’change_bar’)
user.user_permissions.add(permission)
# Checking the cached permission set
user.has_perm(‘books.change_bar’) # False
# Request new instance of User
user = get_object_or_404(User, pk=user_id)
# Permission cache is repopulated from the database
user.has_perm(‘books.change_bar’) # True
# …
Managing Users in the Admin
When you have both django.contrib.admin and django.contrib.auth installed, the admin provides a convenient way to view and manage users, groups, and permissions. Users can be created and deleted like any Django model. Groups can be created, and permissions can be assigned to users or groups. A log of user edits to models made within the admin is also stored and displayed.
Creating Users – You should see a link to “Users” in the “Auth” section of the main admin index page. If you click this link, you should see the user management screen.
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.
If you want a user account to be able to create users using the Django admin site, you’ll need to give them permission to add users and change users (i.e., the “Add user” and “Change user” permissions). If an account has permission to add users but not to change them, that account 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.
Changing Passwords
User passwords are not displayed in the admin (nor stored in the database), but the password storage details are displayed. Included in the display of this information is a link to a password change form that allows admins to change user passwords. Once you click the link, you will be taken to the change password form.
Password Management in Django
Password management is something that should generally not be reinvented unnecessarily, and Django endeavors to provide a secure and flexible set of tools for managing user passwords. This document describes how Django stores passwords, how the storage hashing can be configured, and some utilities to work with hashed passwords.
How Django Stores Passwords – Django provides a flexible password storage system and uses PBKDF2 by default. The password attribute of a User object is a string in this format:
<algorithm>$<iterations>$<salt>$<hash>
Those are the components used for storing a User’s password, separated by the dollar-sign character and consist of: the hashing algorithm, the number of algorithm iterations (work factor), the random salt, and the resulting password hash.
The algorithm is one of a number of one-way hashing or password storage algorithms Django can use. Iterations describe the number of times the algorithm is run over the hash. Salt is the random seed used and the hash is the result of the one-way function. By default, Django uses the PBKDF2 algorithm with a SHA256 hash, a password stretching mechanism recommended by NIST. This should be sufficient for most users: it’s quite secure, requiring massive amounts of computing time to break. However, depending on your requirements, you may choose a different algorithm, or even use a custom algorithm to match your specific security situation. Again, most users shouldn’t need to do this – if you’re not sure, you probably don’t.
If you do, please read on: Django chooses the algorithm to use by consulting the PASSWORD_HASHERS setting. This is a list of hashing algorithm classes that this Django installation supports. The first entry in this list (that is, settings.PASSWORD_HASHERS[0]) will be used to store passwords, and all the other entries are valid hashers that can be used to check existing passwords.
This means that if you want to use a different algorithm, you’ll need to modify PASSWORD_HASHERS to list your preferred algorithm first in the list. The default for PASSWORD_HASHERS is:
PASSWORD_HASHERS = [
‘django.contrib.auth.hashers.PBKDF2PasswordHasher’,
‘django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher’,
‘django.contrib.auth.hashers.BCryptSHA256PasswordHasher’,
‘django.contrib.auth.hashers.BCryptPasswordHasher’,
‘django.contrib.auth.hashers.SHA1PasswordHasher’,
‘django.contrib.auth.hashers.MD5PasswordHasher’,
‘django.contrib.auth.hashers.CryptPasswordHasher’,
]
This means that Django will use PBKDF2 to store all passwords, but will support checking passwords stored with PBKDF2SHA1, bcrypt, SHA1 etc. The next few sections describe a couple of common ways advanced users may want to modify this setting.
Using Bcrypt with Django
Bcrypt is a popular password storage algorithm that’s specifically designed for long-term password storage. It’s not the default used by Django since it requires the use of third-party libraries, but since many people may want to use it, Django supports bcrypt with minimal effort.
To use Bcrypt as your default storage algorithm, do the following:
- Install the bcrypt library. This can be done by running pip install django[bcrypt], or by downloading the library and installing it with python setup.py install.
Modify PASSWORD_HASHERS to list BCryptSHA256PasswordHasher first. That is, in your settings file, you’d put:
PASSWORD_HASHERS = [
‘django.contrib.auth.hashers.BCryptSHA256PasswordHasher’,
‘django.contrib.auth.hashers.BCryptPasswordHasher’,
‘django.contrib.auth.hashers.PBKDF2PasswordHasher’,
‘django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher’,
‘django.contrib.auth.hashers.SHA1PasswordHasher’,
‘django.contrib.auth.hashers.MD5PasswordHasher’,
‘django.contrib.auth.hashers.CryptPasswordHasher’,
]
(You need to keep the other entries in this list, or else Django won’t be able to upgrade passwords).
That’s it – now your Django install will use bcrypt as the default storage algorithm.
Password truncation with BCryptPasswordHasher – The designers of bcrypt truncate all passwords at 72 characters which means that bcrypt(password_with_100_chars) == bcrypt(password_with_100_chars[:72]). The original BCryptPasswordHasher does not have any special handling and thus is also subject to this hidden password length limit.
BCryptSHA256PasswordHasher fixes this by first hashing the password using sha256. This prevents the password truncation and so should be preferred over the BCryptPasswordHasher. The practical ramification of this truncation is pretty marginal as the average user does not have a password greater than 72 characters in length and even being truncated at 72, the compute powered required to brute force bcrypt in any useful amount of time is still astronomical. Nonetheless, we recommend you use BCryptSHA256PasswordHasher anyway on the principle of “better safe than sorry”.
Other bcrypt implementations – There are several other implementations that allow bcrypt to be used with Django. Django’s bcrypt support is NOT directly compatible with these. To upgrade, you will need to modify the hashes in your database to be in the form bcrypt$(raw bcrypt output).
Increasing the work factor – The PBKDF2 and bcrypt algorithms use a number of iterations or rounds of hashing. This deliberately slows down attackers, making attacks against hashed passwords harder. However, as computing power increases, the number of iterations needs to be increased.
The Django development team have chosen a reasonable default (and will increase it with each release of Django), but you may wish to tune it up or down, depending on your security needs and available processing power. To do so, you’ll subclass the appropriate algorithm and override the iterations parameters.
For example, to increase the number of iterations used by the default PBKDF2 algorithm:
- Create a subclass of django.contrib.auth.hashers.PBKDF2PasswordHasher:
from django.contrib.auth.hashers import PBKDF2PasswordHasher
class MyPBKDF2PasswordHasher(PBKDF2PasswordHasher):
iterations = PBKDF2PasswordHasher.iterations * 100
- Save this somewhere in your project. For example, you might put this in a file like myproject/hashers.py.
- Add your new hasher as the first entry in PASSWORD_HASHERS:
PASSWORD_HASHERS = [
‘myproject.hashers.MyPBKDF2PasswordHasher’,
‘django.contrib.auth.hashers.PBKDF2PasswordHasher’,
# … #
]
That’s it – now your Django install will use more iterations when it stores passwords using PBKDF2.
Password Upgrading – When users log in, if their passwords are stored with anything other than the preferred algorithm, Django will automatically upgrade the algorithm to the preferred one. This means that old installs of Django will get automatically more secure as users log in, and it also means that you can switch to new (and better) storage algorithms as they get invented.
However, Django can only upgrade passwords that use algorithms mentioned in PASSWORD_HASHERS, so as you upgrade to new systems you should make sure never to remove entries from this list. If you do, users using unmentioned algorithms won’t be able to upgrade. Passwords will be upgraded when changing the PBKDF2 iteration count.
Manually Managing a User’s Password – The django.contrib.auth.hashers module provides a set of functions to create and validate hashed password. You can use them independently from the User model.
If you’d like to manually authenticate a user by comparing a plain-text password to the hashed password in the database, use the function check_password(). It takes two arguments: the plain-text password to check, and the full value of a user’s password field in the database to check against, and returns True if they match, False otherwise.
make_password() creates a hashed password in the format used by this application. It takes one mandatory argument: the password in plain-text.
Optionally, you can provide a salt and a hashing algorithm to use, if you don’t want to use the defaults (first entry of PASSWORD_HASHERS setting). Currently supported algorithms are: ‘pbkdf2_sha256’, ‘pbkdf2_sha1’, ‘bcrypt_sha256’, ‘bcrypt’, ‘sha1’, ‘md5’, ‘unsalted_md5’ (only for backward compatibility) and ‘crypt’ if you have the crypt library installed.
If the password argument is None, an unusable password is returned (one that will be never accepted by check_password()).
is_password_usable() checks if the given string is a hashed password that has a chance of being verified against check_password().
