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.
See also
Even though users may use strong passwords, attackers might be able to eavesdrop on their connections. Use HTTPS to avoid sending passwords (or any other sensitive data) over plain HTTP connections because they will be vulnerable to password sniffing.
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; see below. 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.Argon2PasswordHasher',
'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
'django.contrib.auth.hashers.BCryptPasswordHasher',
]
This means that Django will use PBKDF2 to store all passwords but will support checking passwords stored with PBKDF2SHA1, argon2, and bcrypt.
The next few sections describe a couple of common ways advanced users may want to modify this setting.
Using Argon2 with Django¶
Argon2 is the winner of the 2015 Password Hashing Competition, a community organized open competition to select a next generation hashing algorithm. It’s designed not to be easier to compute on custom hardware than it is to compute on an ordinary CPU.
Argon2 is not the default for Django because it requires a third-party library. The Password Hashing Competition panel, however, recommends immediate use of Argon2 rather than the other algorithms supported by Django.
To use Argon2 as your default storage algorithm, do the following:
Install the argon2-cffi library. This can be done by running
pip install django[argon2]
, which is equivalent topip install argon2-cffi
(along with any version requirement from Django’ssetup.py
).Modify
PASSWORD_HASHERS
to listArgon2PasswordHasher
first. That is, in your settings file, you’d put:PASSWORD_HASHERS = [ 'django.contrib.auth.hashers.Argon2PasswordHasher', 'django.contrib.auth.hashers.PBKDF2PasswordHasher', 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher', 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher', 'django.contrib.auth.hashers.BCryptPasswordHasher', ]
Keep and/or add any entries in this list if you need Django to upgrade passwords.
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]
, which is equivalent topip install bcrypt
(along with any version requirement from Django’ssetup.py
).Modify
PASSWORD_HASHERS
to listBCryptSHA256PasswordHasher
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.Argon2PasswordHasher', ]
Keep and/or add any entries in this list if you need Django 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)
. For example:
bcrypt$$2a$12$NT0I31Sa7ihGEWpka9ASYrEFkhuTNeBQ2xfZskIiiJeyFXhRgS.Sy
.
Increasing the work factor¶
PBKDF2 and bcrypt¶
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. We’ve 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): """ A subclass of PBKDF2PasswordHasher that uses 100 times more iterations. """ 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', 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher', 'django.contrib.auth.hashers.Argon2PasswordHasher', 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher', 'django.contrib.auth.hashers.BCryptPasswordHasher', ]
That’s it – now your Django install will use more iterations when it stores passwords using PBKDF2.
Argon2¶
Argon2 has three attributes that can be customized:
time_cost
controls the number of iterations within the hash.memory_cost
controls the size of memory that must be used during the computation of the hash.parallelism
controls how many CPUs the computation of the hash can be parallelized on.
The default values of these attributes are probably fine for you. If you determine that the password hash is too fast or too slow, you can tweak it as follows:
- Choose
parallelism
to be the number of threads you can spare computing the hash. - Choose
memory_cost
to be the KiB of memory you can spare. - Adjust
time_cost
and measure the time hashing a password takes. Pick atime_cost
that takes an acceptable time for you. Iftime_cost
set to 1 is unacceptably slow, lowermemory_cost
.
memory_cost
interpretation
The argon2 command-line utility and some other libraries interpret the
memory_cost
parameter differently from the value that Django uses. The
conversion is given by memory_cost == 2 ** memory_cost_commandline
.
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. Hashed passwords will be
updated when increasing (or decreasing) the number of PBKDF2 iterations or
bcrypt rounds.
Be aware that if all the passwords in your database aren’t encoded in the default hasher’s algorithm, you may be vulnerable to a user enumeration timing attack due to a difference between the duration of a login request for a user with a password encoded in a non-default algorithm and the duration of a login request for a nonexistent user (which runs the default hasher). You may be able to mitigate this by upgrading older password hashes.
Password upgrading without requiring a login¶
If you have an existing database with an older, weak hash such as MD5 or SHA1, you might want to upgrade those hashes yourself instead of waiting for the upgrade to happen when a user logs in (which may never happen if a user doesn’t return to your site). In this case, you can use a “wrapped” password hasher.
For this example, we’ll migrate a collection of SHA1 hashes to use
PBKDF2(SHA1(password)) and add the corresponding password hasher for checking
if a user entered the correct password on login. We assume we’re using the
built-in User
model and that our project has an accounts
app. You can
modify the pattern to work with any algorithm or with a custom user model.
First, we’ll add the custom hasher:
from django.contrib.auth.hashers import (
PBKDF2PasswordHasher, SHA1PasswordHasher,
)
class PBKDF2WrappedSHA1PasswordHasher(PBKDF2PasswordHasher):
algorithm = 'pbkdf2_wrapped_sha1'
def encode_sha1_hash(self, sha1_hash, salt, iterations=None):
return super(PBKDF2WrappedSHA1PasswordHasher, self).encode(sha1_hash, salt, iterations)
def encode(self, password, salt, iterations=None):
_, _, sha1_hash = SHA1PasswordHasher().encode(password, salt).split('$', 2)
return self.encode_sha1_hash(sha1_hash, salt, iterations)
The data migration might look something like:
from django.db import migrations
from ..hashers import PBKDF2WrappedSHA1PasswordHasher
def forwards_func(apps, schema_editor):
User = apps.get_model('auth', 'User')
users = User.objects.filter(password__startswith='sha1$')
hasher = PBKDF2WrappedSHA1PasswordHasher()
for user in users:
algorithm, salt, sha1_hash = user.password.split('$', 2)
user.password = hasher.encode_sha1_hash(sha1_hash, salt)
user.save(update_fields=['password'])
class Migration(migrations.Migration):
dependencies = [
('accounts', '0001_initial'),
# replace this with the latest migration in contrib.auth
('auth', '####_migration_name'),
]
operations = [
migrations.RunPython(forwards_func),
]
Be aware that this migration will take on the order of several minutes for several thousand users, depending on the speed of your hardware.
Finally, we’ll add a PASSWORD_HASHERS
setting:
PASSWORD_HASHERS = [
'django.contrib.auth.hashers.PBKDF2PasswordHasher',
'accounts.hashers.PBKDF2WrappedSHA1PasswordHasher',
]
Include any other hashers that your site uses in this list.
Included hashers¶
The full list of hashers included in Django is:
[
'django.contrib.auth.hashers.PBKDF2PasswordHasher',
'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
'django.contrib.auth.hashers.Argon2PasswordHasher',
'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
'django.contrib.auth.hashers.BCryptPasswordHasher',
'django.contrib.auth.hashers.SHA1PasswordHasher',
'django.contrib.auth.hashers.MD5PasswordHasher',
'django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher',
'django.contrib.auth.hashers.UnsaltedMD5PasswordHasher',
'django.contrib.auth.hashers.CryptPasswordHasher',
]
The corresponding algorithm names are:
pbkdf2_sha256
pbkdf2_sha1
argon2
bcrypt_sha256
bcrypt
sha1
md5
unsalted_sha1
unsalted_md5
crypt
Writing your own hasher¶
If you write your own password hasher that contains a work factor such as a
number of iterations, you should implement a
harden_runtime(self, password, encoded)
method to bridge the runtime gap
between the work factor supplied in the encoded
password and the default
work factor of the hasher. This prevents a user enumeration timing attack due
to difference between a login request for a user with a password encoded in an
older number of iterations and a nonexistent user (which runs the default
hasher’s default number of iterations).
Taking PBKDF2 as example, if encoded
contains 20,000 iterations and the
hasher’s default iterations
is 30,000, the method should run password
through another 10,000 iterations of PBKDF2.
If your hasher doesn’t have a work factor, implement the method as a no-op
(pass
).
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.
-
check_password
(password, encoded)[source]¶ If you’d like to manually authenticate a user by comparing a plain-text password to the hashed password in the database, use the convenience function
check_password()
. It takes two arguments: the plain-text password to check, and the full value of a user’spassword
field in the database to check against, and returnsTrue
if they match,False
otherwise.
-
make_password
(password, salt=None, hasher='default')[source]¶ 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). See Included hashers for the algorithm name of each hasher. If the password argument isNone
, an unusable password is returned (a one that will be never accepted bycheck_password()
).
-
is_password_usable
(encoded_password)[source]¶ Checks if the given string is a hashed password that has a chance of being verified against
check_password()
.
Password validation¶
Users often choose poor passwords. To help mitigate this problem, Django offers pluggable password validation. You can configure multiple password validators at the same time. A few validators are included in Django, but it’s simple to write your own as well.
Each password validator must provide a help text to explain the requirements to the user, validate a given password and return an error message if it does not meet the requirements, and optionally receive passwords that have been set. Validators can also have optional settings to fine tune their behavior.
Validation is controlled by the AUTH_PASSWORD_VALIDATORS
setting.
The default for the setting is an empty list, which means no validators are
applied. In new projects created with the default startproject
template, a simple set of validators is enabled.
By default, validators are used in the forms to reset or change passwords and
in the createsuperuser
and changepassword
management
commands. Validators aren’t applied at the model level, for example in
User.objects.create_user()
and create_superuser()
, because we assume
that developers, not users, interact with Django at that level and also because
model validation doesn’t automatically run as part of creating models.
Note
Password validation can prevent the use of many types of weak passwords. However, the fact that a password passes all the validators doesn’t guarantee that it is a strong password. There are many factors that can weaken a password that are not detectable by even the most advanced password validators.
Enabling password validation¶
Password validation is configured in the
AUTH_PASSWORD_VALIDATORS
setting:
AUTH_PASSWORD_VALIDATORS = [
{
'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
},
{
'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
'OPTIONS': {
'min_length': 9,
}
},
{
'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
},
{
'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
},
]
This example enables all four included validators:
UserAttributeSimilarityValidator
, which checks the similarity between the password and a set of attributes of the user.MinimumLengthValidator
, which simply checks whether the password meets a minimum length. This validator is configured with a custom option: it now requires the minimum length to be nine characters, instead of the default eight.CommonPasswordValidator
, which checks whether the password occurs in a list of common passwords. By default, it compares to an included list of 1000 common passwords.NumericPasswordValidator
, which checks whether the password isn’t entirely numeric.
For UserAttributeSimilarityValidator
and CommonPasswordValidator
,
we’re simply using the default settings in this example.
NumericPasswordValidator
has no settings.
The help texts and any errors from password validators are always returned in
the order they are listed in AUTH_PASSWORD_VALIDATORS
.
Included validators¶
Django includes four validators:
-
class
MinimumLengthValidator
(min_length=8)[source]¶ Validates whether the password meets a minimum length. The minimum length can be customized with the
min_length
parameter.
-
class
UserAttributeSimilarityValidator
(user_attributes=DEFAULT_USER_ATTRIBUTES, max_similarity=0.7)[source]¶ Validates whether the password is sufficiently different from certain attributes of the user.
The
user_attributes
parameter should be an iterable of names of user attributes to compare to. If this argument is not provided, the default is used:'username', 'first_name', 'last_name', 'email'
. Attributes that don’t exist are ignored.The minimum similarity of a rejected password can be set on a scale of 0 to 1 with the
max_similarity
parameter. A setting of 0 rejects all passwords, whereas a setting of 1 rejects only passwords that are identical to an attribute’s value.
-
class
CommonPasswordValidator
(password_list_path=DEFAULT_PASSWORD_LIST_PATH)[source]¶ Validates whether the password is not a common password. By default, this checks against a list of 1000 common password created by Mark Burnett.
The
password_list_path
can be set to the path of a custom file of common passwords. This file should contain one password per line and may be plain text or gzipped.
Integrating validation¶
There are a few functions in django.contrib.auth.password_validation
that
you can call from your own forms or other code to integrate password
validation. This can be useful if you use custom forms for password setting,
or if you have API calls that allow passwords to be set, for example.
-
validate_password
(password, user=None, password_validators=None)[source]¶ Validates a password. If all validators find the password valid, returns
None
. If one or more validators reject the password, raises aValidationError
with all the error messages from the validators.The
user
object is optional: if it’s not provided, some validators may not be able to perform any validation and will accept any password.
-
password_changed
(password, user=None, password_validators=None)[source]¶ Informs all validators that the password has been changed. This can be used by validators such as one that prevents password reuse. This should be called once the password has been successfully changed.
For subclasses of
AbstractBaseUser
, the password field will be marked as “dirty” when callingset_password()
which triggers a call topassword_changed()
after the user is saved.
-
password_validators_help_texts
(password_validators=None)[source]¶ Returns a list of the help texts of all validators. These explain the password requirements to the user.
-
password_validators_help_text_html
(password_validators=None)¶ Returns an HTML string with all help texts in an
<ul>
. This is helpful when adding password validation to forms, as you can pass the output directly to thehelp_text
parameter of a form field.
-
get_password_validators
(validator_config)[source]¶ Returns a set of validator objects based on the
validator_config
parameter. By default, all functions use the validators defined inAUTH_PASSWORD_VALIDATORS
, but by calling this function with an alternate set of validators and then passing the result into thepassword_validators
parameter of the other functions, your custom set of validators will be used instead. This is useful when you have a typical set of validators to use for most scenarios, but also have a special situation that requires a custom set. If you always use the same set of validators, there is no need to use this function, as the configuration fromAUTH_PASSWORD_VALIDATORS
is used by default.The structure of
validator_config
is identical to the structure ofAUTH_PASSWORD_VALIDATORS
. The return value of this function can be passed into thepassword_validators
parameter of the functions listed above.
Note that where the password is passed to one of these functions, this should always be the clear text password - not a hashed password.
Writing your own validator¶
If Django’s built-in validators are not sufficient, you can write your own password validators. Validators are fairly simple classes. They must implement two methods:
validate(self, password, user=None)
: validate a password. ReturnNone
if the password is valid, or raise aValidationError
with an error message if the password is not valid. You must be able to deal withuser
beingNone
- if that means your validator can’t run, simply returnNone
for no error.get_help_text()
: provide a help text to explain the requirements to the user.
Any items in the OPTIONS
in AUTH_PASSWORD_VALIDATORS
for your
validator will be passed to the constructor. All constructor arguments should
have a default value.
Here’s a basic example of a validator, with one optional setting:
from django.core.exceptions import ValidationError
from django.utils.translation import ugettext as _
class MinimumLengthValidator(object):
def __init__(self, min_length=8):
self.min_length = min_length
def validate(self, password, user=None):
if len(password) < self.min_length:
raise ValidationError(
_("This password must contain at least %(min_length)d characters."),
code='password_too_short',
params={'min_length': self.min_length},
)
def get_help_text(self):
return _(
"Your password must contain at least %(min_length)d characters."
% {'min_length': self.min_length}
)
You can also implement password_changed(password, user=None
), which will
be called after a successful password change. That can be used to prevent
password reuse, for example. However, if you decide to store a user’s previous
passwords, you should never do so in clear text.