Password management is something that should generally not be reinvented\nunnecessarily, and Django endeavors to provide a secure and flexible set of\ntools for managing user passwords. This document describes how Django stores\npasswords, how the storage hashing can be configured, and some utilities to\nwork with hashed passwords.
\n\nDjango provides a flexible password storage system and uses PBKDF2 by default.
\nThe password attribute of a\nUser object is a string in this format:
<algorithm>$<iterations>$<salt>$<hash>\nThose are the components used for storing a User’s password, separated by the\ndollar-sign character and consist of: the hashing algorithm, the number of\nalgorithm iterations (work factor), the random salt, and the resulting password\nhash. The algorithm is one of a number of one-way hashing or password storage\nalgorithms Django can use; see below. Iterations describe the number of times\nthe algorithm is run over the hash. Salt is the random seed used and the hash\nis the result of the one-way function.
\nBy default, Django uses the PBKDF2 algorithm with a SHA256 hash, a\npassword stretching mechanism recommended by NIST. This should be\nsufficient for most users: it’s quite secure, requiring massive\namounts of computing time to break.
\nHowever, depending on your requirements, you may choose a different\nalgorithm, or even use a custom algorithm to match your specific\nsecurity situation. Again, most users shouldn’t need to do this – if\nyou’re not sure, you probably don’t. If you do, please read on:
\nDjango chooses the algorithm to use by consulting the\nPASSWORD_HASHERS setting. This is a list of hashing algorithm\nclasses that this Django installation supports. The first entry in this list\n(that is, settings.PASSWORD_HASHERS[0]) will be used to store passwords,\nand all the other entries are valid hashers that can be used to check existing\npasswords. This means that if you want to use a different algorithm, you’ll\nneed to modify PASSWORD_HASHERS to list your preferred algorithm\nfirst in the list.
The default for PASSWORD_HASHERS is:
PASSWORD_HASHERS = [\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.BCryptPasswordHasher',\n]\nThis means that Django will use PBKDF2 to store all passwords but will support\nchecking passwords stored with PBKDF2SHA1, argon2, and bcrypt.
\nThe next few sections describe a couple of common ways advanced users may want\nto modify this setting.
\nArgon2 is the winner of the 2015 Password Hashing Competition, a community\norganized open competition to select a next generation hashing algorithm. It’s\ndesigned not to be easier to compute on custom hardware than it is to compute\non an ordinary CPU.
\nArgon2 is not the default for Django because it requires a third-party\nlibrary. The Password Hashing Competition panel, however, recommends immediate\nuse of Argon2 rather than the other algorithms supported by Django.
\nTo use Argon2 as your default storage algorithm, do the following:
\nInstall the argon2-cffi library. This can be done by running pip\ninstall django[argon2], which is equivalent to pip install argon2-cffi\n(along with any version requirement from Django’s setup.py).
Modify PASSWORD_HASHERS to list Argon2PasswordHasher first.\nThat is, in your settings file, you’d put:
PASSWORD_HASHERS = [\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.BCryptPasswordHasher',\n]\nKeep and/or add any entries in this list if you need Django to upgrade\npasswords.
\nbcrypt with DjangoLink to this heading#Bcrypt is a popular password storage algorithm that’s specifically designed\nfor long-term password storage. It’s not the default used by Django since it\nrequires the use of third-party libraries, but since many people may want to\nuse it Django supports bcrypt with minimal effort.
\nTo use Bcrypt as your default storage algorithm, do the following:
\nInstall the bcrypt library. This can be done by running pip install\ndjango[bcrypt], which is equivalent to pip install bcrypt (along with\nany version requirement from Django’s setup.py).
Modify PASSWORD_HASHERS to list BCryptSHA256PasswordHasher\nfirst. That is, in your settings file, you’d put:
PASSWORD_HASHERS = [\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.BCryptPasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n]\nKeep and/or add any entries in this list if you need Django to upgrade\npasswords.
\nThat’s it – now your Django install will use Bcrypt as the default storage\nalgorithm.
\n\n\nThe PBKDF2 and bcrypt algorithms use a number of iterations or rounds of\nhashing. This deliberately slows down attackers, making attacks against hashed\npasswords harder. However, as computing power increases, the number of\niterations needs to be increased. We’ve chosen a reasonable default (and will\nincrease it with each release of Django), but you may wish to tune it up or\ndown, depending on your security needs and available processing power. To do so,\nyou’ll subclass the appropriate algorithm and override the iterations\nparameters. For example, to increase the number of iterations used by the\ndefault PBKDF2 algorithm:
Create a subclass of django.contrib.auth.hashers.PBKDF2PasswordHasher:
from django.contrib.auth.hashers import PBKDF2PasswordHasher\n\nclass MyPBKDF2PasswordHasher(PBKDF2PasswordHasher):\n """\n A subclass of PBKDF2PasswordHasher that uses 100 times more iterations.\n """\n iterations = PBKDF2PasswordHasher.iterations * 100\nSave this somewhere in your project. For example, you might put this in\na file like myproject/hashers.py.
Add your new hasher as the first entry in PASSWORD_HASHERS:
PASSWORD_HASHERS = [\n 'myproject.hashers.MyPBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.BCryptPasswordHasher',\n]\nThat’s it – now your Django install will use more iterations when it\nstores passwords using PBKDF2.
\nArgon2 has three attributes that can be customized:
\ntime_cost controls the number of iterations within the hash.
memory_cost controls the size of memory that must be used during the\ncomputation of the hash.
parallelism controls how many CPUs the computation of the hash can be\nparallelized on.
The default values of these attributes are probably fine for you. If you\ndetermine that the password hash is too fast or too slow, you can tweak it as\nfollows:
\nChoose parallelism to be the number of threads you can\nspare 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.\nPick a time_cost that takes an acceptable time for you.\nIf time_cost set to 1 is unacceptably slow, lower memory_cost.
When users log in, if their passwords are stored with anything other than\nthe preferred algorithm, Django will automatically upgrade the algorithm\nto the preferred one. This means that old installs of Django will get\nautomatically more secure as users log in, and it also means that you\ncan switch to new (and better) storage algorithms as they get invented.
\nHowever, Django can only upgrade passwords that use algorithms mentioned in\nPASSWORD_HASHERS, so as you upgrade to new systems you should make\nsure never to remove entries from this list. If you do, users using\nunmentioned algorithms won’t be able to upgrade. Hashed passwords will be\nupdated when increasing (or decreasing) the number of PBKDF2 iterations or\nbcrypt rounds.
Be aware that if all the passwords in your database aren’t encoded in the\ndefault hasher’s algorithm, you may be vulnerable to a user enumeration timing\nattack due to a difference between the duration of a login request for a user\nwith a password encoded in a non-default algorithm and the duration of a login\nrequest for a nonexistent user (which runs the default hasher). You may be able\nto mitigate this by upgrading older password hashes.
\n\nIf you have an existing database with an older, weak hash such as MD5 or SHA1,\nyou might want to upgrade those hashes yourself instead of waiting for the\nupgrade to happen when a user logs in (which may never happen if a user doesn’t\nreturn to your site). In this case, you can use a «wrapped» password hasher.
\nFor this example, we’ll migrate a collection of SHA1 hashes to use\nPBKDF2(SHA1(password)) and add the corresponding password hasher for checking\nif a user entered the correct password on login. We assume we’re using the\nbuilt-in User model and that our project has an accounts app. You can\nmodify the pattern to work with any algorithm or with a custom user model.
First, we’ll add the custom hasher:
\naccounts/hashers.pyfrom django.contrib.auth.hashers import (\n PBKDF2PasswordHasher, SHA1PasswordHasher,\n)\n\n\nclass PBKDF2WrappedSHA1PasswordHasher(PBKDF2PasswordHasher):\n algorithm = 'pbkdf2_wrapped_sha1'\n\n def encode_sha1_hash(self, sha1_hash, salt, iterations=None):\n return super(PBKDF2WrappedSHA1PasswordHasher, self).encode(sha1_hash, salt, iterations)\n\n def encode(self, password, salt, iterations=None):\n _, _, sha1_hash = SHA1PasswordHasher().encode(password, salt).split('$', 2)\n return self.encode_sha1_hash(sha1_hash, salt, iterations)\nThe data migration might look something like:
\naccounts/migrations/0002_migrate_sha1_passwords.pyfrom django.db import migrations\n\nfrom ..hashers import PBKDF2WrappedSHA1PasswordHasher\n\n\ndef forwards_func(apps, schema_editor):\n User = apps.get_model('auth', 'User')\n users = User.objects.filter(password__startswith='sha1$')\n hasher = PBKDF2WrappedSHA1PasswordHasher()\n for user in users:\n algorithm, salt, sha1_hash = user.password.split('$', 2)\n user.password = hasher.encode_sha1_hash(sha1_hash, salt)\n user.save(update_fields=['password'])\n\n\nclass Migration(migrations.Migration):\n\n dependencies = [\n ('accounts', '0001_initial'),\n # replace this with the latest migration in contrib.auth\n ('auth', '####_migration_name'),\n ]\n\n operations = [\n migrations.RunPython(forwards_func),\n ]\nBe aware that this migration will take on the order of several minutes for\nseveral thousand users, depending on the speed of your hardware.
\nFinally, we’ll add a PASSWORD_HASHERS setting:
mysite/settings.pyPASSWORD_HASHERS = [\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'accounts.hashers.PBKDF2WrappedSHA1PasswordHasher',\n]\nInclude any other hashers that your site uses in this list.
\nThe full list of hashers included in Django is:
\n[\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.BCryptPasswordHasher',\n 'django.contrib.auth.hashers.SHA1PasswordHasher',\n 'django.contrib.auth.hashers.MD5PasswordHasher',\n 'django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher',\n 'django.contrib.auth.hashers.UnsaltedMD5PasswordHasher',\n 'django.contrib.auth.hashers.CryptPasswordHasher',\n]\nThe corresponding algorithm names are:
\npbkdf2_sha256
pbkdf2_sha1
argon2
bcrypt_sha256
bcrypt
sha1
md5
unsalted_sha1
unsalted_md5
crypt
If you write your own password hasher that contains a work factor such as a\nnumber of iterations, you should implement a\nharden_runtime(self, password, encoded) method to bridge the runtime gap\nbetween the work factor supplied in the encoded password and the default\nwork factor of the hasher. This prevents a user enumeration timing attack due\nto difference between a login request for a user with a password encoded in an\nolder number of iterations and a nonexistent user (which runs the default\nhasher’s default number of iterations).
Taking PBKDF2 as example, if encoded contains 20,000 iterations and the\nhasher’s default iterations is 30,000, the method should run password\nthrough another 10,000 iterations of PBKDF2.
If your hasher doesn’t have a work factor, implement the method as a no-op\n(pass).
The django.contrib.auth.hashers module provides a set of functions\nto create and validate hashed password. You can use them independently\nfrom the User model.
If you’d like to manually authenticate a user by comparing a plain-text\npassword to the hashed password in the database, use the convenience\nfunction check_password(). It takes two arguments: the plain-text\npassword to check, and the full value of a user’s password field in the\ndatabase to check against, and returns True if they match, False\notherwise.
Creates a hashed password in the format used by this application. It takes\none mandatory argument: the password in plain-text. Optionally, you can\nprovide a salt and a hashing algorithm to use, if you don’t want to use the\ndefaults (first entry of PASSWORD_HASHERS setting). See\nIncluded hashers for the algorithm name of each hasher. If the\npassword argument is None, an unusable password is returned (a one that\nwill be never accepted by check_password()).
Checks if the given string is a hashed password that has a chance\nof being verified against check_password().
Users often choose poor passwords. To help mitigate this problem, Django\noffers pluggable password validation. You can configure multiple password\nvalidators at the same time. A few validators are included in Django, but it’s\nsimple to write your own as well.
\nEach password validator must provide a help text to explain the requirements to\nthe user, validate a given password and return an error message if it does not\nmeet the requirements, and optionally receive passwords that have been set.\nValidators can also have optional settings to fine tune their behavior.
\nValidation is controlled by the AUTH_PASSWORD_VALIDATORS setting.\nThe default for the setting is an empty list, which means no validators are\napplied. In new projects created with the default startproject\ntemplate, a simple set of validators is enabled.
By default, validators are used in the forms to reset or change passwords and\nin the createsuperuser and changepassword management\ncommands. Validators aren’t applied at the model level, for example in\nUser.objects.create_user() and create_superuser(), because we assume\nthat developers, not users, interact with Django at that level and also because\nmodel validation doesn’t automatically run as part of creating models.
Password validation is configured in the\nAUTH_PASSWORD_VALIDATORS setting:
AUTH_PASSWORD_VALIDATORS = [\n {\n 'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',\n },\n {\n 'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',\n 'OPTIONS': {\n 'min_length': 9,\n }\n },\n {\n 'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',\n },\n {\n 'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',\n },\n]\nThis example enables all four included validators:
\nUserAttributeSimilarityValidator, which checks the similarity between\nthe password and a set of attributes of the user.
MinimumLengthValidator, which simply checks whether the password meets a\nminimum length. This validator is configured with a custom option: it now\nrequires the minimum length to be nine characters, instead of the default\neight.
CommonPasswordValidator, which checks whether the password occurs in a\nlist of common passwords. By default, it compares to an included list of\n1000 common passwords.
NumericPasswordValidator, which checks whether the password isn’t\nentirely numeric.
For UserAttributeSimilarityValidator and CommonPasswordValidator,\nwe’re simply using the default settings in this example.\nNumericPasswordValidator has no settings.
The help texts and any errors from password validators are always returned in\nthe order they are listed in AUTH_PASSWORD_VALIDATORS.
Django includes four validators:
\nValidates whether the password meets a minimum length.\nThe minimum length can be customized with the min_length parameter.
Validates whether the password is sufficiently different from certain\nattributes of the user.
\nThe user_attributes parameter should be an iterable of names of user\nattributes to compare to. If this argument is not provided, the default\nis used: 'username', 'first_name', 'last_name', 'email'.\nAttributes that don’t exist are ignored.
The maximum similarity the password can have, before it is rejected, can\nbe set with the max_similarity parameter, on a scale of 0 to 1.\nA setting of 0 will cause all passwords to be rejected, whereas a setting\nof 1 will cause it to only reject passwords that are identical to an\nattribute’s value.
Validates whether the password is not a common password. By default, this\nchecks against a list of 1000 common password created by\nMark Burnett.
\nThe password_list_path can be set to the path of a custom file of\ncommon passwords. This file should contain one password per line and\nmay be plain text or gzipped.
Validates whether the password is not entirely numeric.
\nThere are a few functions in django.contrib.auth.password_validation that\nyou can call from your own forms or other code to integrate password\nvalidation. This can be useful if you use custom forms for password setting,\nor if you have API calls that allow passwords to be set, for example.
Validates a password. If all validators find the password valid, returns\nNone. If one or more validators reject the password, raises a\nValidationError with all the error messages\nfrom the validators.
The user object is optional: if it’s not provided, some validators may\nnot be able to perform any validation and will accept any password.
Informs all validators that the password has been changed. This can be used\nby validators such as one that prevents password reuse. This should be\ncalled once the password has been successfully changed.
\nFor subclasses of AbstractBaseUser,\nthe password field will be marked as «dirty» when calling\nset_password() which\ntriggers a call to password_changed() after the user is saved.
Returns a list of the help texts of all validators. These explain the\npassword requirements to the user.
\nReturns an HTML string with all help texts in an <ul>. This is\nhelpful when adding password validation to forms, as you can pass the\noutput directly to the help_text parameter of a form field.
Returns a set of validator objects based on the validator_config\nparameter. By default, all functions use the validators defined in\nAUTH_PASSWORD_VALIDATORS, but by calling this function with an\nalternate set of validators and then passing the result into the\npassword_validators parameter of the other functions, your custom set\nof validators will be used instead. This is useful when you have a typical\nset of validators to use for most scenarios, but also have a special\nsituation that requires a custom set. If you always use the same set\nof validators, there is no need to use this function, as the configuration\nfrom AUTH_PASSWORD_VALIDATORS is used by default.
The structure of validator_config is identical to the\nstructure of AUTH_PASSWORD_VALIDATORS. The return value of\nthis function can be passed into the password_validators parameter\nof the functions listed above.
Note that where the password is passed to one of these functions, this should\nalways be the clear text password - not a hashed password.
\nIf Django’s built-in validators are not sufficient, you can write your own\npassword validators. Validators are fairly simple classes. They must implement\ntwo methods:
\nvalidate(self, password, user=None): validate a password. Return\nNone if the password is valid, or raise a\nValidationError with an error message if the\npassword is not valid. You must be able to deal with user being\nNone - if that means your validator can’t run, simply return None\nfor no error.
get_help_text(): provide a help text to explain the requirements to\nthe user.
Any items in the OPTIONS in AUTH_PASSWORD_VALIDATORS for your\nvalidator will be passed to the constructor. All constructor arguments should\nhave a default value.
Here’s a basic example of a validator, with one optional setting:
\nfrom django.core.exceptions import ValidationError\nfrom django.utils.translation import ugettext as _\n\nclass MinimumLengthValidator(object):\n def __init__(self, min_length=8):\n self.min_length = min_length\n\n def validate(self, password, user=None):\n if len(password) < self.min_length:\n raise ValidationError(\n _("This password must contain at least %(min_length)d characters."),\n code='password_too_short',\n params={'min_length': self.min_length},\n )\n\n def get_help_text(self):\n return _(\n "Your password must contain at least %(min_length)d characters."\n % {'min_length': self.min_length}\n )\nYou can also implement password_changed(password, user=None), which will\nbe called after a successful password change. That can be used to prevent\npassword reuse, for example. However, if you decide to store a user’s previous\npasswords, you should never do so in clear text.