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.
For storing passwords, Django will use the first hasher in\nPASSWORD_HASHERS. To store new passwords with a different algorithm,\nput your preferred algorithm first in PASSWORD_HASHERS.
For verifying passwords, Django will find the hasher in the list that matches\nthe algorithm name in the stored password. If a stored password names an\nalgorithm not found in PASSWORD_HASHERS, trying to verify it will\nraise ValueError.
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.ScryptPasswordHasher",\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. The default variant for the Argon2 password hasher is\nArgon2id.
\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 Argon2id as your default storage algorithm, do the following:
\nInstall the argon2-cffi package. This can be done by running\npython -m pip install django[argon2], which is equivalent to\npython -m pip install argon2-cffi (along with any version requirement\nfrom Django’s pyproject.toml).
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.ScryptPasswordHasher",\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 package. This can be done by running\npython -m pip install django[bcrypt], which is equivalent to\npython -m pip install bcrypt (along with any version requirement from\nDjango’s pyproject.toml).
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.PBKDF2PasswordHasher",\n "django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher",\n "django.contrib.auth.hashers.Argon2PasswordHasher",\n "django.contrib.auth.hashers.ScryptPasswordHasher",\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.
\nscrypt with DjangoLink to this heading#scrypt is similar to PBKDF2 and bcrypt in utilizing a set number of iterations\nto slow down brute-force attacks. However, because PBKDF2 and bcrypt do not\nrequire a lot of memory, attackers with sufficient resources can launch\nlarge-scale parallel attacks in order to speed up the attacking process.\nscrypt is specifically designed to use more memory compared to other\npassword-based key derivation functions in order to limit the amount of\nparallelism an attacker can use, see RFC 7914 for more details.
\nTo use scrypt as your default storage algorithm, do the following:
\nModify PASSWORD_HASHERS to list ScryptPasswordHasher first.\nThat is, in your settings file:
PASSWORD_HASHERS = [\n "django.contrib.auth.hashers.ScryptPasswordHasher",\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]\nKeep and/or add any entries in this list if you need Django to upgrade\npasswords.
\nMost password hashes include a salt along with their password hash in order to\nprotect against rainbow table attacks. The salt itself is a random value which\nincreases the size and thus the cost of the rainbow table and is currently set\nat 128 bits with the salt_entropy value in the BasePasswordHasher. As\ncomputing and storage costs decrease this value should be raised. When\nimplementing your own password hasher you are free to override this value in\norder to use a desired entropy level for your password hashes. salt_entropy\nis measured in bits.
The 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\nso, you’ll subclass the appropriate algorithm and override the iterations\nparameter (use the rounds parameter when subclassing a bcrypt hasher). For\nexample, to increase the number of iterations used by the default PBKDF2\nalgorithm:
Create a subclass of django.contrib.auth.hashers.PBKDF2PasswordHasher
from django.contrib.auth.hashers import PBKDF2PasswordHasher\n\n\nclass MyPBKDF2PasswordHasher(PBKDF2PasswordHasher):\n """\n A subclass of PBKDF2PasswordHasher that uses 100 times more iterations.\n """\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.ScryptPasswordHasher",\n]\nThat’s it – now your Django install will use more iterations when it\nstores passwords using PBKDF2.
\n\nArgon2 has the following 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.
scryptLink to this heading#scrypt has the following attributes that can be customized:
\nwork_factor controls the number of iterations within the hash and the\nsize of memory for computation (N). It must be a power of 2.
block_size controls the internal block size (r), tuning the algorithm\nto memory latency.
parallelism controls how many independent computations may run in\nparallel (p).
maxmem limits the maximum size of memory that can be used during the\ncomputation of the hash. Defaults to 0, which means the default\nlimitation from the OpenSSL library.
We’ve chosen reasonable defaults, but you may wish to tune it up or down,\ndepending on your security needs and available processing power and memory.
\n\nWhen 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, bcrypt\nrounds, or argon2 attributes.
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.
\nIf you have an existing database with an older, weak hash such as MD5, you\nmight want to upgrade those hashes yourself instead of waiting for the upgrade\nto happen when a user logs in (which may never happen if a user doesn’t return\nto your site). In this case, you can use a «wrapped» password hasher.
\nFor this example, we’ll migrate a collection of MD5 hashes to use\nPBKDF2(MD5(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,\n MD5PasswordHasher,\n)\n\n\nclass PBKDF2WrappedMD5PasswordHasher(PBKDF2PasswordHasher):\n algorithm = "pbkdf2_wrapped_md5"\n\n def encode_md5_hash(self, md5_hash, salt, iterations=None):\n return super().encode(md5_hash, salt, iterations)\n\n def encode(self, password, salt, iterations=None):\n _, _, md5_hash = MD5PasswordHasher().encode(password, salt).split("$", 2)\n return self.encode_md5_hash(md5_hash, salt, iterations)\nThe data migration might look something like:
\naccounts/migrations/0002_migrate_md5_passwords.pyfrom django.db import migrations\n\nfrom ..hashers import PBKDF2WrappedMD5PasswordHasher\n\n\ndef forwards_func(apps, schema_editor):\n User = apps.get_model("auth", "User")\n users = User.objects.filter(password__startswith="md5$")\n hasher = PBKDF2WrappedMD5PasswordHasher()\n for user in users:\n algorithm, salt, md5_hash = user.password.split("$", 2)\n user.password = hasher.encode_md5_hash(md5_hash, salt)\n user.save(update_fields=["password"])\n\n\nclass Migration(migrations.Migration):\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.PBKDF2WrappedMD5PasswordHasher",\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.ScryptPasswordHasher",\n "django.contrib.auth.hashers.MD5PasswordHasher",\n]\nThe corresponding algorithm names are:
\npbkdf2_sha256
pbkdf2_sha1
argon2
bcrypt_sha256
bcrypt
scrypt
md5
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 passwords. You can use them independently\nfrom the User model.
Asynchronous version: acheck_password()
If you’d like to manually authenticate a user by comparing a plaintext\npassword to the hashed password in the database, use the convenience\nfunction check_password(). It takes two mandatory arguments: the\nplaintext password to check, and the full value of a user’s password\nfield in the database to check against. It returns True if they match,\nFalse otherwise. Optionally, you can pass a callable setter that\ntakes the password and will be called when you need to regenerate it. You\ncan also pass preferred to change a hashing algorithm if you don’t want\nto use the default (first entry of PASSWORD_HASHERS setting). See\nIncluded hashers for the algorithm name of each hasher.
Creates a hashed password in the format used by this application. It takes\none mandatory argument: the plaintext password (string or bytes).\nOptionally, you can provide a salt and a hashing algorithm to use, if you\ndon’t want to use the defaults (first entry of PASSWORD_HASHERS\nsetting). See Included hashers for the algorithm name of each\nhasher. If the password argument is None, an unusable password is\nreturned (one that will never be accepted by check_password()).
Returns False if the password is a result of\nUser.set_unusable_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 you\ncan 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 define a callback to be notified when\nthe password for a user has been changed. Validators can also have optional\nsettings 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 set of validators is enabled by default.
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 checks whether the password meets a minimum\nlength. This validator is configured with a custom option: it now requires\nthe minimum length to be nine characters, instead of the default eight.
CommonPasswordValidator, which checks whether the password occurs in a\nlist of common passwords. By default, it compares to an included list of\n20,000 common passwords.
NumericPasswordValidator, which checks whether the password isn’t\nentirely numeric.
For UserAttributeSimilarityValidator and CommonPasswordValidator,\nwe’re using the default settings in this example. NumericPasswordValidator\nhas 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 that the password is of a minimum length.\nThe minimum length can be customized with the min_length parameter.
A hook for customizing the ValidationError error message. Defaults\nto "This password is too short. It must contain at least <min_length>\ncharacters.".
A hook for customizing the validator’s help text. Defaults to "Your\npassword must contain at least <min_length> characters.".
Validates that 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 allowed similarity of passwords can be set on a scale of 0.1\nto 1.0 with the max_similarity parameter. This is compared to the\nresult of difflib.SequenceMatcher.quick_ratio(). A value of 0.1\nrejects passwords unless they are substantially different from the\nuser_attributes, whereas a value of 1.0 rejects only passwords that are\nidentical to an attribute’s value.
A hook for customizing the ValidationError error message. Defaults\nto "The password is too similar to the <user_attribute>.".
A hook for customizing the validator’s help text. Defaults to "Your\npassword can’t be too similar to your other personal information.".
Validates that the password is not a common password. This converts the\npassword to lowercase (to do a case-insensitive comparison) and checks it\nagainst a list of 20,000 common passwords created by Royce Williams.
\nThe password_list_path can be set to the path of a custom file of\ncommon passwords. This file should contain one lowercase password per line\nand may be plain text or gzipped.
A hook for customizing the ValidationError error message. Defaults\nto "This password is too common.".
A hook for customizing the validator’s help text. Defaults to "Your\npassword can’t be a commonly used password.".
Validate that the password is not entirely numeric.
\nA hook for customizing the ValidationError error message. Defaults\nto "This password is entirely numeric.".
A hook for customizing the validator’s help text. Defaults to "Your\npassword can’t be entirely numeric.".
There 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 have a fairly small interface. They must\nimplement two 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, return None for no\nerror.
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 gettext as _\n\n\nclass MinimumLengthValidator:\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.